Merge pull request #313 from mofeng-git/dev

Dev

.github/workflows/build.yml

@@ -34,13 +34,11 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: npm
-          cache-dependency-path: web/package-lock.json
 
       - name: Build frontend
         working-directory: web
         run: |
-          npm ci
+          npm install
           npm run build
 
       - name: Upload frontend dist
@@ -66,8 +64,16 @@ jobs:
 
       - uses: dtolnay/rust-toolchain@stable
 
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          # The Docker workflow builds the same targets with the same Cross images.
+          shared-key: linux-cross-release
+          key: ${{ hashFiles('Cross.toml', 'build/cross/Dockerfile.*') }}
+          cache-all-crates: true
+
       - name: Install cross
-        run: cargo install cross --locked
+        run: cargo install cross --version 0.2.5 --locked
 
       - name: Build linux binary
         run: bash build/build-images.sh
@@ -127,6 +133,12 @@ jobs:
           "TURBOJPEG_LIB_DIR=$env:TURBOJPEG_LIB_DIR" | Out-File -FilePath $env:GITHUB_ENV -Append
           "TURBOJPEG_INCLUDE_DIR=$env:TURBOJPEG_INCLUDE_DIR" | Out-File -FilePath $env:GITHUB_ENV -Append
 
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: windows-msvc-release
+          key: ${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json') }}
+
       - name: Build Windows exe
         shell: pwsh
         run: .\build\windows\build.ps1 -Configuration release -Package

.github/workflows/docker.yml

@@ -37,21 +37,27 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 24
-          cache: npm
-          cache-dependency-path: web/package-lock.json
 
       - uses: dtolnay/rust-toolchain@stable
 
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          # Reuse dependency artifacts produced by the deb job and vice versa.
+          shared-key: linux-cross-release
+          key: ${{ hashFiles('Cross.toml', 'build/cross/Dockerfile.*') }}
+          cache-all-crates: true
+
       - name: Install build dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y unzip xz-utils
-          cargo install cross --locked
+          cargo install cross --version 0.2.5 --locked
 
       - name: Build frontend
         working-directory: web
         run: |
-          npm ci
+          npm install
           npm run build
 
       - name: Set up QEMU

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "one-kvm"
-version = "0.2.5"
+version = "0.2.7"
 edition = "2021"
 authors = ["SilentWind"]
 description = "A open and lightweight IP-KVM solution written in Rust"
-license = "GPL-2.0"
+license = "AGPL-3.0-only"
 repository = "https://github.com/mofeng-git/One-KVM"
 keywords = ["kvm", "ipkvm", "remote-management", "embedded"]
 categories = ["embedded", "network-programming"]
@@ -69,6 +69,7 @@ desktop = [
     "dep:v4l2r",
     "dep:alsa",
     "dep:gpio-cdev",
+    "dep:one-kvm-bluetooth-hid",
     "dep:cpal",
     "dep:windows-sys",
 ]
@@ -177,6 +178,8 @@ turbojpeg = { version = "1.3", optional = true }
 audiopus = { version = "0.2", optional = true }
 
 [target.'cfg(target_os = "linux")'.dependencies]
+one-kvm-bluetooth-hid = { path = "libs/bluetooth-hid", optional = true }
+
 # Utilities
 nix = { version = "0.31", default-features = false, features = ["fs", "socket", "net", "hostname", "poll"], optional = true }
 

Cross.toml

@@ -1,5 +1,5 @@
 # Cross-compilation configuration for One-KVM
-# Uses pre-built custom Debian 11 based images for consistent build/runtime environment
+# Uses pre-built custom Debian 12 based images for consistent build/runtime environment
 # See: https://github.com/cross-rs/cross
 
 [build]

LICENSE

@@ -1,5 +1,5 @@
-                    GNU GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
 
  Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
@@ -7,17 +7,15 @@
 
                             Preamble
 
-  The GNU General Public License is a free, copyleft license for
-software and other kinds of works.
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
 
   The licenses for most software and other practical works are designed
 to take away your freedom to share and change the works.  By contrast,
-the GNU General Public License is intended to guarantee your freedom to
+our General Public Licenses are intended to guarantee your freedom to
 share and change all versions of a program--to make sure it remains free
-software for all its users.  We, the Free Software Foundation, use the
-GNU General Public License for most of our software; it applies also to
-any other work released this way by its authors.  You can apply it to
-your programs, too.
+software for all its users.
 
   When we speak of free software, we are referring to freedom, not
 price.  Our General Public Licenses are designed to make sure that you
@@ -26,44 +24,34 @@ them if you wish), that you receive source code or can get it if you
 want it, that you can change the software or use pieces of it in new
 free programs, and that you know you can do these things.
 
-  To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights.  Therefore, you have
-certain responsibilities if you distribute copies of the software, or if
-you modify it: responsibilities to respect the freedom of others.
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
 
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received.  You must make sure that they, too, receive
-or can get the source code.  And you must show them these terms so they
-know their rights.
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
 
-  Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
 
-  For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software.  For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
-  Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the manufacturer
-can do so.  This is fundamentally incompatible with the aim of
-protecting users' freedom to change the software.  The systematic
-pattern of such abuse occurs in the area of products for individuals to
-use, which is precisely where it is most unacceptable.  Therefore, we
-have designed this version of the GPL to prohibit the practice for those
-products.  If such problems arise substantially in other domains, we
-stand ready to extend this provision to those domains in future versions
-of the GPL, as needed to protect the freedom of users.
-
-  Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish to
-avoid the special danger that patents applied to a free program could
-make it effectively proprietary.  To prevent this, the GPL assures that
-patents cannot be used to render the program non-free.
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
 
   The precise terms and conditions for copying, distribution and
 modification follow.
@@ -72,7 +60,7 @@ modification follow.
 
   0. Definitions.
 
-  "This License" refers to version 3 of the GNU General Public License.
+  "This License" refers to version 3 of the GNU Affero General Public License.
 
   "Copyright" also means copyright-like laws that apply to other kinds of
 works, such as semiconductor masks.
@@ -549,35 +537,45 @@ to collect a royalty for further conveying from those to whom you convey
 the Program, the only way you could satisfy both those terms and this
 License would be to refrain entirely from conveying the Program.
 
-  13. Use with the GNU Affero General Public License.
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
 
   Notwithstanding any other provision of this License, you have
 permission to link or combine any covered work with a work licensed
-under version 3 of the GNU Affero General Public License into a single
+under version 3 of the GNU General Public License into a single
 combined work, and to convey the resulting work.  The terms of this
 License will continue to apply to the part which is the covered work,
-but the special requirements of the GNU Affero General Public License,
-section 13, concerning interaction through a network will apply to the
-combination as such.
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
 
   14. Revised Versions of this License.
 
   The Free Software Foundation may publish revised and/or new versions of
-the GNU General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
 address new problems or concerns.
 
   Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU General
+Program specifies that a certain numbered version of the GNU Affero General
 Public License "or any later version" applies to it, you have the
 option of following the terms and conditions either of that numbered
 version or of any later version published by the Free Software
 Foundation.  If the Program does not specify a version number of the
-GNU General Public License, you may choose any version ever published
+GNU Affero General Public License, you may choose any version ever published
 by the Free Software Foundation.
 
   If the Program specifies that a proxy can decide which future
-versions of the GNU General Public License can be used, that proxy's
+versions of the GNU Affero General Public License can be used, that proxy's
 public statement of acceptance of a version permanently authorizes you
 to choose that version for the Program.
 
@@ -635,40 +633,29 @@ the "copyright" line and a pointer to where the full notice is found.
     Copyright (C) <year>  <name of author>
 
     This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
+    it under the terms of the GNU Affero General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
 
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
+    GNU Affero General Public License for more details.
 
-    You should have received a copy of the GNU General Public License
+    You should have received a copy of the GNU Affero General Public License
     along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Also add information on how to contact you by electronic and paper mail.
 
-  If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-    <program>  Copyright (C) <year>  <name of author>
-    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, your program's commands
-might be different; for a GUI interface, you would use an "about box".
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
 
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
+For more information on this, and how to apply and follow the GNU AGPL, see
 <https://www.gnu.org/licenses/>.
-
-  The GNU General Public License does not permit incorporating your program
-into proprietary programs.  If your program is a subroutine library, you
-may consider it more useful to permit linking proprietary applications with
-the library.  If this is what you want to do, use the GNU Lesser General
-Public License instead of this License.  But first, please read
-<https://www.gnu.org/licenses/why-not-lgpl.html>.

build/Dockerfile.runtime

@@ -1,24 +1,35 @@
 # One-KVM Runtime Image
 # This Dockerfile only packages pre-compiled binaries (no compilation)
 # Used after cross-compiling with `cross build`
-# Using Debian 11 for maximum compatibility (GLIBC 2.31)
+# Using Debian 12 to match the build images (GLIBC 2.36)
 
 ARG TARGETPLATFORM=linux/amd64
 
-FROM debian:11-slim
+FROM debian:12-slim
 
 ARG TARGETPLATFORM
+ARG APT_MIRROR=
 
 # Install runtime dependencies in a single layer
 # All codec libraries (libx264, libx265, libopus) are now statically linked
 # Only hardware acceleration drivers and core system libraries remain dynamic
-RUN sed -i 's/ main$/ main contrib non-free/' /etc/apt/sources.list && \
+# Set APT_MIRROR=mirrors.tuna.tsinghua.edu.cn to speed up builds in China
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i "s@deb.debian.org@${APT_MIRROR}@g" /etc/apt/sources.list.d/debian.sources; \
+    fi \
+    && sed -i 's/^Components: main$/Components: main contrib non-free non-free-firmware/' /etc/apt/sources.list.d/debian.sources && \
     apt-get update && \
     apt-get install -y --no-install-recommends \
         # Core runtime (all platforms) - no codec libs needed
         ca-certificates \
+        # Bluetooth HID uses the host BlueZ system bus; btmgmt manages a dedicated adapter.
+        bluez \
         libudev1 \
         libasound2 \
+        # OTG Ethernet bridge control (nmcli talks to the host NetworkManager over D-Bus)
+        network-manager \
+        iproute2 \
+        iputils-ping \
         # v4l2 is handled by kernel, minimal userspace needed
         libv4l-0 \
         && \

build/Dockerfile.runtime-full

@@ -1,24 +1,35 @@
 # One-KVM Runtime Image (full)
 # This Dockerfile only packages pre-compiled binaries (no compilation)
 # Used after cross-compiling with `cross build`
-# Using Debian 11 for maximum compatibility (GLIBC 2.31)
+# Using Debian 12 to match the build images (GLIBC 2.36)
 
 ARG TARGETPLATFORM=linux/amd64
 
-FROM debian:11-slim
+FROM debian:12-slim
 
 ARG TARGETPLATFORM
+ARG APT_MIRROR=
 
 # Install runtime dependencies in a single layer
 # All codec libraries (libx264, libx265, libopus) are now statically linked
 # Only hardware acceleration drivers and core system libraries remain dynamic
-RUN sed -i 's/ main$/ main contrib non-free/' /etc/apt/sources.list && \
+# Set APT_MIRROR=mirrors.tuna.tsinghua.edu.cn to speed up builds in China
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i "s@deb.debian.org@${APT_MIRROR}@g" /etc/apt/sources.list.d/debian.sources; \
+    fi \
+    && sed -i 's/^Components: main$/Components: main contrib non-free non-free-firmware/' /etc/apt/sources.list.d/debian.sources && \
     apt-get update && \
     apt-get install -y --no-install-recommends \
         # Core runtime (all platforms) - no codec libs needed
         ca-certificates \
+        # Bluetooth HID uses the host BlueZ system bus; btmgmt manages a dedicated adapter.
+        bluez \
         libudev1 \
         libasound2 \
+        # OTG Ethernet bridge control (nmcli talks to the host NetworkManager over D-Bus)
+        network-manager \
+        iproute2 \
+        iputils-ping \
         # v4l2 is handled by kernel, minimal userspace needed
         libv4l-0 \
         && \

build/build-images.sh

@@ -21,21 +21,25 @@ build_arch() {
 
     case "${CHINAMIRRO:-}" in
         1|true|TRUE|yes|YES|on|ON)
-            local cross_build_opts="${CROSS_BUILD_OPTS:+$CROSS_BUILD_OPTS }--progress=plain --build-arg CHINAMIRRO=1 --build-arg GH_PROXY=${GH_PROXY:-https://gh-proxy.com/} --build-arg DEBIAN_IMAGE=${DEBIAN_IMAGE:-docker.1ms.run/library/debian:11}"
+            # Default Rust toolchain mirror is USTC (rsproxy.cn is unreachable via the
+            # Docker bridge on some networks because its CDN blocks the SNAT source IP).
+            local rust_dist="${RUSTUP_DIST_SERVER_MIRROR:-https://mirrors.ustc.edu.cn/rust-static}"
+            local rust_root="${RUSTUP_UPDATE_ROOT_MIRROR:-https://mirrors.ustc.edu.cn/rust-static/rustup}"
+            local crates_sparse="${CARGO_SPARSE_MIRROR:-sparse+https://mirrors.ustc.edu.cn/crates.io-index/}"
+            local crates_git="${CARGO_GIT_MIRROR:-https://mirrors.ustc.edu.cn/crates.io-index}"
+            local cross_build_opts="${CROSS_BUILD_OPTS:+$CROSS_BUILD_OPTS }--progress=plain --build-arg CHINAMIRRO=1 --build-arg GH_PROXY=${GH_PROXY:-https://ghfast.top/} --build-arg DEBIAN_IMAGE=${DEBIAN_IMAGE:-dockerproxy.net/library/debian:12}"
             cross_build_opts="$cross_build_opts --build-arg HTTP_PROXY= --build-arg HTTPS_PROXY= --build-arg ALL_PROXY= --build-arg NO_PROXY="
             cross_build_opts="$cross_build_opts --build-arg http_proxy= --build-arg https_proxy= --build-arg all_proxy= --build-arg no_proxy="
             echo "=== China mirror acceleration: enabled ==="
             echo "=== Building: $rust_target (via cross with custom Dockerfile) ==="
             env \
                 CROSS_BUILD_OPTS="$cross_build_opts" \
-                CARGO_SOURCE_CRATES_IO_REPLACE_WITH=rsproxy-sparse \
-                CARGO_SOURCE_RSPROXY_REGISTRY=https://rsproxy.cn/crates.io-index \
-                CARGO_SOURCE_RSPROXY_SPARSE_REGISTRY=sparse+https://rsproxy.cn/index/ \
-                CARGO_REGISTRIES_RSPROXY_INDEX=https://rsproxy.cn/crates.io-index \
+                CARGO_SOURCE_CRATES_IO_REPLACE_WITH=cn-mirror \
+                CARGO_SOURCE_CN-MIRROR_REGISTRY="$crates_sparse" \
                 CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse \
                 CARGO_NET_GIT_FETCH_WITH_CLI=true \
-                RUSTUP_DIST_SERVER=https://rsproxy.cn \
-                RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup \
+                RUSTUP_DIST_SERVER="$rust_dist" \
+                RUSTUP_UPDATE_ROOT="$rust_root" \
                 cross build --release --target "$rust_target"
             return
             ;;

build/cross/Dockerfile.arm64

@@ -1,15 +1,15 @@
-# Cross-compilation image for ARM64 based on Debian 11
-# Build on Debian 11 (GLIBC 2.31) for maximum runtime compatibility
+# Cross-compilation image for ARM64 based on Debian 12
+# Build on Debian 12 (GLIBC 2.36) to match the runtime images
 
-ARG DEBIAN_IMAGE=debian:11
+ARG DEBIAN_IMAGE=debian:12
 FROM ${DEBIAN_IMAGE}
 
 ARG CHINAMIRRO=0
 ARG GH_PROXY=https://gh-proxy.com/
-ARG RUSTUP_DIST_SERVER_CN=https://rsproxy.cn
-ARG RUSTUP_UPDATE_ROOT_CN=https://rsproxy.cn/rustup
-ARG CARGO_INDEX_CN=https://rsproxy.cn/crates.io-index
-ARG CARGO_REGISTRY_CN=sparse+https://rsproxy.cn/index/
+ARG RUSTUP_DIST_SERVER_CN=https://mirrors.ustc.edu.cn/rust-static
+ARG RUSTUP_UPDATE_ROOT_CN=https://mirrors.ustc.edu.cn/rust-static/rustup
+ARG CARGO_INDEX_CN=https://mirrors.ustc.edu.cn/crates.io-index
+ARG CARGO_REGISTRY_CN=sparse+https://mirrors.ustc.edu.cn/crates.io-index/
 ARG LIBJPEG_TURBO_VERSION=3.1.4.1
 ARG LIBYUV_REV=957f295ea946cbbd13fcfc46e7066f2efa801233
 ARG LIBVPX_VERSION=1.16.0
@@ -22,8 +22,8 @@ ARG FFMPEG_ROCKCHIP_REV=40c412daccf08164493da0de990eb99a8948116b
 # Optionally use China mirrors for builds in China.
 RUN if [ "$CHINAMIRRO" = "1" ]; then \
         sed -i -E \
-            -e 's|http://deb.debian.org/debian([[:space:]])|http://mirrors.tuna.tsinghua.edu.cn/debian\1|g' \
-            /etc/apt/sources.list; \
+            -e 's@http://deb.debian.org/debian([[:space:]]|$)@http://mirrors.tuna.tsinghua.edu.cn/debian\1@g' \
+            /etc/apt/sources.list.d/debian.sources; \
     fi
 
 # Install Rust toolchain
@@ -39,12 +39,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         mkdir -p /root/.cargo; \
         printf '%s\n' \
             '[source.crates-io]' \
-            "replace-with = 'rsproxy-sparse'" \
-            '[source.rsproxy]' \
+            "replace-with = 'cn-mirror-sparse'" \
+            '[source.cn-mirror]' \
             "registry = '${CARGO_INDEX_CN}'" \
-            '[source.rsproxy-sparse]' \
+            '[source.cn-mirror-sparse]' \
             "registry = '${CARGO_REGISTRY_CN}'" \
-            '[registries.rsproxy]' \
+            '[registries.cn-mirror]' \
             "index = '${CARGO_INDEX_CN}'" \
             '[net]' \
             'git-fetch-with-cli = true' \
@@ -83,8 +83,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 # Install ARM64 development libraries (without VAAPI/X11 for ARM)
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libssl1.1 \
-    libssl1.1:arm64 \
+    libssl3 \
+    libssl3:arm64 \
     libasound2-dev:arm64 \
     libv4l-dev:arm64 \
     libudev-dev:arm64 \

build/cross/Dockerfile.armv7

@@ -1,15 +1,15 @@
-# Cross-compilation image for ARMv7 based on Debian 11
-# Build on Debian 11 (GLIBC 2.31) for maximum runtime compatibility
+# Cross-compilation image for ARMv7 based on Debian 12
+# Build on Debian 12 (GLIBC 2.36) to match the runtime images
 
-ARG DEBIAN_IMAGE=debian:11
+ARG DEBIAN_IMAGE=debian:12
 FROM ${DEBIAN_IMAGE}
 
 ARG CHINAMIRRO=0
 ARG GH_PROXY=https://gh-proxy.com/
-ARG RUSTUP_DIST_SERVER_CN=https://rsproxy.cn
-ARG RUSTUP_UPDATE_ROOT_CN=https://rsproxy.cn/rustup
-ARG CARGO_INDEX_CN=https://rsproxy.cn/crates.io-index
-ARG CARGO_REGISTRY_CN=sparse+https://rsproxy.cn/index/
+ARG RUSTUP_DIST_SERVER_CN=https://mirrors.ustc.edu.cn/rust-static
+ARG RUSTUP_UPDATE_ROOT_CN=https://mirrors.ustc.edu.cn/rust-static/rustup
+ARG CARGO_INDEX_CN=https://mirrors.ustc.edu.cn/crates.io-index
+ARG CARGO_REGISTRY_CN=sparse+https://mirrors.ustc.edu.cn/crates.io-index/
 ARG LIBJPEG_TURBO_VERSION=3.1.4.1
 ARG LIBYUV_REV=957f295ea946cbbd13fcfc46e7066f2efa801233
 ARG LIBVPX_VERSION=1.16.0
@@ -22,8 +22,8 @@ ARG FFMPEG_ROCKCHIP_REV=40c412daccf08164493da0de990eb99a8948116b
 # Optionally use China mirrors for builds in China.
 RUN if [ "$CHINAMIRRO" = "1" ]; then \
         sed -i -E \
-            -e 's|http://deb.debian.org/debian([[:space:]])|http://mirrors.tuna.tsinghua.edu.cn/debian\1|g' \
-            /etc/apt/sources.list; \
+            -e 's@http://deb.debian.org/debian([[:space:]]|$)@http://mirrors.tuna.tsinghua.edu.cn/debian\1@g' \
+            /etc/apt/sources.list.d/debian.sources; \
     fi
 
 # Install Rust toolchain
@@ -39,12 +39,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         mkdir -p /root/.cargo; \
         printf '%s\n' \
             '[source.crates-io]' \
-            "replace-with = 'rsproxy-sparse'" \
-            '[source.rsproxy]' \
+            "replace-with = 'cn-mirror-sparse'" \
+            '[source.cn-mirror]' \
             "registry = '${CARGO_INDEX_CN}'" \
-            '[source.rsproxy-sparse]' \
+            '[source.cn-mirror-sparse]' \
             "registry = '${CARGO_REGISTRY_CN}'" \
-            '[registries.rsproxy]' \
+            '[registries.cn-mirror]' \
             "index = '${CARGO_INDEX_CN}'" \
             '[net]' \
             'git-fetch-with-cli = true' \
@@ -83,8 +83,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 # Install ARMv7 development libraries (without VAAPI/X11 for ARM)
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libssl1.1 \
-    libssl1.1:armhf \
+    libssl3 \
+    libssl3:armhf \
     libasound2-dev:armhf \
     libv4l-dev:armhf \
     libudev-dev:armhf \

build/cross/Dockerfile.x86_64

@@ -1,15 +1,15 @@
-# Cross-compilation image for x86_64 based on Debian 11
-# Build on Debian 11 (GLIBC 2.31) for maximum runtime compatibility
+# Cross-compilation image for x86_64 based on Debian 12
+# Build on Debian 12 (GLIBC 2.36) to match the runtime images
 
-ARG DEBIAN_IMAGE=debian:11
+ARG DEBIAN_IMAGE=debian:12
 FROM ${DEBIAN_IMAGE}
 
 ARG CHINAMIRRO=0
 ARG GH_PROXY=https://gh-proxy.com/
-ARG RUSTUP_DIST_SERVER_CN=https://rsproxy.cn
-ARG RUSTUP_UPDATE_ROOT_CN=https://rsproxy.cn/rustup
-ARG CARGO_INDEX_CN=https://rsproxy.cn/crates.io-index
-ARG CARGO_REGISTRY_CN=sparse+https://rsproxy.cn/index/
+ARG RUSTUP_DIST_SERVER_CN=https://mirrors.ustc.edu.cn/rust-static
+ARG RUSTUP_UPDATE_ROOT_CN=https://mirrors.ustc.edu.cn/rust-static/rustup
+ARG CARGO_INDEX_CN=https://mirrors.ustc.edu.cn/crates.io-index
+ARG CARGO_REGISTRY_CN=sparse+https://mirrors.ustc.edu.cn/crates.io-index/
 ARG LIBJPEG_TURBO_VERSION=3.1.4.1
 ARG LIBYUV_REV=957f295ea946cbbd13fcfc46e7066f2efa801233
 ARG LIBVPX_VERSION=1.16.0
@@ -20,8 +20,8 @@ ARG FFMPEG_ROCKCHIP_REV=40c412daccf08164493da0de990eb99a8948116b
 # Optionally use China mirrors for builds in China.
 RUN if [ "$CHINAMIRRO" = "1" ]; then \
         sed -i -E \
-            -e 's|http://deb.debian.org/debian([[:space:]])|http://mirrors.tuna.tsinghua.edu.cn/debian\1|g' \
-            /etc/apt/sources.list; \
+            -e 's@http://deb.debian.org/debian([[:space:]]|$)@http://mirrors.tuna.tsinghua.edu.cn/debian\1@g' \
+            /etc/apt/sources.list.d/debian.sources; \
     fi
 
 # Install Rust toolchain
@@ -37,12 +37,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         mkdir -p /root/.cargo; \
         printf '%s\n' \
             '[source.crates-io]' \
-            "replace-with = 'rsproxy-sparse'" \
-            '[source.rsproxy]' \
+            "replace-with = 'cn-mirror-sparse'" \
+            '[source.cn-mirror]' \
             "registry = '${CARGO_INDEX_CN}'" \
-            '[source.rsproxy-sparse]' \
+            '[source.cn-mirror-sparse]' \
             "registry = '${CARGO_REGISTRY_CN}'" \
-            '[registries.rsproxy]' \
+            '[registries.cn-mirror]' \
             "index = '${CARGO_INDEX_CN}'" \
             '[net]' \
             'git-fetch-with-cli = true' \

build/debian/control.tpl

@@ -6,6 +6,7 @@ Maintainer: SilentWind <admin@mofeng.run>
 Package: one-kvm
 Architecture: {arch}
 Depends: ${{auto}}, ca-certificates{distsuffix}
+Recommends: bluez
 Description: A open and lightweight IP-KVM solution written in Rust
  Enables BIOS-level remote management of servers and workstations.
  .
@@ -17,6 +18,7 @@ Description: A open and lightweight IP-KVM solution written in Rust
   * Hardware-accelerated video encoding (VAAPI, QSV, RKMPP)
   * WebRTC and MJPEG streaming with low latency
   * USB HID emulation via OTG gadget
+  * Classic Bluetooth keyboard and mouse via BlueZ
   * Mass storage device for ISO/IMG mounting
   * ATX power control via GPIO or USB relay
 Homepage: https://github.com/mofeng-git/One-KVM

build/debian/copyright

@@ -1,16 +1,130 @@
 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: one-kvm
-Source: https://github.com/mofeng-git/one-KVM
+Upstream-Contact: https://github.com/mofeng-git/One-KVM/issues
+Source: https://github.com/mofeng-git/One-KVM
 
 Files: *
 Copyright: 2025 One-KVM contributors
-License: GPL-2.0
+License: AGPL-3.0-only
+
+Files: protos/*
+Copyright: the RustDesk contributors
+           2025 One-KVM contributors
+License: AGPL-3.0-only
+Comment:
+ Protocol definition files derived from RustDesk
+ (https://github.com/rustdesk/rustdesk). Modified for One-KVM.
+ See protos/NOTICE for the full attribution.
+
+Files: src/rustdesk/*
+Copyright: the RustDesk contributors
+           2025 One-KVM contributors
+License: AGPL-3.0-only
+Comment:
+ Code derived from the RustDesk project, modified for One-KVM.
+ See src/rustdesk/NOTICE for the full attribution.
+
+Files: libs/hwcodec/*
+Copyright: the RustDesk contributors
+           2025 One-KVM contributors
+License: AGPL-3.0-only
+Comment:
+ Derived from the RustDesk hwcodec component. See libs/hwcodec/NOTICE.
+
+Files: libs/v4l2r/*
+Copyright: 2023-2024 Andrei Lytkin, Daniel Almeida, Collabora Ltd. and other v4l2r contributors
+License: Expat
 
 Files: libs/ventoy-img-rs/resources/*
 Copyright: Ventoy contributors
-License: GPL-2.0
+License: GPL-3.0+
+Comment:
+ Pre-built Ventoy boot files (boot.img, core.img.xz, ventoy.disk.img.xz).
+ Ventoy upstream: https://github.com/ventoy/Ventoy, licensed GPL-3.0-or-later.
 
-License: GPL-2.0
+Files: res/vcpkg/libyuv/*
+Copyright: The LibYuv Project Authors
+License: BSD-3-Clause
+
+Files: third-party/ffmpeg
+Copyright: FFmpeg developers and contributors
+License: GPL-2.0+
+Comment:
+ FFmpeg is built with --enable-gpl --enable-version3 and linked against
+ x264/x265; the resulting build is GPL-compatible with the AGPL-3.0 main
+ program. Upstream: https://ffmpeg.org/
+ The Linux builds use nyanmisaka/ffmpeg-rockchip at the commit pinned by
+ FFMPEG_ROCKCHIP_REV in build/cross/Dockerfile.*.
+
+Files: third-party/x264
+Copyright: x264 LLC and x264 contributors
+License: GPL-2.0+
+Comment: Upstream: https://www.videolan.org/developers/x264.html
+
+Files: third-party/x265
+Copyright: MulticoreWare, Inc. and x265 contributors
+License: GPL-2.0+
+Comment: Upstream: https://www.x265.org/
+
+Files: third-party/libvpx
+Copyright: The WebM Project authors
+License: BSD-3-Clause
+Comment: Upstream: https://www.webmproject.org/code/
+
+Files: third-party/libopus
+Copyright: Opus contributors
+License: BSD-3-Clause
+Comment: Upstream: https://opus-codec.org/
+
+Files: third-party/libjpeg-turbo
+Copyright: D. R. Commander and other libjpeg-turbo contributors
+License: BSD-3-Clause
+Comment: Upstream: https://libjpeg-turbo.org/
+
+Files: third-party/libsodium
+Copyright: 2013-2025 Frank Denis
+License: Expat
+Comment: Upstream: https://libsodium.gitbook.io/
+
+Files: third-party/sqlite
+Copyright: 1994-2010 Hipp, Wyrick & Company, Inc.
+License: SQLite-public-domain
+Comment: Upstream: https://www.sqlite.org/
+
+License: AGPL-3.0-only
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+ .
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the full text of the GNU Affero General Public License
+ version 3 can be found in the file `/usr/share/common-licenses/AGPL-3'.
+
+License: GPL-3.0+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the full text of the GNU General Public License
+ version 3 can be found in the file `/usr/share/common-licenses/GPL-3'.
+
+License: GPL-2.0+
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 2 of the License, or
@@ -22,8 +136,61 @@ License: GPL-2.0
  GNU General Public License for more details.
  .
  You should have received a copy of the GNU General Public License
- along with this program.  If not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the full text of the GNU General Public License
+ version 2 can be found in the file `/usr/share/common-licenses/GPL-2'.
 
-On Debian systems, the full text of the GNU General Public License
-version 2 can be found in the file `/usr/share/common-licenses/GPL-2'.
+License: Expat
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+
+License: BSD-3-Clause
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+ .
+ 1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+ .
+ 2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+ .
+ 3. Neither the name of the copyright holder nor the names of its contributors
+ may be used to endorse or promote products derived from this software
+ without specific prior written permission.
+ .
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+
+License: SQLite-public-domain
+ The author disclaims copyright to this source code.  In place of a legal
+ notice, here is a blessing:
+ .
+ May you do good and not evil.
+ May you find forgiveness for yourself and understand yourself.
+ May you share freely, never taking more than you give.

build/one-kvm.service

@@ -1,7 +1,7 @@
 [Unit]
 Description=One-KVM IP-KVM Service
 Documentation=https://github.com/mofeng-git/One-KVM
-After=network-online.target
+After=network-online.target bluetooth.service
 Wants=network-online.target
 
 [Service]

build/package-deb.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Build deb packages from pre-compiled binaries
-# Binaries are compiled once on Debian 11 (GLIBC 2.31) via build-images.sh
+# Binaries are compiled once on Debian 12 (GLIBC 2.36) via build-images.sh
 # This script packages them directly on the host using dpkg-deb
 # Usage: ./build/build-deb.sh [arch]
 # Example: ./build/build-deb.sh aarch64
@@ -125,7 +125,7 @@ EOF
     chmod 755 "$PKG_DIR/DEBIAN/prerm"
 
     # Create control file
-    BASE_DEPS="libc6 (>= 2.31), libgcc-s1, libstdc++6, libasound2t64 (>= 1.1) | libasound2 (>= 1.1), libdrm2 (>= 2.4)"
+    BASE_DEPS="libc6 (>= 2.36), libgcc-s1, libstdc++6, libasound2t64 (>= 1.1) | libasound2 (>= 1.1), libdrm2 (>= 2.4)"
     AMD64_DEPS="libva2 (>= 2.0), libva-drm2 (>= 2.10), libva-x11-2 (>= 2.10), libmfx-gen1.2 (>= 22.0) | libmfx1 (>= 21.1), libx11-6 (>= 1.6), libxcb1 (>= 1.14), i965-va-driver-shaders (>= 2.4), intel-media-va-driver-non-free (>= 21.1)"
     DEPS="$BASE_DEPS"
     if [ "$DEB_ARCH" = "amd64" ]; then
@@ -139,10 +139,11 @@ Section: admin
 Priority: optional
 Architecture: $DEB_ARCH
 Depends: $DEPS
+Recommends: bluez
 Maintainer: SilentWind <admin@mofeng.run>
 Description: A open and lightweight IP-KVM solution
  Enables BIOS-level remote management of servers and workstations.
- Built on Debian 11, compatible with Debian 11+, Ubuntu 20.04+.
+ Built on Debian 12, compatible with Debian 12+, Ubuntu 24.04+.
 EOF
 
     # Build deb directly on host

build/package-docker.sh

@@ -204,9 +204,21 @@ get_tool_urls() {
 }
 
 # Download tools for a platform
+# Set CURL_PROXY=http://host:port to route GitHub downloads through an HTTP proxy
+# Set GHPROXY_PREFIX=https://ghfast.top/ to prefix GitHub URLs instead
 download_tools() {
     local platform="$1"
     local staging="$2"
+    local curl_proxy=()
+    if [ -n "${CURL_PROXY:-}" ]; then
+        curl_proxy=(-x "$CURL_PROXY")
+    fi
+    dl() {
+        # dl <url> <output>
+        local url="$1"
+        [ -n "${GHPROXY_PREFIX:-}" ] && url="${GHPROXY_PREFIX%/}/$url"
+        curl -fsSL "${curl_proxy[@]}" "$url" -o "$2"
+    }
 
     get_tool_urls "$platform"
 
@@ -214,14 +226,14 @@ download_tools() {
 
     # ttyd
     if [ ! -f "$staging/ttyd" ]; then
-        curl -fsSL "$TTYD_URL" -o "$staging/ttyd"
+        dl "$TTYD_URL" "$staging/ttyd"
         chmod +x "$staging/ttyd"
     fi
 
     if [ "$INCLUDE_THIRD_PARTY" = true ]; then
         # gostc
         if [ ! -f "$staging/gostc" ]; then
-            curl -fsSL "$GOSTC_URL" -o /tmp/gostc.tar.gz
+            dl "$GOSTC_URL" /tmp/gostc.tar.gz
             tar -xzf /tmp/gostc.tar.gz -C "$staging"
             chmod +x "$staging/gostc"
             rm /tmp/gostc.tar.gz
@@ -229,7 +241,7 @@ download_tools() {
 
         # easytier
         if [ ! -f "$staging/easytier-core" ]; then
-            curl -fsSL "$EASYTIER_URL" -o /tmp/easytier.zip
+            dl "$EASYTIER_URL" /tmp/easytier.zip
             unzip -o /tmp/easytier.zip -d /tmp/easytier
             cp "/tmp/easytier/$EASYTIER_DIR/easytier-core" "$staging/easytier-core"
             chmod +x "$staging/easytier-core"
@@ -311,9 +323,16 @@ build_for_platform() {
 
     local build_cmd="docker buildx build --platform $platform"
     build_cmd="$build_cmd --build-arg TARGETPLATFORM=$platform"
+    if [ -n "${APT_MIRROR:-}" ]; then
+        build_cmd="$build_cmd --build-arg APT_MIRROR=$APT_MIRROR"
+    fi
 
     if [ "$PUSH" = true ]; then
         build_cmd="$build_cmd --push"
+        # Aliyun ACR rejects the OCI artifact manifests used by BuildKit attestations.
+        if [[ "$REGISTRY" == registry.cn-*.aliyuncs.com/* ]]; then
+            build_cmd="$build_cmd --provenance=false --sbom=false"
+        fi
     elif [ "$LOAD" = true ]; then
         build_cmd="$build_cmd --load"
     fi

docs/macos-drag-compatibility.md

@@ -0,0 +1,24 @@
+# macOS 拖拽兼容模式（实验性）
+
+适用于 OTG 和 CH9329 后端的绝对鼠标输入。遇到目标 Mac 上拖拽只能移动一小段便停止时，可在设置页的 HID 配置中开启「macOS 拖拽兼容模式」。默认关闭。
+
+配置字段为 `hid.mouse_macos_drag`，旧 PR 的 `ch9329_macos_drag` 字段仍可作为读取别名。OTG 必须同时启用相对鼠标和绝对鼠标接口，否则配置保存会被拒绝。CH9329 同时启用 Linux 兼容开关时，此模式优先。
+
+## 报告行为
+
+- 未按键时仍使用绝对坐标定位。
+- 从绝对输入开始的拖拽：按下使用绝对报告，移动和滚轮使用相对报告，释放时先更新相对按钮状态，再发送绝对按钮释放。
+- 按键报告的通道保持到所有按钮释放，不随拖拽期间的输入模式切换而改变。
+- 从相对输入开始的点击、拖拽继续使用相对按钮报告；此选项不修复原生相对模式的点击兼容问题。
+- 位移从原始 15 位输入坐标换算，累计小数余量，大位移按单包范围分包并保留总量及方向。
+- 运行时使用当前视频采集尺寸，并在 HID 重载后恢复尺寸；视频尚未提供尺寸时使用配置尺寸。
+
+## 验证范围与限制
+
+本次 OTG 扩展及位移换算修改没有 macOS 实机验证。原 PR 作者对旧 CH9329 实现的实机反馈不能视为本版本已经验证。
+
+本地自动化覆盖位移累计/分包、1080p/4K 换算、往返移动、滚轮、输入模式切换、复位、CH9329 命令队列、OTG 临时文件模拟端点及配置校验。临时文件测试仅验证写出的字节，不验证 USB 枚举或目标系统的事件解释。
+
+相对位移受 macOS 鼠标速度、加速、显示缩放及多屏布局影响，无法保证与绝对定位逐像素一致。松手报告携带最后的客户端绝对坐标，仍可能出现落点偏移或光标跳位；大位移分包也可能增加低波特率串口延迟。
+
+后续实机验证应分别覆盖两个后端：窗口/文件/文本拖拽，快速及慢速移动，滚轮和多按钮组合，1080p/4K 与缩放显示，输入模式切换、断开重连、精确落点。异常时关闭此选项恢复默认行为。

libs/bluetooth-hid/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "one-kvm-bluetooth-hid"
+version = "0.1.0"
+edition = "2021"
+license = "AGPL-3.0-only"
+
+[dependencies]
+bluer = { version = "0.17", features = ["bluetoothd", "l2cap"] }
+dbus = { version = "0.9", features = ["vendored"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "process"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+dbus-crossroads = "0.5"
+dbus-tokio = "0.7"
+libc = "0.2"
+tracing = "0.1"

libs/bluetooth-hid/examples/pairing_probe.rs

@@ -0,0 +1,49 @@
+//! Explicit hardware regression: opens a 10-second pairing window without
+//! removing existing bonds or sending input. Stop the production HID first.
+use one_kvm_bluetooth_hid::{Action, Config, Peripheral};
+use std::time::Duration;
+
+#[tokio::main]
+async fn main() -> Result<(), String> {
+    let peripheral = Peripheral::start(Config {
+        adapter: "hci0".into(),
+        name: "One-KVM HID".into(),
+        peer: None,
+    })?;
+    let result = async {
+        for _ in 0..50 {
+            if peripheral.status().initialized {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(100)).await;
+        }
+        let before = peripheral.status();
+        if !before.initialized {
+            return Err(format!("Initialization failed: {:?}", before.error));
+        }
+        if !before
+            .devices
+            .iter()
+            .any(|d| Some(&d.address) == before.peer.as_ref() && d.paired)
+        {
+            return Err("This regression needs an existing bonded computer".into());
+        }
+        peripheral.action(Action::Pair(10)).await?;
+        tokio::time::sleep(Duration::from_secs(1)).await;
+        let open = peripheral.status();
+        println!("open: {}", serde_json::to_string(&open).unwrap());
+        if open.pairing_seconds == 0 {
+            return Err("Existing bond prematurely closed pairing".into());
+        }
+        tokio::time::sleep(Duration::from_secs(10)).await;
+        let expired = peripheral.status();
+        println!("expired: {}", serde_json::to_string(&expired).unwrap());
+        if expired.pairing_seconds != 0 || expired.peer != before.peer {
+            return Err("Window did not expire while preserving the bonded peer".into());
+        }
+        Ok(())
+    }
+    .await;
+    let cleanup = peripheral.shutdown().await;
+    result.and(cleanup)
+}

libs/bluetooth-hid/examples/probe.rs

@@ -0,0 +1,24 @@
+//! Native hardware smoke check. Registers for 12 seconds, sends no input,
+//! opens no pairing window, then restores the adapter configuration.
+use one_kvm_bluetooth_hid::{Config, Peripheral};
+use std::time::Duration;
+#[tokio::main]
+async fn main() -> Result<(), String> {
+    let peripheral = Peripheral::start(Config {
+        adapter: "hci0".into(),
+        name: "One-KVM HID".into(),
+        peer: None,
+    })?;
+    let mut initialized = false;
+    for _ in 0..12 {
+        tokio::time::sleep(Duration::from_secs(1)).await;
+        let status = peripheral.status();
+        initialized |= status.initialized;
+        println!("{}", serde_json::to_string(&status).unwrap());
+    }
+    peripheral.shutdown().await?;
+    if !initialized {
+        return Err("Native BlueZ peripheral never initialized".into());
+    }
+    Ok(())
+}

libs/bluetooth-hid/src/agent.rs

@@ -0,0 +1,236 @@
+use crate::Shared;
+use dbus::{channel::MatchingReceiver, message::MatchRule, nonblock::Proxy, Path};
+use dbus_crossroads::Crossroads;
+use std::{
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+const PATH: &str = "/org/onekvm/bluetooth/agent";
+pub struct Agent {
+    connection: Arc<dbus::nonblock::SyncConnection>,
+    task: tokio::task::JoinHandle<()>,
+}
+impl Agent {
+    pub async fn register(shared: Arc<Shared>, adapter: String) -> Result<Self, String> {
+        let (resource, connection) =
+            dbus_tokio::connection::new_system_sync().map_err(|e| e.to_string())?;
+        let task = tokio::spawn(async move {
+            let _ = resource.await;
+        });
+        let mut cr = Crossroads::new();
+        let iface = cr.register("org.bluez.Agent1", |b| {
+            b.method("Release", (), (), |_, _: &mut (), ()| Ok(()));
+            b.method("Cancel", (), (), |_, _: &mut (), ()| Ok(()));
+            let state = shared.clone();
+            let name = adapter.clone();
+            b.method(
+                "RequestAuthorization",
+                ("device",),
+                (),
+                move |_, _: &mut (), (path,): (Path<'static>,)| {
+                    authorize(&state, &name, &path, true)
+                },
+            );
+            let state = shared.clone();
+            let name = adapter.clone();
+            b.method(
+                "RequestConfirmation",
+                ("device", "passkey"),
+                (),
+                move |_, _: &mut (), (path, _): (Path<'static>, u32)| {
+                    authorize(&state, &name, &path, true)
+                },
+            );
+            b.method(
+                "AuthorizeService",
+                ("device", "uuid"),
+                (),
+                move |_, _: &mut (), (path, uuid): (Path<'static>, String)| {
+                    if !matches!(uuid.as_str(), "00001124-0000-1000-8000-00805f9b34fb") {
+                        return Err(dbus::MethodErr::from((
+                            "org.bluez.Error.Rejected",
+                            "Not an HID service",
+                        )));
+                    }
+                    authorize(&shared, &adapter, &path, false)
+                },
+            );
+        });
+        cr.insert(PATH, &[iface], ());
+        let profile = cr.register("org.bluez.Profile1", |b| {
+            b.method("Release", (), (), |_, _: &mut (), ()| Ok(()));
+            b.method(
+                "RequestDisconnection",
+                ("device",),
+                (),
+                |_, _: &mut (), (_device,): (Path<'static>,)| Ok(()),
+            );
+            b.method(
+                "NewConnection",
+                ("device", "fd", "properties"),
+                (),
+                |_,
+                 _: &mut (),
+                 (_device, _fd, _props): (
+                    Path<'static>,
+                    dbus::arg::OwnedFd,
+                    dbus::arg::PropMap,
+                )| {
+                    // This profile only publishes SDP. Our L2CAP sockets own both HID channels.
+                    Err::<(), _>(dbus::MethodErr::from((
+                        "org.bluez.Error.Rejected",
+                        "Unexpected profile connection",
+                    )))
+                },
+            );
+        });
+        cr.insert("/org/onekvm/bluetooth/profile", &[profile], ());
+        connection.start_receive(
+            MatchRule::new_method_call(),
+            Box::new(move |msg, conn| {
+                let _ = cr.handle_message(msg, conn);
+                true
+            }),
+        );
+        let agent = Self { connection, task };
+        let proxy = Proxy::new(
+            "org.bluez",
+            "/org/bluez",
+            Duration::from_secs(5),
+            agent.connection.clone(),
+        );
+        let result: Result<(), dbus::Error> = proxy
+            .method_call(
+                "org.bluez.AgentManager1",
+                "RegisterAgent",
+                (Path::from(PATH), "NoInputNoOutput"),
+            )
+            .await;
+        if let Err(error) = result {
+            return Err(error.to_string());
+        }
+        let result: Result<(), dbus::Error> = proxy
+            .method_call(
+                "org.bluez.AgentManager1",
+                "RequestDefaultAgent",
+                (Path::from(PATH),),
+            )
+            .await;
+        result.map_err(|e| e.to_string())?;
+        let mut options: dbus::arg::PropMap = std::collections::HashMap::new();
+        options.insert(
+            "ServiceRecord".into(),
+            dbus::arg::Variant(Box::new(crate::protocol::sdp())),
+        );
+        options.insert(
+            "Role".into(),
+            dbus::arg::Variant(Box::new("server".to_string())),
+        );
+        options.insert(
+            "RequireAuthentication".into(),
+            dbus::arg::Variant(Box::new(true)),
+        );
+        options.insert(
+            "RequireAuthorization".into(),
+            dbus::arg::Variant(Box::new(false)),
+        );
+        let result: Result<(), dbus::Error> = proxy
+            .method_call(
+                "org.bluez.ProfileManager1",
+                "RegisterProfile",
+                (
+                    Path::from("/org/onekvm/bluetooth/profile"),
+                    crate::protocol::HID_UUID,
+                    options,
+                ),
+            )
+            .await;
+        result.map_err(|e| format!("Register HID SDP: {e}"))?;
+        Ok(agent)
+    }
+}
+impl Drop for Agent {
+    fn drop(&mut self) {
+        self.task.abort();
+    }
+}
+fn authorize(
+    shared: &Shared,
+    adapter: &str,
+    path: &str,
+    pairing: bool,
+) -> Result<(), dbus::MethodErr> {
+    let rejected = || {
+        dbus::MethodErr::from((
+            "org.bluez.Error.Rejected",
+            "Open pairing in One-KVM or select the paired computer",
+        ))
+    };
+    let prefix = format!("/org/bluez/{adapter}/dev_");
+    let address = path
+        .strip_prefix(&prefix)
+        .ok_or_else(rejected)?
+        .replace('_', ":");
+    let mut state = shared.state.lock().unwrap();
+    if pairing
+        && !state
+            .pairing_until
+            .is_some_and(|until| until > Instant::now())
+    {
+        return Err(rejected());
+    }
+    if state.peer.as_ref().is_some_and(|peer| peer != &address) {
+        return Err(rejected());
+    }
+    if state.peer.is_none() {
+        if !pairing || state.bonded_before_pairing.contains(&address) {
+            return Err(rejected());
+        }
+        state.peer = Some(address);
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn existing_unrelated_bond_cannot_be_adopted_by_agent_callback() {
+        let shared = Shared::new(None);
+        {
+            let mut state = shared.state.lock().unwrap();
+            state.pairing_until = Some(Instant::now() + Duration::from_secs(120));
+            state
+                .bonded_before_pairing
+                .insert("10:6F:D9:66:97:88".into());
+        }
+        assert!(authorize(
+            &shared,
+            "hci0",
+            "/org/bluez/hci0/dev_10_6F_D9_66_97_88",
+            true
+        )
+        .is_err());
+        assert!(shared.state.lock().unwrap().peer.is_none());
+    }
+    #[test]
+    fn only_pair_during_window_and_pin_first_peer() {
+        let state = Shared::new(None);
+        let first = "/org/bluez/hci0/dev_10_6F_D9_66_97_88";
+        assert!(authorize(&state, "hci0", first, true).is_err());
+        state.state.lock().unwrap().pairing_until = Some(Instant::now() + Duration::from_secs(60));
+        assert!(authorize(&state, "hci0", first, true).is_ok());
+        assert!(authorize(
+            &state,
+            "hci0",
+            "/org/bluez/hci0/dev_10_6F_D9_66_97_89",
+            true
+        )
+        .is_err());
+        assert!(authorize(&state, "hci1", first, true).is_err());
+        state.state.lock().unwrap().pairing_until = None;
+        assert!(authorize(&state, "hci0", first, false).is_ok());
+        assert!(authorize(&state, "hci0", first, true).is_err());
+    }
+}

libs/bluetooth-hid/src/bonds.rs

@@ -0,0 +1,145 @@
+//! Only bonds explicitly owned by this HID peripheral may be removed.
+use bluer::{Adapter, Session};
+use std::{future::Future, pin::Pin};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Bond {
+    pub adapter: String,
+    pub peer: String,
+    pub pending: bool,
+}
+pub type Operation<'a, T> = Pin<Box<dyn Future<Output = Result<T, String>> + Send + 'a>>;
+pub trait BondStore: Send + Sync {
+    fn list(&self) -> Operation<'_, Vec<Bond>>;
+    fn save(&self, bond: Bond) -> Operation<'_, ()>;
+    fn remove(&self, bond: Bond) -> Operation<'_, ()>;
+}
+
+pub async fn clean_adapter(store: &dyn BondStore, adapter: &Adapter) -> Result<(), String> {
+    let address = adapter
+        .address()
+        .await
+        .map_err(|e| e.to_string())?
+        .to_string();
+    clean_owned(store, &address, |peer| async move {
+        let peer = peer.parse().map_err(|_| "Invalid stored HID peer")?;
+        if adapter
+            .device_addresses()
+            .await
+            .map_err(|e| e.to_string())?
+            .contains(&peer)
+        {
+            adapter
+                .remove_device(peer)
+                .await
+                .map_err(|e| e.to_string())?;
+        }
+        Ok(())
+    })
+    .await
+}
+
+async fn clean_owned<F, Fut>(
+    store: &dyn BondStore,
+    address: &str,
+    mut remove: F,
+) -> Result<(), String>
+where
+    F: FnMut(String) -> Fut,
+    Fut: Future<Output = Result<(), String>>,
+{
+    for bond in store
+        .list()
+        .await?
+        .into_iter()
+        .filter(|b| b.pending && b.adapter == address)
+    {
+        remove(bond.peer.clone()).await?;
+        // Keep the tombstone until BlueZ confirms removal; retry safely after interruption.
+        store.remove(bond).await?;
+    }
+    Ok(())
+}
+
+pub async fn reset(store: &dyn BondStore, explicit: Vec<Bond>) -> Result<(), String> {
+    let session = Session::new().await.map_err(|e| e.to_string())?;
+    let mut owned = store.list().await?;
+    owned.extend(explicit);
+    for mut bond in owned {
+        bond.pending = true;
+        store.save(bond).await?;
+    }
+    for name in session.adapter_names().await.map_err(|e| e.to_string())? {
+        clean_adapter(store, &session.adapter(&name).map_err(|e| e.to_string())?).await?;
+    }
+    // Records for absent adapters remain pending and are cleaned before their next use.
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Mutex;
+    #[derive(Default)]
+    struct Memory(Mutex<Vec<Bond>>);
+    impl BondStore for Memory {
+        fn list(&self) -> Operation<'_, Vec<Bond>> {
+            Box::pin(async { Ok(self.0.lock().unwrap().clone()) })
+        }
+        fn save(&self, bond: Bond) -> Operation<'_, ()> {
+            Box::pin(async move {
+                let mut rows = self.0.lock().unwrap();
+                rows.retain(|b| b.adapter != bond.adapter || b.peer != bond.peer);
+                rows.push(bond);
+                Ok(())
+            })
+        }
+        fn remove(&self, bond: Bond) -> Operation<'_, ()> {
+            Box::pin(async move {
+                self.0.lock().unwrap().retain(|b| b != &bond);
+                Ok(())
+            })
+        }
+    }
+    fn bond(adapter: &str, peer: &str, pending: bool) -> Bond {
+        Bond {
+            adapter: adapter.into(),
+            peer: peer.into(),
+            pending,
+        }
+    }
+    #[tokio::test]
+    async fn cleanup_only_removes_owned_pending_bonds_on_the_selected_hardware() {
+        let current = bond("adapter-A", "host-1", true);
+        let absent = bond("adapter-B", "host-2", true);
+        let retained = bond("adapter-A", "host-3", false);
+        let store = Memory(Mutex::new(vec![current, absent.clone(), retained.clone()]));
+        let removed = Mutex::new(Vec::new());
+        clean_owned(&store, "adapter-A", |peer| {
+            removed.lock().unwrap().push(peer);
+            async { Ok(()) }
+        })
+        .await
+        .unwrap();
+        assert_eq!(*removed.lock().unwrap(), vec!["host-1"]);
+        assert_eq!(store.list().await.unwrap(), vec![absent, retained]);
+    }
+    #[tokio::test]
+    async fn cleanup_failure_keeps_tombstone_and_is_reported() {
+        let record = bond("adapter-A", "host-1", true);
+        let store = Memory(Mutex::new(vec![record.clone()]));
+        assert_eq!(
+            clean_owned(&store, "adapter-A", |_| async {
+                Err("BlueZ denied removal".into())
+            })
+            .await
+            .unwrap_err(),
+            "BlueZ denied removal"
+        );
+        assert_eq!(store.list().await.unwrap(), vec![record]);
+        clean_owned(&store, "adapter-A", |_| async { Ok(()) })
+            .await
+            .unwrap();
+        assert!(store.list().await.unwrap().is_empty());
+    }
+}

libs/bluetooth-hid/src/controller.rs

@@ -0,0 +1,135 @@
+//! Exclusive controller ownership. No BLE switching or power cycling.
+use std::{
+    fs::{File, OpenOptions},
+    os::{fd::AsRawFd, unix::fs::OpenOptionsExt},
+    process::Stdio,
+    time::Duration,
+};
+use tokio::process::Command;
+pub struct Controller {
+    _lock: File,
+    adapter: String,
+    old_class: (u8, u8),
+    old_connectable: bool,
+}
+async fn run_once(adapter: &str, args: &[&str]) -> Result<String, String> {
+    let mut cmd = Command::new("btmgmt");
+    cmd.arg("--index")
+        .arg(adapter.trim_start_matches("hci"))
+        .args(args)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true);
+    let mut child = cmd
+        .spawn()
+        .map_err(|e| format!("Install bluez/btmgmt: {e}"))?;
+    // BlueZ 5.55's btmgmt exits on stdin EOF, even with a command argument.
+    // Keep a pipe open until it finishes; systemd normally supplies /dev/null.
+    let stdin = child.stdin.take();
+    let result = tokio::time::timeout(Duration::from_secs(5), child.wait_with_output())
+        .await
+        .map_err(|_| "btmgmt timeout")?
+        .map_err(|e| format!("Install bluez/btmgmt: {e}"))?;
+    drop(stdin);
+    let text = String::from_utf8_lossy(&result.stdout).into_owned();
+    if !result.status.success()
+        || !result.stderr.is_empty()
+        || text.to_lowercase().contains("failed")
+    {
+        return Err(format!(
+            "btmgmt {}: {text} {}",
+            args.join(" "),
+            String::from_utf8_lossy(&result.stderr)
+        ));
+    }
+    Ok(text)
+}
+async fn run(adapter: &str, args: &[&str]) -> Result<String, String> {
+    // BlueZ updates the EIR/class asynchronously after registering SDP.
+    // Kernel management rejects a simultaneous class change with Busy.
+    for attempt in 0..5 {
+        match run_once(adapter, args).await {
+            Err(error) if error.contains("(Busy)") && attempt < 4 => {
+                tokio::time::sleep(Duration::from_millis(200)).await;
+            }
+            result => return result,
+        }
+    }
+    unreachable!()
+}
+impl Controller {
+    pub async fn acquire(adapter: &str) -> Result<Self, String> {
+        let lock = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .truncate(false)
+            .mode(0o600)
+            .custom_flags(libc::O_NOFOLLOW)
+            .open(format!("/run/one-kvm-bluetooth-{adapter}.lock"))
+            .map_err(|e| e.to_string())?;
+        if unsafe { libc::flock(lock.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) } != 0 {
+            return Err("Bluetooth adapter already owned by One-KVM".into());
+        }
+        let info = run(adapter, &["info"]).await?;
+        let settings = info
+            .lines()
+            .find_map(|l| l.trim().strip_prefix("current settings:"))
+            .ok_or("Cannot read Bluetooth settings")?;
+        if !settings.split_whitespace().any(|s| s == "br/edr") {
+            return Err(
+                "Classic Bluetooth disabled; enable BR/EDR with btmgmt before using HID".into(),
+            );
+        }
+        let class = info
+            .split_whitespace()
+            .skip_while(|s| *s != "class")
+            .nth(1)
+            .ok_or("Missing Bluetooth class")?;
+        let class =
+            u32::from_str_radix(class.trim_start_matches("0x"), 16).map_err(|e| e.to_string())?;
+        Ok(Self {
+            _lock: lock,
+            adapter: adapter.into(),
+            old_class: (((class >> 8) & 0x1f) as u8, (class & 0xfc) as u8),
+            old_connectable: settings.split_whitespace().any(|s| s == "connectable"),
+        })
+    }
+    pub async fn configure(&self) -> Result<(), String> {
+        run(&self.adapter, &["class", "5", "192"]).await?;
+        run(&self.adapter, &["connectable", "on"]).await?;
+        Ok(())
+    }
+    pub async fn restore(&self) -> Result<(), String> {
+        let mut errors = vec![];
+        if let Err(e) = run(
+            &self.adapter,
+            &[
+                "class",
+                &self.old_class.0.to_string(),
+                &self.old_class.1.to_string(),
+            ],
+        )
+        .await
+        {
+            errors.push(e);
+        }
+        if let Err(e) = run(
+            &self.adapter,
+            &[
+                "connectable",
+                if self.old_connectable { "on" } else { "off" },
+            ],
+        )
+        .await
+        {
+            errors.push(e);
+        }
+        if errors.is_empty() {
+            Ok(())
+        } else {
+            Err(errors.join("; "))
+        }
+    }
+}

libs/bluetooth-hid/src/lib.rs

@@ -0,0 +1,964 @@
+//! Classic Bluetooth HID peripheral: SDP + L2CAP. Linux/BlueZ only.
+mod agent;
+pub mod bonds;
+mod controller;
+mod protocol;
+
+use bluer::{
+    l2cap::{Security, SecurityLevel, SeqPacket, SeqPacketListener, Socket, SocketAddr},
+    Adapter, Address, AddressType, Session,
+};
+use serde::{Deserialize, Serialize};
+use std::{
+    collections::HashSet,
+    sync::{Arc, Mutex},
+    time::{Duration, Instant},
+};
+use tokio::sync::{mpsc, oneshot, watch, Mutex as AsyncMutex};
+
+#[derive(Debug, Clone)]
+pub struct Config {
+    pub adapter: String,
+    pub name: String,
+    pub peer: Option<String>,
+}
+impl Config {
+    pub fn validate(&self) -> Result<(), String> {
+        if !self
+            .adapter
+            .strip_prefix("hci")
+            .is_some_and(|n| !n.is_empty() && n.bytes().all(|c| c.is_ascii_digit()))
+        {
+            return Err("Bluetooth adapter must be hci followed by an index".into());
+        }
+        if self.name.is_empty() || self.name.len() > 64 || self.name.chars().any(char::is_control) {
+            return Err(
+                "Bluetooth name must contain 1–64 UTF-8 bytes without control characters".into(),
+            );
+        }
+        if let Some(peer) = &self.peer {
+            peer.parse::<Address>()
+                .map_err(|_| "Invalid Bluetooth peer address")?;
+        }
+        Ok(())
+    }
+}
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Status {
+    pub initialized: bool,
+    pub connected: bool,
+    pub ready: bool,
+    pub adapter: String,
+    pub adapter_address: String,
+    pub peer: Option<String>,
+    pub pairing_seconds: u32,
+    pub control_connected: bool,
+    pub interrupt_connected: bool,
+    pub leds: u8,
+    pub generation: u64,
+    pub error: Option<String>,
+    pub devices: Vec<Device>,
+}
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Device {
+    pub address: String,
+    pub name: String,
+    pub paired: bool,
+    pub connected: bool,
+}
+#[derive(Debug, Clone, Copy)]
+pub enum Report {
+    Keyboard,
+    Mouse,
+    Consumer,
+}
+impl Report {
+    fn len(self) -> usize {
+        match self {
+            Self::Keyboard => 8,
+            Self::Mouse => 4,
+            Self::Consumer => 2,
+        }
+    }
+    fn id(self) -> u8 {
+        match self {
+            Self::Keyboard => 1,
+            Self::Mouse => 2,
+            Self::Consumer => 3,
+        }
+    }
+}
+struct State {
+    peer: Option<String>,
+    pairing_until: Option<Instant>,
+    bonded_before_pairing: HashSet<String>,
+}
+impl State {
+    fn observe_bond(&mut self, address: &str, paired: bool) {
+        // Just Works may complete without an Agent1 authorization callback.
+        // Adopt only a new bond from our explicit window, respecting a pinned peer.
+        if paired
+            && self.peer.is_none()
+            && self
+                .pairing_until
+                .is_some_and(|until| until > Instant::now())
+            && !self.bonded_before_pairing.contains(address)
+        {
+            self.peer = Some(address.to_owned());
+            tracing::info!(
+                peer = address,
+                "Bluetooth HID selected newly bonded computer"
+            );
+        }
+    }
+    fn close_pairing(&mut self, paired: bool, fallback: Option<String>) {
+        self.pairing_until = None;
+        if !paired {
+            self.peer = fallback;
+        }
+    }
+    fn pairing_completed(&self, selected_paired: bool) -> bool {
+        selected_paired
+            && self
+                .peer
+                .as_ref()
+                .is_some_and(|peer| !self.bonded_before_pairing.contains(peer))
+    }
+}
+struct Shared {
+    state: Mutex<State>,
+}
+impl Shared {
+    fn new(peer: Option<String>) -> Self {
+        Self {
+            state: Mutex::new(State {
+                peer,
+                pairing_until: None,
+                bonded_before_pairing: HashSet::new(),
+            }),
+        }
+    }
+    fn allowed(&self, address: Address) -> bool {
+        self.state.lock().unwrap().peer.as_deref() == Some(address.to_string().as_str())
+    }
+}
+pub enum Action {
+    Pair(u32),
+    ClosePairing,
+    Forget,
+    Disconnect,
+    Reset,
+}
+enum Command {
+    Report(Report, Vec<u8>),
+    Action(Action),
+    Stop,
+}
+struct Request {
+    command: Command,
+    result: oneshot::Sender<Result<(), String>>,
+    expires: Instant,
+}
+pub struct Peripheral {
+    tx: mpsc::Sender<Request>,
+    status: watch::Receiver<Status>,
+    task: AsyncMutex<Option<tokio::task::JoinHandle<()>>>,
+}
+impl Peripheral {
+    pub fn start(config: Config) -> Result<Self, String> {
+        Self::start_with_store(config, None)
+    }
+    pub fn start_with_store(
+        config: Config,
+        bonds: Option<Arc<dyn bonds::BondStore>>,
+    ) -> Result<Self, String> {
+        config.validate()?;
+        let (tx, rx) = mpsc::channel(64);
+        let (state_tx, status) = watch::channel(Status {
+            adapter: config.adapter.clone(),
+            ..Default::default()
+        });
+        let task = tokio::spawn(supervise(config, bonds, rx, state_tx));
+        Ok(Self {
+            tx,
+            status,
+            task: AsyncMutex::new(Some(task)),
+        })
+    }
+    pub fn status(&self) -> Status {
+        self.status.borrow().clone()
+    }
+    pub fn subscribe(&self) -> watch::Receiver<Status> {
+        self.status.clone()
+    }
+    async fn request(&self, command: Command, duration: Duration) -> Result<(), String> {
+        let (result, rx) = oneshot::channel();
+        let request = Request {
+            command,
+            result,
+            expires: Instant::now() + duration,
+        };
+        self.tx
+            .try_send(request)
+            .map_err(|_| "Bluetooth input queue unavailable or full".to_string())?;
+        tokio::time::timeout(duration, rx)
+            .await
+            .map_err(|_| "Bluetooth operation timed out".to_string())?
+            .map_err(|_| "Bluetooth worker stopped".to_string())?
+    }
+    pub async fn send(&self, report: Report, value: Vec<u8>) -> Result<(), String> {
+        if value.len() != report.len() {
+            return Err("Invalid HID report size".into());
+        }
+        self.request(Command::Report(report, value), Duration::from_millis(500))
+            .await
+    }
+    pub async fn action(&self, action: Action) -> Result<(), String> {
+        self.request(Command::Action(action), Duration::from_secs(15))
+            .await
+    }
+    pub async fn shutdown(&self) -> Result<(), String> {
+        if let Some(task) = self.task.lock().await.take() {
+            let result = self.request(Command::Stop, Duration::from_secs(45)).await;
+            // Do not abort: the worker must restore the radio before a backend switch.
+            task.await.map_err(|e| e.to_string())?;
+            result
+        } else {
+            Ok(())
+        }
+    }
+}
+
+fn listen(address: Address, psm: u16) -> Result<SeqPacketListener, String> {
+    let socket = Socket::<SeqPacket>::new_seq_packet().map_err(|e| e.to_string())?;
+    socket
+        .set_security(Security {
+            level: SecurityLevel::Medium,
+            key_size: 0,
+        })
+        .map_err(|e| e.to_string())?;
+    socket.bind(SocketAddr::new(address,AddressType::BrEdr,psm))
+        .map_err(|e|format!("Cannot bind classic HID PSM 0x{psm:02x}: {e}. Disable BlueZ input plugin; see Bluetooth HID setup."))?;
+    socket.listen(2).map_err(|e| e.to_string())
+}
+struct Runtime {
+    adapter: Adapter,
+    _session: Session,
+    shared: Arc<Shared>,
+    agent: Option<agent::Agent>,
+    controller: controller::Controller,
+    listeners: [SeqPacketListener; 2],
+    channels: [Option<Arc<SeqPacket>>; 2],
+    channel_peer: Option<Address>,
+    partial_since: Option<Instant>,
+    hid: protocol::HidProtocol,
+    generation: u64,
+    old_pairable: bool,
+    old_powered: bool,
+    old_alias: String,
+    old_discoverable: bool,
+    old_discoverable_timeout: u32,
+    old_pairable_timeout: u32,
+    config: Config,
+    bonds: Option<Arc<dyn bonds::BondStore>>,
+    recorded_peer: Option<String>,
+}
+impl Runtime {
+    async fn open(
+        config: &Config,
+        bonds: Option<Arc<dyn bonds::BondStore>>,
+    ) -> Result<Self, String> {
+        let controller = controller::Controller::acquire(&config.adapter).await?;
+        let session = Session::new().await.map_err(|e| e.to_string())?;
+        let adapter = session
+            .adapter(&config.adapter)
+            .map_err(|e| e.to_string())?;
+        let address = adapter.address().await.map_err(|e| e.to_string())?;
+        let mut config = config.clone();
+        if let Some(store) = &bonds {
+            bonds::clean_adapter(store.as_ref(), &adapter).await?;
+            if config.peer.is_none() {
+                config.peer = store
+                    .list()
+                    .await?
+                    .into_iter()
+                    .find(|bond| bond.adapter == address.to_string() && !bond.pending)
+                    .map(|bond| bond.peer);
+            }
+        }
+        // Acquire BOTH channels before changing adapter state. Conflict is a startup error.
+        let listeners = [listen(address, 0x11)?, listen(address, 0x13)?];
+        let old_powered = adapter.is_powered().await.map_err(|e| e.to_string())?;
+        let old_pairable = adapter.is_pairable().await.map_err(|e| e.to_string())?;
+        let old_alias = adapter.alias().await.map_err(|e| e.to_string())?;
+        let old_discoverable = adapter.is_discoverable().await.map_err(|e| e.to_string())?;
+        let old_discoverable_timeout = adapter
+            .discoverable_timeout()
+            .await
+            .map_err(|e| e.to_string())?;
+        let old_pairable_timeout = adapter
+            .pairable_timeout()
+            .await
+            .map_err(|e| e.to_string())?;
+        let shared = Arc::new(Shared::new(
+            config.peer.as_ref().map(|p| p.to_ascii_uppercase()),
+        ));
+        let mut runtime = Self {
+            adapter,
+            _session: session,
+            shared,
+            agent: None,
+            controller,
+            listeners,
+            channels: [None, None],
+            channel_peer: None,
+            partial_since: None,
+            hid: Default::default(),
+            generation: 0,
+            old_pairable,
+            old_powered,
+            old_alias,
+            old_discoverable,
+            old_discoverable_timeout,
+            old_pairable_timeout,
+            config: config.clone(),
+            bonds,
+            recorded_peer: None,
+        };
+        if let Err(e) = runtime.setup().await {
+            let restore = runtime.close().await;
+            return Err(format!("{e}; cleanup: {restore:?}"));
+        }
+        Ok(runtime)
+    }
+    async fn setup(&mut self) -> Result<(), String> {
+        self.adapter
+            .set_powered(true)
+            .await
+            .map_err(|e| e.to_string())?;
+        self.adapter
+            .set_discoverable(false)
+            .await
+            .map_err(|e| e.to_string())?;
+        self.adapter
+            .set_pairable(false)
+            .await
+            .map_err(|e| e.to_string())?;
+        self.adapter
+            .set_alias(self.config.name.clone())
+            .await
+            .map_err(|e| e.to_string())?;
+        self.agent =
+            Some(agent::Agent::register(self.shared.clone(), self.config.adapter.clone()).await?);
+        self.controller.configure().await?;
+        self.public(None).await?;
+        Ok(())
+    }
+    async fn public(&self, seconds: Option<u32>) -> Result<(), String> {
+        if let Some(seconds) = seconds {
+            self.adapter
+                .set_pairable_timeout(seconds)
+                .await
+                .map_err(|e| e.to_string())?;
+            self.adapter
+                .set_discoverable_timeout(seconds)
+                .await
+                .map_err(|e| e.to_string())?;
+            self.adapter
+                .set_pairable(true)
+                .await
+                .map_err(|e| e.to_string())?;
+            if let Err(e) = self.adapter.set_discoverable(true).await {
+                let _ = self.adapter.set_pairable(false).await;
+                return Err(e.to_string());
+            }
+        } else {
+            self.adapter
+                .set_discoverable(false)
+                .await
+                .map_err(|e| e.to_string())?;
+            self.adapter
+                .set_pairable(false)
+                .await
+                .map_err(|e| e.to_string())?;
+        }
+        Ok(())
+    }
+    fn drop_channels(&mut self) {
+        for socket in self.channels.iter_mut().filter_map(Option::take) {
+            let _ = socket.shutdown(std::net::Shutdown::Both);
+        }
+        self.channel_peer = None;
+        self.partial_since = None;
+        self.hid = Default::default();
+        self.generation = self.generation.wrapping_add(1);
+    }
+    async fn packet(&self, index: usize, data: &[u8]) -> Result<(), String> {
+        let socket = self.channels[index]
+            .as_ref()
+            .ok_or("Classic HID channel not connected")?;
+        let sent = tokio::time::timeout(Duration::from_millis(250), socket.send(data))
+            .await
+            .map_err(|_| "HID send timeout")?
+            .map_err(|e| e.to_string())?;
+        if sent != data.len() {
+            return Err("Short HID packet write".into());
+        }
+        Ok(())
+    }
+    async fn release(&mut self) {
+        for packet in self.hid.release() {
+            if self.channels[1].is_some() && self.packet(1, &packet).await.is_err() {
+                self.drop_channels();
+                break;
+            }
+        }
+        self.generation = self.generation.wrapping_add(1);
+    }
+    async fn accept(
+        &mut self,
+        index: usize,
+        socket: SeqPacket,
+        peer: SocketAddr,
+    ) -> Result<(), String> {
+        if peer.addr_type != AddressType::BrEdr {
+            return Ok(());
+        }
+        // A host can open HID channels before the next status poll.
+        let paired = self
+            .adapter
+            .device(peer.addr)
+            .map_err(|e| e.to_string())?
+            .is_paired()
+            .await
+            .map_err(|e| e.to_string())?;
+        self.shared
+            .state
+            .lock()
+            .unwrap()
+            .observe_bond(&peer.addr.to_string(), paired);
+        if !self.shared.allowed(peer.addr) {
+            return Ok(());
+        }
+        if self.channel_peer.is_some_and(|p| p != peer.addr) || self.channels[index].is_some() {
+            return Ok(());
+        }
+        // Kernel BT_SECURITY_MEDIUM negotiates encryption before accept completes.
+        if socket
+            .as_ref()
+            .security()
+            .map_err(|e| e.to_string())?
+            .key_size
+            < 7
+        {
+            return Ok(());
+        }
+        self.channel_peer = Some(peer.addr);
+        self.channels[index] = Some(Arc::new(socket));
+        if self.channels.iter().all(Option::is_some) {
+            self.partial_since = None;
+            self.release().await;
+        } else {
+            self.partial_since = Some(Instant::now());
+        }
+        Ok(())
+    }
+    async fn status(&mut self) -> Result<Status, String> {
+        if !self.adapter.is_powered().await.map_err(|e| e.to_string())? {
+            return Err("Bluetooth adapter powered off".into());
+        }
+        // A daemon restart loses the SDP registration even if the adapter comes back powered.
+        if !self
+            .adapter
+            .uuids()
+            .await
+            .map_err(|e| e.to_string())?
+            .unwrap_or_default()
+            .iter()
+            .any(|id| id.to_string() == protocol::HID_UUID)
+        {
+            return Err("Classic HID SDP registration lost; restarting Bluetooth backend".into());
+        }
+        let mut status = Status {
+            initialized: true,
+            adapter: self.config.adapter.clone(),
+            adapter_address: self
+                .adapter
+                .address()
+                .await
+                .map_err(|e| e.to_string())?
+                .to_string(),
+            ..Default::default()
+        };
+        for address in self
+            .adapter
+            .device_addresses()
+            .await
+            .map_err(|e| e.to_string())?
+        {
+            let device = self.adapter.device(address).map_err(|e| e.to_string())?;
+            let connected = device.is_connected().await.unwrap_or(false);
+            let paired = device.is_paired().await.unwrap_or(false);
+            self.shared
+                .state
+                .lock()
+                .unwrap()
+                .observe_bond(&address.to_string(), paired);
+            if paired || connected {
+                status.devices.push(Device {
+                    address: address.to_string(),
+                    name: device.alias().await.unwrap_or_default(),
+                    paired,
+                    connected,
+                });
+            }
+        }
+        status.devices.sort_by(|a, b| a.address.cmp(&b.address));
+        let (peer, until) = {
+            let state = self.shared.state.lock().unwrap();
+            (state.peer.clone(), state.pairing_until)
+        };
+        status.peer = peer.clone();
+        let selected = status
+            .devices
+            .iter()
+            .find(|device| Some(&device.address) == peer.as_ref());
+        let selected_paired = selected.is_some_and(|device| device.paired);
+        if selected_paired && self.recorded_peer != peer {
+            if let (Some(store), Some(peer)) = (&self.bonds, &peer) {
+                store
+                    .save(bonds::Bond {
+                        adapter: status.adapter_address.clone(),
+                        peer: peer.clone(),
+                        pending: false,
+                    })
+                    .await?;
+                self.recorded_peer = Some(peer.clone());
+            }
+        }
+        status.connected = selected.is_some_and(|device| device.paired && device.connected);
+        if self.channels.iter().any(Option::is_some)
+            && (!status.connected
+                || self
+                    .partial_since
+                    .is_some_and(|time| time.elapsed() > Duration::from_secs(10)))
+        {
+            self.drop_channels();
+        }
+        if let Some(until) = until {
+            let completed = self
+                .shared
+                .state
+                .lock()
+                .unwrap()
+                .pairing_completed(selected_paired);
+            if until <= Instant::now() || completed {
+                {
+                    let mut state = self.shared.state.lock().unwrap();
+                    state.close_pairing(
+                        selected_paired,
+                        self.config.peer.as_ref().map(|p| p.to_ascii_uppercase()),
+                    );
+                    status.peer = state.peer.clone();
+                }
+                self.public(None).await?;
+                tracing::info!(reason = if completed { "bonded" } else { "expired" }, peer = ?status.peer, "Bluetooth HID pairing window closed");
+            } else {
+                status.pairing_seconds =
+                    until.saturating_duration_since(Instant::now()).as_secs() as u32 + 1;
+            }
+        }
+        status.control_connected = self.channels[0].is_some();
+        status.interrupt_connected = self.channels[1].is_some();
+        status.ready = status.connected
+            && status.control_connected
+            && status.interrupt_connected
+            && !self.hid.suspended;
+        status.leds = self.hid.leds;
+        status.generation = self.generation;
+        Ok(status)
+    }
+    async fn forget(&mut self) -> Result<(), String> {
+        self.release().await;
+        self.drop_channels();
+        let peer = self.shared.state.lock().unwrap().peer.clone();
+        if let Some(peer) = &peer {
+            let address = peer.parse().map_err(|_| "Invalid peer")?;
+            if self
+                .adapter
+                .device_addresses()
+                .await
+                .map_err(|e| e.to_string())?
+                .contains(&address)
+            {
+                self.adapter
+                    .remove_device(address)
+                    .await
+                    .map_err(|e| e.to_string())?;
+            }
+            self.shared
+                .state
+                .lock()
+                .unwrap()
+                .bonded_before_pairing
+                .remove(peer);
+            tracing::info!(%peer, "Bluetooth HID forgot computer");
+        }
+        if let Some(store) = &self.bonds {
+            let address = self
+                .adapter
+                .address()
+                .await
+                .map_err(|e| e.to_string())?
+                .to_string();
+            for bond in store
+                .list()
+                .await?
+                .into_iter()
+                .filter(|b| b.adapter == address && Some(&b.peer) == peer.as_ref())
+            {
+                store.remove(bond).await?;
+            }
+        }
+        self.recorded_peer = None;
+        self.config.peer = None;
+        self.shared.state.lock().unwrap().peer = None;
+        Ok(())
+    }
+    async fn incoming(&mut self, index: usize, data: &[u8]) -> Result<(), String> {
+        if index == 1 {
+            self.hid.output(data);
+            return Ok(());
+        }
+        let result = self.hid.control(data);
+        if let Some(reply) = result.reply {
+            self.packet(0, &reply).await?;
+        }
+        if result.reset {
+            self.release().await;
+        }
+        if result.unplug {
+            self.forget().await?;
+        }
+        Ok(())
+    }
+    async fn execute(&mut self, command: Command) -> Result<(), String> {
+        match command {
+            Command::Report(kind, value) => {
+                let peer = self.channel_peer.ok_or("Classic HID is not connected")?;
+                if !self.shared.allowed(peer) || self.channels.iter().any(Option::is_none) {
+                    return Err("Classic HID channels are not ready".into());
+                }
+                let device = self.adapter.device(peer).map_err(|e| e.to_string())?;
+                if !device.is_paired().await.unwrap_or(false)
+                    || !device.is_connected().await.unwrap_or(false)
+                {
+                    self.drop_channels();
+                    return Err("Selected Bluetooth computer disconnected".into());
+                }
+                let packet = self.hid.input(kind, &value)?;
+                if let Err(e) = self.packet(1, &packet).await {
+                    self.drop_channels();
+                    return Err(e);
+                }
+            }
+            Command::Action(Action::Pair(seconds)) => {
+                if !(10..=300).contains(&seconds) {
+                    return Err("Pairing window must be 10–300 seconds".into());
+                }
+                let mut bonded = HashSet::new();
+                for address in self
+                    .adapter
+                    .device_addresses()
+                    .await
+                    .map_err(|e| e.to_string())?
+                {
+                    if self
+                        .adapter
+                        .device(address)
+                        .map_err(|e| e.to_string())?
+                        .is_paired()
+                        .await
+                        .map_err(|e| e.to_string())?
+                    {
+                        bonded.insert(address.to_string());
+                    }
+                }
+                {
+                    let mut state = self.shared.state.lock().unwrap();
+                    // Preserve the original baseline when extending an open window.
+                    if !state
+                        .pairing_until
+                        .is_some_and(|until| until > Instant::now())
+                    {
+                        state.bonded_before_pairing = bonded;
+                    }
+                    state.pairing_until =
+                        Some(Instant::now() + Duration::from_secs(seconds.into()));
+                }
+                if let Err(e) = self.public(Some(seconds)).await {
+                    self.shared.state.lock().unwrap().pairing_until = None;
+                    return Err(e);
+                }
+                tracing::info!(seconds, "Bluetooth HID pairing window opened");
+            }
+            Command::Action(Action::ClosePairing) => {
+                self.public(None).await?;
+                let peer = self.shared.state.lock().unwrap().peer.clone();
+                let paired = if let Some(peer) = peer {
+                    self.adapter
+                        .device(peer.parse().map_err(|_| "Invalid HID peer")?)
+                        .map_err(|e| e.to_string())?
+                        .is_paired()
+                        .await
+                        .map_err(|e| e.to_string())?
+                } else {
+                    false
+                };
+                self.shared
+                    .state
+                    .lock()
+                    .unwrap()
+                    .close_pairing(paired, self.config.peer.clone());
+                tracing::info!(reason = "manual", "Bluetooth HID pairing window closed");
+            }
+            Command::Action(Action::Forget) => self.forget().await?,
+            Command::Action(Action::Disconnect) => {
+                self.release().await;
+                self.drop_channels();
+                let peer = self.shared.state.lock().unwrap().peer.clone();
+                if let Some(peer) = peer {
+                    self.adapter
+                        .device(peer.parse().map_err(|_| "Invalid peer")?)
+                        .map_err(|e| e.to_string())?
+                        .disconnect()
+                        .await
+                        .map_err(|e| e.to_string())?;
+                }
+            }
+            Command::Action(Action::Reset) => self.release().await,
+            Command::Stop => {}
+        }
+        Ok(())
+    }
+    async fn close(&mut self) -> Result<(), String> {
+        self.release().await;
+        self.drop_channels();
+        self.agent.take();
+        tokio::time::sleep(Duration::from_millis(100)).await;
+        let mut errors = vec![];
+        if let Err(e) = self.adapter.set_discoverable(false).await {
+            errors.push(e.to_string());
+        }
+        if let Err(e) = self.controller.restore().await {
+            errors.push(e);
+        }
+        if let Err(e) = self.adapter.set_alias(self.old_alias.clone()).await {
+            errors.push(e.to_string());
+        }
+        if let Err(e) = self
+            .adapter
+            .set_discoverable_timeout(self.old_discoverable_timeout)
+            .await
+        {
+            errors.push(e.to_string());
+        }
+        if let Err(e) = self
+            .adapter
+            .set_pairable_timeout(self.old_pairable_timeout)
+            .await
+        {
+            errors.push(e.to_string());
+        }
+        if let Err(e) = self.adapter.set_pairable(self.old_pairable).await {
+            errors.push(e.to_string());
+        }
+        if let Err(e) = self.adapter.set_discoverable(self.old_discoverable).await {
+            errors.push(e.to_string());
+        }
+        if let Err(e) = self.adapter.set_powered(self.old_powered).await {
+            errors.push(e.to_string());
+        }
+        if errors.is_empty() {
+            Ok(())
+        } else {
+            Err(errors.join("; "))
+        }
+    }
+}
+async fn receive(socket: Option<Arc<SeqPacket>>, buffer: &mut [u8]) -> std::io::Result<usize> {
+    match socket {
+        Some(socket) => socket.recv(buffer).await,
+        None => std::future::pending().await,
+    }
+}
+async fn supervise(
+    config: Config,
+    bonds: Option<Arc<dyn bonds::BondStore>>,
+    mut rx: mpsc::Receiver<Request>,
+    tx: watch::Sender<Status>,
+) {
+    let mut generation = 0;
+    loop {
+        let mut runtime = match Runtime::open(&config, bonds.clone()).await {
+            Ok(runtime) => runtime,
+            Err(error) => {
+                tx.send_replace(Status {
+                    adapter: config.adapter.clone(),
+                    error: Some(error.clone()),
+                    generation,
+                    ..Default::default()
+                });
+                let delay = tokio::time::sleep(Duration::from_secs(5));
+                tokio::pin!(delay);
+                loop {
+                    tokio::select! {_=&mut delay=>break,request=rx.recv()=>{
+                        let Some(request)=request else{return;};
+                        if matches!(request.command,Command::Stop){let _=request.result.send(Ok(()));return;}
+                        let _=request.result.send(Err(error.clone()));
+                    }}
+                }
+                continue;
+            }
+        };
+        runtime.generation = generation;
+        let mut timer = tokio::time::interval(Duration::from_millis(500));
+        let failure = loop {
+            let ctl = runtime.channels[0].clone();
+            let intr = runtime.channels[1].clone();
+            let mut ctl_buffer = [0; 1024];
+            let mut intr_buffer = [0; 1024];
+            tokio::select! {
+                accepted=runtime.listeners[0].accept()=>{match accepted{Ok((socket,peer))=>{if let Err(e)=runtime.accept(0,socket,peer).await{break e;}},Err(e)=>break e.to_string()}}
+                accepted=runtime.listeners[1].accept()=>{match accepted{Ok((socket,peer))=>{if let Err(e)=runtime.accept(1,socket,peer).await{break e;}},Err(e)=>break e.to_string()}}
+                read=receive(ctl,&mut ctl_buffer)=>{match read{Ok(n)if n>0=>{if runtime.incoming(0,&ctl_buffer[..n]).await.is_err(){runtime.drop_channels();}},_=>runtime.drop_channels()}}
+                read=receive(intr,&mut intr_buffer)=>{match read{Ok(n)if n>0=>{if runtime.incoming(1,&intr_buffer[..n]).await.is_err(){runtime.drop_channels();}},_=>runtime.drop_channels()}}
+                _=timer.tick()=>{match runtime.status().await{Ok(status)=>{tx.send_if_modified(|old|{if *old!=status{*old=status;true}else{false}});},Err(e)=>break e}}
+                request=rx.recv()=>{
+                    let Some(request)=request else{let _=runtime.close().await;return;};
+                    if matches!(request.command,Command::Stop){let result=runtime.close().await;tx.send_replace(Status{adapter:config.adapter.clone(),..Default::default()});let _=request.result.send(result);return;}
+                    if request.expires<=Instant::now()||request.result.is_closed(){runtime.release().await;continue;}
+                    let action = matches!(&request.command, Command::Action(_));
+                    let result=runtime.execute(request.command).await;
+                    if result.is_err(){runtime.release().await;}
+                    if action {
+                        if let Ok(status) = runtime.status().await { tx.send_replace(status); }
+                    }
+                    let _=request.result.send(result);
+                }
+            }
+        };
+        let restore = runtime.close().await;
+        generation = runtime.generation.wrapping_add(1);
+        tx.send_replace(Status {
+            adapter: config.adapter.clone(),
+            error: Some(format!("{failure}; cleanup: {restore:?}")),
+            generation,
+            ..Default::default()
+        });
+        drop(runtime);
+        tokio::time::sleep(Duration::from_secs(2)).await;
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn closing_pairing_preserves_completed_bonds_but_releases_unpaired_targets() {
+        let shared = Shared::new(Some("10:6F:D9:66:97:88".into()));
+        let mut state = shared.state.lock().unwrap();
+        state.pairing_until = Some(Instant::now() + Duration::from_secs(120));
+        state.close_pairing(true, None);
+        assert_eq!(state.peer.as_deref(), Some("10:6F:D9:66:97:88"));
+        assert!(state.pairing_until.is_none());
+        state.close_pairing(false, None);
+        assert!(state.peer.is_none());
+    }
+    #[test]
+    fn configuration_validation() {
+        let mut c = Config {
+            adapter: "hci0".into(),
+            name: "One-KVM".into(),
+            peer: None,
+        };
+        assert!(c.validate().is_ok());
+        c.adapter = "hci0;reboot".into();
+        assert!(c.validate().is_err());
+        c.adapter = "hci1".into();
+        c.peer = Some("bogus".into());
+        assert!(c.validate().is_err());
+    }
+    #[test]
+    fn peer_isolation() {
+        let state = Shared::new(Some("10:6F:D9:66:97:88".into()));
+        assert!(state.allowed("10:6F:D9:66:97:88".parse().unwrap()));
+        assert!(!state.allowed("10:6F:D9:66:97:89".parse().unwrap()));
+    }
+    #[test]
+    fn new_bond_without_agent_callback_completes_pairing() {
+        let shared = Shared::new(None);
+        let mut state = shared.state.lock().unwrap();
+        state.pairing_until = Some(Instant::now() + Duration::from_secs(120));
+        let peer = "10:6F:D9:66:97:88";
+        state.observe_bond(peer, false);
+        assert_eq!(state.peer, None);
+        state.observe_bond(peer, true);
+        assert_eq!(state.peer.as_deref(), Some(peer));
+        assert!(state.pairing_completed(true));
+        // A second computer cannot replace the one selected in this window.
+        state.observe_bond("10:6F:D9:66:97:89", true);
+        assert_eq!(state.peer.as_deref(), Some(peer));
+    }
+    #[test]
+    fn old_bond_does_not_finish_a_new_window() {
+        let peer = "10:6F:D9:66:97:88";
+        let shared = Shared::new(Some(peer.into()));
+        let mut state = shared.state.lock().unwrap();
+        state.pairing_until = Some(Instant::now() + Duration::from_secs(120));
+        state.bonded_before_pairing.insert(peer.into());
+        state.observe_bond(peer, true);
+        assert!(!state.pairing_completed(true));
+        state.peer = None;
+        state.observe_bond(peer, true);
+        assert_eq!(state.peer, None);
+    }
+    #[test]
+    fn bond_observation_respects_closed_window_and_pinned_peer() {
+        let peer = "10:6F:D9:66:97:88";
+        let shared = Shared::new(None);
+        let mut state = shared.state.lock().unwrap();
+        state.observe_bond(peer, true);
+        assert_eq!(state.peer, None);
+        state.pairing_until = Some(Instant::now() - Duration::from_secs(1));
+        state.observe_bond(peer, true);
+        assert_eq!(state.peer, None);
+        state.pairing_until = Some(Instant::now() + Duration::from_secs(120));
+        state.peer = Some("10:6F:D9:66:97:89".into());
+        state.observe_bond(peer, true);
+        assert_eq!(state.peer.as_deref(), Some("10:6F:D9:66:97:89"));
+    }
+}
+
+#[derive(Serialize)]
+pub struct AdapterInfo {
+    pub name: String,
+    pub address: String,
+    pub powered: bool,
+}
+pub async fn adapters() -> Result<Vec<AdapterInfo>, String> {
+    let session = Session::new().await.map_err(|e| e.to_string())?;
+    let mut output = vec![];
+    for name in session.adapter_names().await.map_err(|e| e.to_string())? {
+        let adapter = session.adapter(&name).map_err(|e| e.to_string())?;
+        output.push(AdapterInfo {
+            name,
+            address: adapter
+                .address()
+                .await
+                .map_err(|e| e.to_string())?
+                .to_string(),
+            powered: adapter.is_powered().await.map_err(|e| e.to_string())?,
+        });
+    }
+    Ok(output)
+}

libs/bluetooth-hid/src/protocol.rs

@@ -0,0 +1,267 @@
+//! Classic HIDP framing and report descriptor.
+use crate::Report;
+pub const MAP: &[u8] = &[
+    0x05, 0x01, 0x09, 0x06, 0xa1, 0x01, 0x85, 0x01, 0x05, 0x07, 0x19, 0xe0, 0x29, 0xe7, 0x15, 0x00,
+    0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0x95, 0x01, 0x75, 0x08, 0x81, 0x01, 0x95, 0x05,
+    0x75, 0x01, 0x05, 0x08, 0x19, 0x01, 0x29, 0x05, 0x91, 0x02, 0x95, 0x01, 0x75, 0x03, 0x91, 0x01,
+    0x95, 0x06, 0x75, 0x08, 0x15, 0x00, 0x25, 0x65, 0x05, 0x07, 0x19, 0x00, 0x29, 0x65, 0x81, 0x00,
+    0xc0, 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x85, 0x02, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19,
+    0x01, 0x29, 0x05, 0x15, 0x00, 0x25, 0x01, 0x95, 0x05, 0x75, 0x01, 0x81, 0x02, 0x95, 0x01, 0x75,
+    0x03, 0x81, 0x01, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75,
+    0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0, 0x05, 0x0c, 0x09, 0x01, 0xa1, 0x01, 0x85, 0x03, 0x15,
+    0x00, 0x26, 0xff, 0x03, 0x19, 0x00, 0x2a, 0xff, 0x03, 0x75, 0x10, 0x95, 0x01, 0x81, 0x00, 0xc0,
+];
+
+pub const HID_UUID: &str = "00001124-0000-1000-8000-00805f9b34fb";
+pub fn sdp() -> String {
+    let hex: String = MAP.iter().map(|byte| format!("{byte:02x}")).collect();
+    format!(
+        r#"<?xml version="1.0"?>
+<record>
+  <attribute id="0x0001"><sequence><uuid value="0x1124"/></sequence></attribute>
+  <attribute id="0x0004"><sequence><sequence><uuid value="0x0100"/><uint16 value="0x0011"/></sequence><sequence><uuid value="0x0011"/></sequence></sequence></attribute>
+  <attribute id="0x0005"><sequence><uuid value="0x1002"/></sequence></attribute>
+  <attribute id="0x0006"><sequence><uint16 value="0x656e"/><uint16 value="0x006a"/><uint16 value="0x0100"/></sequence></attribute>
+  <attribute id="0x0009"><sequence><sequence><uuid value="0x1124"/><uint16 value="0x0100"/></sequence></sequence></attribute>
+  <attribute id="0x000d"><sequence><sequence><sequence><uuid value="0x0100"/><uint16 value="0x0013"/></sequence><sequence><uuid value="0x0011"/></sequence></sequence></sequence></attribute>
+  <attribute id="0x0100"><text value="One-KVM Keyboard and Mouse"/></attribute>
+  <attribute id="0x0101"><text value="Classic Bluetooth HID"/></attribute>
+  <attribute id="0x0102"><text value="One-KVM"/></attribute>
+  <attribute id="0x0200"><uint16 value="0x0100"/></attribute>
+  <attribute id="0x0201"><uint16 value="0x0111"/></attribute>
+  <attribute id="0x0202"><uint8 value="0xc0"/></attribute>
+  <attribute id="0x0203"><uint8 value="0x00"/></attribute>
+  <attribute id="0x0204"><boolean value="false"/></attribute>
+  <attribute id="0x0205"><boolean value="false"/></attribute>
+  <attribute id="0x0206"><sequence><sequence><uint8 value="0x22"/><text encoding="hex" value="{hex}"/></sequence></sequence></attribute>
+  <attribute id="0x0207"><sequence><sequence><uint16 value="0x0409"/><uint16 value="0x0100"/></sequence></sequence></attribute>
+  <attribute id="0x0209"><boolean value="false"/></attribute>
+  <attribute id="0x020a"><boolean value="false"/></attribute>
+  <attribute id="0x020b"><uint16 value="0x0100"/></attribute>
+  <attribute id="0x020c"><uint16 value="0x0c80"/></attribute>
+  <attribute id="0x020d"><boolean value="true"/></attribute>
+  <attribute id="0x020e"><boolean value="true"/></attribute>
+</record>"#
+    )
+}
+#[derive(Debug, Default)]
+pub struct HidProtocol {
+    pub boot: bool,
+    pub suspended: bool,
+    pub leds: u8,
+    pub keyboard: [u8; 8],
+    pub buttons: u8,
+    pub consumer: [u8; 2],
+}
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct ControlResult {
+    pub reply: Option<Vec<u8>>,
+    pub unplug: bool,
+    pub reset: bool,
+}
+impl HidProtocol {
+    pub fn input(&mut self, kind: Report, value: &[u8]) -> Result<Vec<u8>, String> {
+        if value.len() != kind.len() {
+            return Err("Invalid HID report length".into());
+        }
+        if self.suspended {
+            return Err("Bluetooth HID is suspended".into());
+        }
+        let mut packet = vec![0xa1, kind.id()];
+        match kind {
+            Report::Keyboard => {
+                self.keyboard.copy_from_slice(value);
+                packet.extend_from_slice(value);
+            }
+            Report::Mouse => {
+                self.buttons = value[0];
+                packet.extend_from_slice(&value[..if self.boot { 3 } else { 4 }]);
+                if self.boot {
+                    packet[2] &= 7;
+                }
+            }
+            Report::Consumer if !self.boot => {
+                self.consumer.copy_from_slice(value);
+                packet.extend_from_slice(value);
+            }
+            Report::Consumer => return Err("Consumer keys unavailable in boot protocol".into()),
+        }
+        Ok(packet)
+    }
+    pub fn release(&mut self) -> Vec<Vec<u8>> {
+        self.keyboard = [0; 8];
+        self.buttons = 0;
+        self.consumer = [0; 2];
+        let mut packets = vec![
+            vec![0xa1, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+            if self.boot {
+                vec![0xa1, 2, 0, 0, 0]
+            } else {
+                vec![0xa1, 2, 0, 0, 0, 0]
+            },
+        ];
+        if !self.boot {
+            packets.push(vec![0xa1, 3, 0, 0]);
+        }
+        packets
+    }
+    pub fn output(&mut self, data: &[u8]) -> bool {
+        if data.len() == 3 && data[0] == 0xa2 && data[1] == 1 {
+            self.leds = data[2] & 0x1f;
+            true
+        } else {
+            false
+        }
+    }
+    pub fn control(&mut self, data: &[u8]) -> ControlResult {
+        let mut result = ControlResult::default();
+        let handshake = |code| ControlResult {
+            reply: Some(vec![code]),
+            ..Default::default()
+        };
+        let Some(&header) = data.first() else {
+            return handshake(4);
+        };
+        match header {
+            0x13 if data.len() == 1 => {
+                self.suspended = true;
+                result.reset = true;
+            }
+            0x14 if data.len() == 1 => {
+                self.suspended = false;
+                result.reset = true;
+            }
+            0x15 if data.len() == 1 => {
+                result.unplug = true;
+            }
+            0x11 | 0x12 if data.len() == 1 => {
+                self.suspended = false;
+                result.reset = true;
+            }
+            0x60 if data.len() == 1 => {
+                result.reply = Some(vec![0xa0, if self.boot { 0 } else { 1 }]);
+            }
+            0x70 | 0x71 if data.len() == 1 => {
+                self.boot = header == 0x70;
+                result.reply = Some(vec![0]);
+                result.reset = true;
+            }
+            0x52 if data.len() == 3 && data[1] == 1 => {
+                self.leds = data[2] & 0x1f;
+                return handshake(0);
+            }
+            0x41 | 0x49 | 0x42 | 0x4a => {
+                let sized = header & 8 != 0;
+                if data.len() != if sized { 4 } else { 2 } {
+                    return handshake(4);
+                }
+                let mut report = vec![0xa0 | (header & 3), data[1]];
+                match (header & 3, data[1]) {
+                    (1, 1) => report.extend(self.keyboard),
+                    (1, 2) => report.extend(if self.boot {
+                        vec![self.buttons & 7, 0, 0]
+                    } else {
+                        vec![self.buttons, 0, 0, 0]
+                    }),
+                    (1, 3) if !self.boot => report.extend(self.consumer),
+                    (2, 1) => report.push(self.leds),
+                    _ => return handshake(2),
+                }
+                if sized {
+                    report.truncate(1 + u16::from_le_bytes([data[2], data[3]]) as usize);
+                }
+                result.reply = Some(report);
+            }
+            _ => return handshake(3), // ERR_UNSUPPORTED_REQUEST
+        }
+        result
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn classic_frames_and_boot_protocol() {
+        let mut hid = HidProtocol::default();
+        assert_eq!(
+            hid.input(Report::Keyboard, &[2, 0, 4, 0, 0, 0, 0, 0])
+                .unwrap(),
+            [0xa1, 1, 2, 0, 4, 0, 0, 0, 0, 0]
+        );
+        assert_eq!(hid.control(&[0x60]).reply.unwrap(), [0xa0, 1]);
+        assert_eq!(hid.control(&[0x70]).reply.unwrap(), [0]);
+        assert_eq!(
+            hid.input(Report::Mouse, &[0x1f, 127, 128, 1]).unwrap(),
+            [0xa1, 2, 7, 127, 128]
+        );
+        assert!(hid.input(Report::Consumer, &[0, 0]).is_err());
+        assert!(hid.input(Report::Keyboard, &[0]).is_err());
+    }
+    #[test]
+    fn led_read_write_and_errors() {
+        let mut hid = HidProtocol::default();
+        assert!(hid.output(&[0xa2, 1, 3]));
+        assert_eq!(hid.leds, 3);
+        assert_eq!(hid.control(&[0x42, 1]).reply.unwrap(), [0xa2, 1, 3]);
+        assert_eq!(hid.control(&[0x52, 1, 2]).reply.unwrap(), [0]);
+        assert_eq!(hid.leds, 2);
+        assert_eq!(hid.control(&[0x41, 99]).reply.unwrap(), [2]);
+        assert_eq!(hid.control(&[0x41]).reply.unwrap(), [4]);
+        assert_eq!(hid.control(&[0x90, 0]).reply.unwrap(), [3]);
+        assert_eq!(
+            hid.control(&[0x49, 1, 3, 0]).reply.unwrap(),
+            [0xa1, 1, 0, 0]
+        );
+    }
+    #[test]
+    fn suspend_reset_and_virtual_unplug() {
+        let mut hid = HidProtocol::default();
+        assert!(hid.control(&[0x13]).reset);
+        assert!(hid.input(Report::Mouse, &[0; 4]).is_err());
+        assert!(hid.control(&[0x14]).reset);
+        assert!(hid.input(Report::Mouse, &[0; 4]).is_ok());
+        assert!(hid.control(&[0x15]).unplug);
+        hid.keyboard[2] = 4;
+        hid.buttons = 1;
+        assert_eq!(hid.release().len(), 3);
+        assert_eq!(hid.keyboard, [0; 8]);
+        assert_eq!(hid.buttons, 0);
+    }
+    #[test]
+    fn sdp_describes_both_classic_channels() {
+        let record = sdp();
+        assert!(record.contains("uuid value=\"0x1124\""));
+        assert!(record.contains("uint16 value=\"0x0011\""));
+        assert!(record.contains("uint16 value=\"0x0013\""));
+        assert!(!record.contains("0x1812"));
+    }
+    #[test]
+    fn descriptor_report_sizes() {
+        let (mut pos, mut size, mut count, mut id, mut depth) = (0, 0, 0, 0, 0);
+        let mut input = [0; 4];
+        let mut output = [0; 4];
+        while pos < MAP.len() {
+            let prefix = MAP[pos];
+            pos += 1;
+            let length = [0, 1, 2, 4][(prefix & 3) as usize];
+            let mut value = 0;
+            for i in 0..length {
+                value |= (MAP[pos + i] as usize) << (8 * i);
+            }
+            pos += length;
+            match ((prefix >> 2) & 3, prefix >> 4) {
+                (1, 7) => size = value,
+                (1, 8) => id = value,
+                (1, 9) => count = value,
+                (0, 8) => input[id] += size * count,
+                (0, 9) => output[id] += size * count,
+                (0, 10) => depth += 1,
+                (0, 12) => depth -= 1,
+                _ => {}
+            }
+        }
+        assert_eq!(depth, 0);
+        assert_eq!(input, [0, 64, 32, 16]);
+        assert_eq!(output, [0, 8, 0, 0]);
+    }
+}

libs/hwcodec/Cargo.toml

@@ -3,6 +3,9 @@ name = "hwcodec"
 version = "0.8.0"
 edition = "2021"
 description = "Hardware video codec for IP-KVM (Windows/Linux)"
+# This crate contains code derived from RustDesk hwcodec (AGPL-3.0).
+# See NOTICE in this directory and the LICENSE file in the repository root.
+license = "AGPL-3.0-only"
 
 [package.metadata.cargo-machete]
 ignored = ["serde"]

libs/hwcodec/NOTICE

@@ -0,0 +1,28 @@
+Third-Party Code Attribution
+=============================
+
+This crate (the Rust code under src/, the C/C++ code under cpp/, build.rs and
+README.md) is derived from the hwcodec component of the RustDesk project
+(https://github.com/rustdesk/rustdesk), "a real-time hardware codec library
+for RustDesk based on FFmpeg".
+
+Upstream work:
+  RustDesk hwcodec - https://github.com/rustdesk/rustdesk/tree/master/libs/hwcodec
+  Copyright (C) the RustDesk contributors
+  Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only)
+
+Modifications:
+  The code was ported, restructured and modified for the One-KVM build
+  (including FFmpeg integration changes described in README.md). Per sections
+  4 and 5 of the AGPL-3.0, the modified files remain licensed under
+  AGPL-3.0-only.
+
+This library links against FFmpeg configured with --enable-gpl
+(--enable-version3), x264 and x265, each distributed under the GPL-2.0-or-later
+(see build/debian/copyright and the repository root LICENSE).
+
+The complete AGPL-3.0 license text can be found in the LICENSE file at the
+repository root and at: https://www.gnu.org/licenses/agpl-3.0.en.html
+
+The corresponding source code of One-KVM is available at
+https://github.com/mofeng-git/One-KVM (see the release tags).

libs/hwcodec/build.rs

@@ -5,7 +5,8 @@ use std::{
 };
 
 fn main() {
-    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    // Read the current source path when running, since build artifacts may move.
+    let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
     let cpp_dir = manifest_dir.join("cpp");
     println!("cargo:rerun-if-changed=src");
     println!("cargo:rerun-if-changed={}", cpp_dir.display());
@@ -17,7 +18,7 @@ fn main() {
 }
 
 fn build_common(builder: &mut Build) {
-    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
     let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap();
     let common_dir = manifest_dir.join("cpp").join("common");
 
@@ -367,7 +368,7 @@ mod ffmpeg {
     }
 
     fn ffmpeg_ffi() {
-        let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+        let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
         let ffmpeg_ram_dir = manifest_dir.join("cpp").join("common");
         let ffi_header_path = ffmpeg_ram_dir.join("ffmpeg_ffi.h");
         println!("cargo:rerun-if-changed={}", ffi_header_path.display());
@@ -381,7 +382,7 @@ mod ffmpeg {
     }
 
     fn build_ffmpeg_ram(builder: &mut Build) {
-        let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+        let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
         let ffmpeg_ram_dir = manifest_dir.join("cpp").join("ffmpeg_ram");
         let ffi_header = ffmpeg_ram_dir
             .join("ffmpeg_ram_ffi.h")
@@ -420,7 +421,7 @@ mod ffmpeg {
             return;
         }
 
-        let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+        let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
         let capture_header = manifest_dir
             .join("cpp")
             .join("ffmpeg_capture_ffi.h")
@@ -443,7 +444,7 @@ mod ffmpeg {
     }
 
     fn build_ffmpeg_hw(builder: &mut Build) {
-        let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+        let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
         let ffmpeg_hw_dir = manifest_dir.join("cpp").join("ffmpeg_hw");
         let ffi_header = ffmpeg_hw_dir
             .join("ffmpeg_hw_ffi.h")
@@ -487,6 +488,7 @@ mod ffmpeg {
                 }
             }
             builder.file(ffmpeg_hw_dir.join("ffmpeg_hw_mjpeg_h26x.cpp"));
+            builder.file(ffmpeg_hw_dir.join("rkmpp_dmabuf.cpp"));
         } else {
             println!(
                 "cargo:info=Skipping ffmpeg_hw_mjpeg_h26x.cpp (RKMPP) for arch {}",

libs/hwcodec/cpp/common/platform/linux/linux.cpp

@@ -146,6 +146,67 @@ int linux_support_v4l2m2m() {
     return false;
   };
 
+  auto is_qcom_platform = [&]() -> bool {
+    const char *platform_hints[] = {
+      "qcom",
+      "qualcomm",
+      "venus",
+      "iris",
+      "sc7280",
+      "qcm6490",
+      "qcs6490",
+    };
+
+    const char *platform_files[] = {
+      "/proc/device-tree/compatible",
+      "/proc/device-tree/model",
+      "/sys/firmware/devicetree/base/compatible",
+      "/sys/firmware/devicetree/base/model",
+    };
+
+    for (size_t i = 0; i < sizeof(platform_files) / sizeof(platform_files[0]); i++) {
+      std::string value;
+      if (read_text_file(platform_files[i], &value) &&
+          contains_any(to_lower(value), platform_hints,
+                       sizeof(platform_hints) / sizeof(platform_hints[0]))) {
+        return true;
+      }
+    }
+
+    const char *video_nodes[] = {
+      "video0",
+      "video1",
+      "video2",
+      "video3",
+      "video10",
+      "video11",
+      "video32",
+    };
+    const char *video_hints[] = {
+      "qcom-iris",
+      "qcom,",
+      "venus",
+      "iris",
+    };
+
+    for (size_t i = 0; i < sizeof(video_nodes) / sizeof(video_nodes[0]); i++) {
+      std::string name;
+      std::string modalias;
+      const std::string base = std::string("/sys/class/video4linux/") + video_nodes[i];
+      if (read_text_file((base + "/name").c_str(), &name) &&
+          contains_any(to_lower(name), video_hints, sizeof(video_hints) / sizeof(video_hints[0]))) {
+        return true;
+      }
+      if (read_text_file((base + "/device/modalias").c_str(), &modalias) &&
+          contains_any(to_lower(modalias), video_hints,
+                       sizeof(video_hints) / sizeof(video_hints[0]))) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
   auto is_amlogic_platform = [&]() -> bool {
     const char *platform_hints[] = {
       "amlogic",
@@ -210,7 +271,8 @@ int linux_support_v4l2m2m() {
     return false;
   };
 
-  const bool amlogic_platform = is_amlogic_platform();
+  const bool qcom_platform = is_qcom_platform();
+  const bool amlogic_platform = !qcom_platform && is_amlogic_platform();
   if (amlogic_platform && !v4l2m2m_allowed()) {
     LOG_WARN(std::string(
         "V4L2 M2M: skipped probe on Amlogic platform; set ONE_KVM_V4L2M2M_ALLOW=1 to enable"));

libs/hwcodec/cpp/common/util.cpp

@@ -4,6 +4,9 @@ extern "C" {
 }
 
 #include "util.h"
+#include <algorithm>
+#include <cctype>
+#include <fstream>
 #include <limits>
 #include <map>
 #include <string.h>
@@ -45,17 +48,46 @@ bool is_software_hevc(const std::string &name) {
   return true;
 }
 
+bool is_qcom_iris_driver() {
+  const char *driver_path = "/sys/class/video4linux/video1/name";
+  std::ifstream file(driver_path);
+  if (!file.is_open()) return false;
+
+  std::string value;
+  std::getline(file, value, '\0');
+  std::transform(value.begin(), value.end(), value.begin(), [](unsigned char c) {
+    return static_cast<char>(std::tolower(c));
+  });
+  return value.find("qcom-iris") != std::string::npos ||
+         value.find("iris-encoder") != std::string::npos ||
+         value.find("iris") != std::string::npos;
+}
+
 } // anonymous namespace
 
 namespace util_encode {
 
+bool is_qcom_iris_platform() {
+  return is_qcom_iris_driver();
+}
+
+bool supports_forced_keyframe(const std::string &name) {
+  if (name.find("v4l2m2m") != std::string::npos && is_qcom_iris_platform()) {
+    return false;
+  }
+  return true;
+}
+
 void set_av_codec_ctx(AVCodecContext *c, const std::string &name, int kbs,
                       int gop, int fps, int thread_count) {
   c->has_b_frames = 0;
   c->max_b_frames = 0;
-  if (gop > 0 && gop < std::numeric_limits<int16_t>::max()) {
-    c->gop_size = gop;
-    c->keyint_min = gop; // Match keyint_min to gop for consistent keyframe interval
+  const bool qcom_iris_v4l2 =
+      name.find("v4l2m2m") != std::string::npos && is_qcom_iris_platform();
+  const int effective_gop = qcom_iris_v4l2 ? std::max(5, fps / 3) : gop;
+  if (effective_gop > 0 && effective_gop < std::numeric_limits<int16_t>::max()) {
+    c->gop_size = effective_gop;
+    c->keyint_min = effective_gop; // Match keyint_min to gop for consistent keyframe interval
   } else if (name.find("vaapi") != std::string::npos) {
     c->gop_size = fps > 0 ? fps : 30; // Default to 1 second keyframe interval
     c->keyint_min = c->gop_size;
@@ -120,7 +152,8 @@ bool set_lantency_free(void *priv_data, const std::string &name) {
   }
   if (name.find("amf") != std::string::npos) {
     if ((ret = av_opt_set(priv_data, "query_timeout", "1000", 0)) < 0) {
-      LOG_WARN(std::string("amf query_timeout option is unavailable, ret = ") + av_err2str(ret));
+      LOG_DEBUG(std::string("amf query_timeout option is unavailable, ret = ") +
+                av_err2str(ret));
     }
   }
   if (name.find("qsv") != std::string::npos) {
@@ -139,7 +172,8 @@ bool set_lantency_free(void *priv_data, const std::string &name) {
   if (name.find("rkmpp") != std::string::npos) {
     // Set async_depth to 1 for minimal buffering (0 = synchronous, higher = more buffering)
     if ((ret = av_opt_set(priv_data, "async_depth", "1", 0)) < 0) {
-      LOG_WARN(std::string("rkmpp set async_depth failed, ret = ") + av_err2str(ret));
+      LOG_DEBUG(std::string("rkmpp async_depth option is unavailable, ret = ") +
+                av_err2str(ret));
       // Not fatal - older FFmpeg versions may not support this option
     }
   }
@@ -147,11 +181,14 @@ bool set_lantency_free(void *priv_data, const std::string &name) {
   if (name.find("v4l2m2m") != std::string::npos) {
     // Minimize number of output buffers for lower latency
     if ((ret = av_opt_set_int(priv_data, "num_output_buffers", 4, 0)) < 0) {
-      LOG_WARN(std::string("v4l2m2m set num_output_buffers failed, ret = ") + av_err2str(ret));
+      LOG_DEBUG(std::string("v4l2m2m num_output_buffers option is unavailable, ret = ") +
+                av_err2str(ret));
       // Not fatal
     }
-    if ((ret = av_opt_set_int(priv_data, "num_capture_buffers", 4, 0)) < 0) {
-      LOG_WARN(std::string("v4l2m2m set num_capture_buffers failed, ret = ") + av_err2str(ret));
+    const int capture_buffers = is_qcom_iris_driver() ? 12 : 8;
+    if ((ret = av_opt_set_int(priv_data, "num_capture_buffers", capture_buffers, 0)) < 0) {
+      LOG_DEBUG(std::string("v4l2m2m num_capture_buffers option is unavailable, ret = ") +
+                av_err2str(ret));
       // Not fatal
     }
   }
@@ -360,6 +397,14 @@ struct CodecOptions {
 
 bool set_rate_control(AVCodecContext *c, const std::string &name, int rc,
                       int q) {
+  // Remote-desktop content is usually sparse. VBR avoids padding static
+  // frames up to the target bitrate while allowing short bursts for screen
+  // changes. Keep those bursts bounded at twice the target bitrate.
+  if (rc == RC_VBR && c->bit_rate > 0) {
+    c->rc_max_rate = c->bit_rate * 2;
+    c->rc_buffer_size = c->rc_max_rate;
+  }
+
   if (name.find("vaapi") != std::string::npos && rc == RC_CQ) {
     // Used only after the normal bitrate-based VAAPI initialization fails.
     // Some drivers, including Intel iHD on Jasper Lake, expose CQP as their
@@ -458,6 +503,10 @@ bool set_others(void *priv_data, const std::string &name) {
 bool change_bit_rate(AVCodecContext *c, const std::string &name, int kbs) {
   if (kbs > 0) {
     c->bit_rate = kbs * 1000;
+    if (c->rc_max_rate > 0 && name.find("qsv") == std::string::npos) {
+      c->rc_max_rate = c->bit_rate * 2;
+      c->rc_buffer_size = c->rc_max_rate;
+    }
     if (name.find("qsv") != std::string::npos) {
       c->rc_max_rate = c->bit_rate;
     }

libs/hwcodec/cpp/common/util.h

@@ -9,6 +9,9 @@ extern "C" {
 
 namespace util_encode {
 
+bool is_qcom_iris_platform();
+bool supports_forced_keyframe(const std::string &name);
+
 void set_av_codec_ctx(AVCodecContext *c, const std::string &name, int kbs,
                       int gop, int fps, int thread_count);
 bool set_lantency_free(void *priv_data, const std::string &name);

libs/hwcodec/cpp/ffmpeg_hw/rkmpp_dma_jpeg.h

@@ -0,0 +1,38 @@
+#pragma once
+#include <stddef.h>
+#include <stdint.h>
+
+// Validate bounded JPEG headers before giving hardware a fixed-size output
+// buffer. Only baseline 8-bit JPEG is accepted; other streams use copy fallback.
+// No scan-data traversal or full-packet copy is needed.
+inline bool rkmpp_dma_jpeg_header(const uint8_t *data, size_t size, int width, int height) {
+    if (!data || size < 4 || data[0] != 0xff || data[1] != 0xd8) return false;
+    size_t pos = 2;
+    bool sof = false;
+    while (pos < size) {
+        if (data[pos++] != 0xff) return false;
+        while (pos < size && data[pos] == 0xff) ++pos;
+        if (pos == size) return false;
+        const unsigned marker = data[pos++];
+        if (!marker || marker == 0xd8 || marker == 0xd9 || marker == 1 ||
+            (marker >= 0xd0 && marker <= 0xd7)) return false;
+        if (size - pos < 2) return false;
+        const size_t length = (size_t(data[pos]) << 8) | data[pos + 1];
+        if (length < 2 || length > size - pos) return false;
+        if (marker == 0xc0) {
+            if (sof || length < 8 || data[pos + 2] != 8) return false;
+            const unsigned h = (unsigned(data[pos + 3]) << 8) | data[pos + 4];
+            const unsigned w = (unsigned(data[pos + 5]) << 8) | data[pos + 6];
+            const unsigned components = data[pos + 7];
+            if (w != unsigned(width) || h != unsigned(height) ||
+                (components != 1 && components != 3) || length != 8 + 3 * components) return false;
+            sof = true;
+        } else if (marker >= 0xc0 && marker <= 0xcf && marker != 0xc4 && marker != 0xcc) {
+            return false; // Progressive, lossless, extended or differential SOF.
+        } else if (marker == 0xda) {
+            return sof && length >= 6 && size - pos > length;
+        }
+        pos += length;
+    }
+    return false;
+}

libs/hwcodec/cpp/ffmpeg_hw/rkmpp_dmabuf.cpp

@@ -0,0 +1,329 @@
+#include "rkmpp_dmabuf_ffi.h"
+#include <array>
+#include <cstdio>
+#include <limits>
+#include <new>
+#include "rkmpp_dma_jpeg.h"
+
+// Native MPP is already linked by the ARM FFmpeg/RKMPP build. Keep this
+// optional for toolchains which only supply the FFmpeg headers.
+#if defined(__linux__) && __has_include(<rockchip/rk_mpi.h>)
+#define HAVE_MPP_DMA 1
+#include <cerrno>
+#include <linux/dma-buf.h>
+#include <sys/ioctl.h>
+extern "C" {
+#include <rockchip/rk_mpi.h>
+#include <rockchip/mpp_buffer.h>
+#include <rockchip/mpp_frame.h>
+#include <rockchip/mpp_packet.h>
+#include <rockchip/mpp_task.h>
+#include <rockchip/rk_venc_cfg.h>
+#include <rockchip/rk_venc_rc.h>
+}
+#endif
+
+static thread_local char dma_error[192] = {};
+static int fail(const char *operation, int code) {
+    std::snprintf(dma_error, sizeof(dma_error), "%s (ret=%d)", operation, code);
+    return -1;
+}
+
+#ifdef HAVE_MPP_DMA
+struct RkmppDmaEncoder {
+    MppCtx ctx = nullptr;
+    MppApi *api = nullptr;
+    MppEncCfg cfg = nullptr;
+    MppPacket packet = nullptr;
+    std::array<MppBuffer, 16> buffers{};
+    std::array<size_t, 16> capacities{};
+    size_t count = 0;
+    size_t minimum = 0;
+    int width = 0, height = 0, stride = 0;
+    MppFrameFormat format = MPP_FMT_YUV420SP;
+    bool jpeg = false;
+    MppCtx decoder = nullptr;
+    MppApi *dec_api = nullptr;
+    MppBufferGroup decoded_group = nullptr;
+    MppBuffer decoded_buffer = nullptr;
+    MppFrame decoded_frame = nullptr;
+    MppPacket input_packet = nullptr;
+    bool decoded_layout_set = false;
+    int decoded_stride = 0, decoded_vstride = 0;
+
+    void close() {
+        if (packet) mpp_packet_deinit(&packet);
+        if (ctx) {
+            // A timeout must not expose still-in-use input to V4L2 QBUF.
+            api->reset(ctx);
+            mpp_destroy(ctx);
+            ctx = nullptr;
+        }
+        // On any decoder failure, end hardware access before releasing the
+        // input packet, exported buffers, or allowing the caller's QBUF.
+        if (decoder) {
+            dec_api->reset(decoder);
+            mpp_destroy(decoder);
+            decoder = nullptr;
+        }
+        if (input_packet) mpp_packet_deinit(&input_packet);
+        if (decoded_frame) mpp_frame_deinit(&decoded_frame);
+        if (decoded_buffer) { mpp_buffer_put(decoded_buffer); decoded_buffer = nullptr; }
+        if (decoded_group) { mpp_buffer_group_put(decoded_group); decoded_group = nullptr; }
+        for (auto &buffer : buffers) {
+            if (buffer) { mpp_buffer_put(buffer); buffer = nullptr; }
+        }
+        if (cfg) { mpp_enc_cfg_deinit(cfg); cfg = nullptr; }
+    }
+    ~RkmppDmaEncoder() { close(); }
+};
+
+static bool set_cfg(RkmppDmaEncoder *e, const char *key, int value) {
+    int ret = mpp_enc_cfg_set_s32(e->cfg, key, value);
+    if (ret) fail(key, ret);
+    return ret == 0;
+}
+
+extern "C" int rkmpp_dma_reconfigure(RkmppDmaEncoder *e, int kbps, int gop) {
+    if (!e || !e->ctx || kbps <= 0 || kbps > 1000000 || gop <= 0)
+        return fail("invalid DMA encoder configuration", -1);
+    const int bps = kbps * 1000;
+    if (!set_cfg(e, "rc:bps_target", bps) ||
+        !set_cfg(e, "rc:bps_max", bps + bps / 16) ||
+        !set_cfg(e, "rc:bps_min", bps - bps / 16) ||
+        !set_cfg(e, "rc:gop", gop)) return -1;
+    int ret = e->api->control(e->ctx, MPP_ENC_SET_CFG, e->cfg);
+    return ret ? fail("MPP_ENC_SET_CFG", ret) : 0;
+}
+
+extern "C" RkmppDmaEncoder *rkmpp_dma_new(
+    int width, int height, int stride, int format, int codec, int fps,
+    int kbps, int gop, const int *fds, const size_t *sizes, size_t count) {
+    if (width <= 0 || height <= 0 || width > 8192 || height > 8192 ||
+        (width & 1) || (height & 1) || format < 0 || format > 4 ||
+        codec < 0 || codec > 1 || fps <= 0 || fps > 240 ||
+        (format != 4 && stride < width * (format == 1 || format == 3 ? 3 : format == 2 ? 2 : 1)) ||
+        (format == 2 && stride % 16 != 0) || !fds || !sizes || !count || count > 16) {
+        fail("invalid DMA frame layout", -1); return nullptr;
+    }
+    auto *e = new (std::nothrow) RkmppDmaEncoder;
+    if (!e) { fail("allocate DMA encoder", -1); return nullptr; }
+    e->width = width; e->height = height; e->stride = stride; e->count = count;
+    e->jpeg = format == 4;
+    if (e->jpeg) e->stride = stride = (width + 15) & ~15;
+    const int vstride = e->jpeg ? (height + 15) & ~15 : height;
+    e->format = format == 3 ? MPP_FMT_RGB888 : format == 2 ? MPP_FMT_YUV422_YUYV : format == 1 ? MPP_FMT_BGR888 : MPP_FMT_YUV420SP;
+    auto abort_init = [e](const char *op, int ret) -> RkmppDmaEncoder * {
+        fail(op, ret); delete e; return nullptr;
+    };
+    int ret = mpp_create(&e->ctx, &e->api);
+    if (ret) return abort_init("mpp_create", ret);
+    RK_S64 timeout = 2000;
+    ret = e->api->control(e->ctx, MPP_SET_OUTPUT_TIMEOUT, &timeout);
+    if (ret) return abort_init("MPP_SET_OUTPUT_TIMEOUT", ret);
+    ret = e->api->control(e->ctx, MPP_SET_INPUT_TIMEOUT, &timeout);
+    if (ret) return abort_init("MPP_SET_INPUT_TIMEOUT", ret);
+    ret = mpp_init(e->ctx, MPP_CTX_ENC, codec ? MPP_VIDEO_CodingHEVC : MPP_VIDEO_CodingAVC);
+    if (ret) return abort_init("mpp_init", ret);
+    ret = mpp_enc_cfg_init(&e->cfg);
+    if (ret) return abort_init("mpp_enc_cfg_init", ret);
+    ret = e->api->control(e->ctx, MPP_ENC_GET_CFG, e->cfg);
+    if (ret) return abort_init("MPP_ENC_GET_CFG", ret);
+    if (!set_cfg(e, "prep:width", width) || !set_cfg(e, "prep:height", height) ||
+        !set_cfg(e, "prep:hor_stride", stride) || !set_cfg(e, "prep:ver_stride", vstride) ||
+        !set_cfg(e, "prep:format", e->format) || !set_cfg(e, "rc:mode", MPP_ENC_RC_MODE_CBR) ||
+        !set_cfg(e, "rc:fps_in_flex", 0) || !set_cfg(e, "rc:fps_in_num", fps) ||
+        !set_cfg(e, "rc:fps_in_denorm", 1) || !set_cfg(e, "rc:fps_out_flex", 0) ||
+        !set_cfg(e, "rc:fps_out_num", fps) || !set_cfg(e, "rc:fps_out_denorm", 1) ||
+        !set_cfg(e, "codec:type", codec ? MPP_VIDEO_CodingHEVC : MPP_VIDEO_CodingAVC)) {
+        delete e; return nullptr;
+    }
+    // Match the browser-friendly baseline profile used by the existing RKMPP
+    // byte encoder, rather than inheriting MPP's High-profile default.
+    const int level = int64_t(width) * height * fps <= int64_t(1920) * 1080 * 60 ? 42 : 52;
+    if (!codec && (!set_cfg(e, "h264:profile", 66) || !set_cfg(e, "h264:level", level) ||
+                   !set_cfg(e, "h264:cabac_en", 0) || !set_cfg(e, "h264:trans8x8", 0))) {
+        delete e; return nullptr;
+    }
+    if (rkmpp_dma_reconfigure(e, kbps, gop)) { delete e; return nullptr; }
+    MppEncHeaderMode mode = MPP_ENC_HEADER_MODE_EACH_IDR;
+    ret = e->api->control(e->ctx, MPP_ENC_SET_HEADER_MODE, &mode);
+    if (ret) return abort_init("MPP_ENC_SET_HEADER_MODE", ret);
+    // Reject arithmetic overflow even on 32-bit ARM; stride is supplied by a driver.
+    if (size_t(stride) > std::numeric_limits<size_t>::max() / size_t(height))
+        return abort_init("DMA buffer size overflow", -1);
+    size_t minimum = size_t(stride) * height;
+    if (format == 0) {
+        if (minimum > std::numeric_limits<size_t>::max() / 3)
+            return abort_init("DMA buffer size overflow", -1);
+        minimum = minimum * 3 / 2;
+    }
+    if (e->jpeg) minimum = 68; // SOI/payload plus bounded hardware read headroom.
+    e->minimum = minimum;
+    for (size_t i = 0; i < count; ++i) {
+        if (fds[i] < 0 || sizes[i] < minimum) return abort_init("short DMA buffer", -1);
+        MppBufferInfo info{};
+        info.type = MPP_BUFFER_TYPE_EXT_DMA; info.fd = fds[i];
+        info.size = sizes[i]; info.index = static_cast<int>(i);
+        ret = mpp_buffer_import(&e->buffers[i], &info);
+        if (ret) return abort_init("mpp_buffer_import", ret);
+        e->capacities[i] = sizes[i];
+    }
+    if (e->jpeg) {
+        ret = mpp_create(&e->decoder, &e->dec_api);
+        if (ret) return abort_init("mpp_create JPEG decoder", ret);
+        ret = mpp_init(e->decoder, MPP_CTX_DEC, MPP_VIDEO_CodingMJPEG);
+        if (ret) return abort_init("mpp_init JPEG decoder", ret);
+        MppFrameFormat output = MPP_FMT_YUV420SP;
+        ret = e->dec_api->control(e->decoder, MPP_DEC_SET_OUTPUT_FORMAT, &output);
+        if (ret) return abort_init("JPEG NV12 output", ret);
+        ret = mpp_buffer_group_get_internal(&e->decoded_group, MPP_BUFFER_TYPE_DRM);
+        if (ret) return abort_init("JPEG output buffer group", ret);
+        // MPP JPEG requires aligned storage; reserve the conservative size used
+        // by its advanced-task decoder demo. One output reused after encode.
+        ret = mpp_buffer_get(e->decoded_group, &e->decoded_buffer, size_t(stride) * vstride * 4);
+        if (ret) return abort_init("JPEG output buffer", ret);
+        ret = mpp_frame_init(&e->decoded_frame);
+        if (ret) return abort_init("JPEG output frame", ret);
+        mpp_frame_set_buffer(e->decoded_frame, e->decoded_buffer);
+    }
+    return e;
+}
+
+static int dma_read_sync(MppBuffer buffer, bool start) {
+    dma_buf_sync sync{};
+    sync.flags = DMA_BUF_SYNC_READ | (start ? DMA_BUF_SYNC_START : DMA_BUF_SYNC_END);
+    int ret;
+    do { ret = ioctl(mpp_buffer_get_fd(buffer), DMA_BUF_IOCTL_SYNC, &sync); }
+    while (ret < 0 && errno == EINTR);
+    return ret;
+}
+
+static int decode_jpeg(RkmppDmaEncoder *e, size_t index, size_t bytes_used) {
+    MppBuffer input = e->buffers[index];
+    // The parser reads only header bytes with explicit DMA CPU-read ownership.
+    if (dma_read_sync(input, true)) return fail("JPEG DMA read sync start", errno);
+    const auto *data = static_cast<const uint8_t *>(mpp_buffer_get_ptr(input));
+    const bool valid = rkmpp_dma_jpeg_header(data, bytes_used, e->width, e->height);
+    if (dma_read_sync(input, false)) return fail("JPEG DMA read sync end", errno);
+    if (!valid) return fail("unsupported/mismatched JPEG header", -1);
+
+    int ret = mpp_packet_init_with_buffer(&e->input_packet, input);
+    if (ret) return fail("JPEG input packet", ret);
+    mpp_packet_set_length(e->input_packet, bytes_used);
+    MppTask task = nullptr;
+    ret = e->dec_api->poll(e->decoder, MPP_PORT_INPUT, static_cast<MppPollType>(2000));
+    if (ret) return fail("JPEG input poll", ret);
+    ret = e->dec_api->dequeue(e->decoder, MPP_PORT_INPUT, &task);
+    if (ret || !task) return fail("JPEG input task", ret);
+    ret = mpp_task_meta_set_packet(task, KEY_INPUT_PACKET, e->input_packet);
+    if (ret) return fail("JPEG input metadata", ret);
+    ret = mpp_task_meta_set_frame(task, KEY_OUTPUT_FRAME, e->decoded_frame);
+    if (ret) return fail("JPEG output metadata", ret);
+    ret = e->dec_api->enqueue(e->decoder, MPP_PORT_INPUT, task);
+    if (ret) return fail("JPEG submit", ret);
+    task = nullptr;
+    ret = e->dec_api->poll(e->decoder, MPP_PORT_OUTPUT, static_cast<MppPollType>(2000));
+    if (ret) return fail("JPEG output poll", ret);
+    ret = e->dec_api->dequeue(e->decoder, MPP_PORT_OUTPUT, &task);
+    if (ret || !task) return fail("JPEG output task", ret);
+    MppFrame result = nullptr;
+    ret = mpp_task_meta_get_frame(task, KEY_OUTPUT_FRAME, &result);
+    if (ret || result != e->decoded_frame) return fail("JPEG output frame mismatch", ret);
+    ret = e->dec_api->enqueue(e->decoder, MPP_PORT_OUTPUT, task);
+    if (ret) return fail("JPEG return output task", ret);
+    ret = e->dec_api->poll(e->decoder, MPP_PORT_INPUT, static_cast<MppPollType>(2000));
+    if (ret) return fail("JPEG input completion", ret);
+    mpp_packet_deinit(&e->input_packet);
+    if (mpp_frame_get_errinfo(result) || mpp_frame_get_discard(result) ||
+        mpp_frame_get_info_change(result) ||
+        mpp_frame_get_width(result) != unsigned(e->width) ||
+        mpp_frame_get_height(result) != unsigned(e->height) ||
+        mpp_frame_get_fmt(result) != MPP_FMT_YUV420SP ||
+        mpp_frame_get_buffer(result) != e->decoded_buffer) {
+        std::snprintf(dma_error, sizeof(dma_error),
+            "invalid JPEG decoded frame: err=%u discard=%u info_change=%u size=%ux%u fmt=%x buffer_match=%d",
+            mpp_frame_get_errinfo(result), mpp_frame_get_discard(result), mpp_frame_get_info_change(result),
+            mpp_frame_get_width(result), mpp_frame_get_height(result), unsigned(mpp_frame_get_fmt(result)),
+            int(mpp_frame_get_buffer(result) == e->decoded_buffer));
+        return -1;
+    }
+    const int hs = mpp_frame_get_hor_stride(result), vs = mpp_frame_get_ver_stride(result);
+    if (hs < e->width || vs < e->height || hs > 8192 || vs > 8192 || (hs & 15) || (vs & 15) ||
+        size_t(hs) * vs * 3 / 2 > mpp_buffer_get_size(e->decoded_buffer))
+        return fail("invalid JPEG decoded stride", -1);
+    if (!e->decoded_layout_set) {
+        if (!set_cfg(e, "prep:hor_stride", hs) || !set_cfg(e, "prep:ver_stride", vs)) return -1;
+        ret = e->api->control(e->ctx, MPP_ENC_SET_CFG, e->cfg);
+        if (ret) return fail("JPEG encoder layout", ret);
+        e->decoded_stride = hs; e->decoded_vstride = vs; e->decoded_layout_set = true;
+    } else if (hs != e->decoded_stride || vs != e->decoded_vstride) {
+        return fail("JPEG decoded layout changed", -1);
+    }
+    return 0;
+}
+
+extern "C" int rkmpp_dma_encode(RkmppDmaEncoder *e, size_t index, size_t bytes_used, int fresh_fd, int64_t pts_us,
+                                 int force_idr, const uint8_t **data, size_t *size) {
+    if (!e || !e->ctx || index >= e->count || !data || !size)
+        return fail("invalid DMA encode call", -1);
+    *data = nullptr; *size = 0;
+    if (e->packet) mpp_packet_deinit(&e->packet);
+    auto abort_encode = [e](const char *op, int ret) {
+        fail(op, ret); e->close(); return -1;
+    };
+    if (bytes_used > e->capacities[index] ||
+        (e->jpeg ? (bytes_used < 4 || e->capacities[index] - bytes_used < 64) : bytes_used != e->minimum))
+        return abort_encode("invalid DMA payload length", -1);
+    if (fresh_fd >= 0) {
+        MppBuffer replacement = nullptr;
+        MppBufferInfo info{};
+        info.type = MPP_BUFFER_TYPE_EXT_DMA; info.fd = fresh_fd;
+        info.size = e->capacities[index]; info.index = static_cast<int>(index);
+        const int ret = mpp_buffer_import(&replacement, &info);
+        if (ret) return abort_encode("refresh USB DMA import", ret);
+        if (e->buffers[index]) mpp_buffer_put(e->buffers[index]);
+        e->buffers[index] = replacement;
+    }
+    if (e->jpeg && decode_jpeg(e, index, bytes_used)) {
+        // Preserve the detailed decoder failure while ending BOTH engines.
+        e->close(); return -1;
+    }
+    if (force_idr) {
+        int ret = e->api->control(e->ctx, MPP_ENC_SET_IDR_FRAME, nullptr);
+        if (ret) return abort_encode("MPP_ENC_SET_IDR_FRAME", ret);
+    }
+    MppFrame frame = e->jpeg ? e->decoded_frame : nullptr;
+    int ret = 0;
+    if (!e->jpeg) {
+        ret = mpp_frame_init(&frame);
+        if (ret) return abort_encode("mpp_frame_init", ret);
+        mpp_frame_set_width(frame, e->width); mpp_frame_set_height(frame, e->height);
+        mpp_frame_set_hor_stride(frame, e->stride); mpp_frame_set_ver_stride(frame, e->height);
+        mpp_frame_set_fmt(frame, e->format);
+        mpp_frame_set_buffer(frame, e->buffers[index]);
+    }
+    mpp_frame_set_pts(frame, pts_us);
+    ret = e->api->encode_put_frame(e->ctx, frame);
+    if (!e->jpeg) mpp_frame_deinit(&frame);
+    if (ret) return abort_encode("encode_put_frame", ret);
+    ret = e->api->encode_get_packet(e->ctx, &e->packet);
+    if (ret || !e->packet) return abort_encode("encode_get_packet", ret);
+    if (mpp_packet_is_partition(e->packet) || !mpp_packet_get_length(e->packet))
+        return abort_encode("incomplete DMA encoder output", -1);
+    // One synchronous input, no temporal scalability/reordering/split output.
+    // A completed packet is the input-consumption barrier for this mode.
+    *data = static_cast<const uint8_t *>(mpp_packet_get_pos(e->packet));
+    *size = mpp_packet_get_length(e->packet);
+    return 0;
+}
+extern "C" void rkmpp_dma_free(RkmppDmaEncoder *e) { delete e; }
+#else
+extern "C" RkmppDmaEncoder *rkmpp_dma_new(int,int,int,int,int,int,int,int,const int*,const size_t*,size_t) {
+    fail("RKMPP DMA support not built", -1); return nullptr;
+}
+extern "C" int rkmpp_dma_encode(RkmppDmaEncoder*,size_t,size_t,int,int64_t,int,const uint8_t**,size_t*) { return -1; }
+extern "C" int rkmpp_dma_reconfigure(RkmppDmaEncoder*,int,int) { return -1; }
+extern "C" void rkmpp_dma_free(RkmppDmaEncoder*) {}
+#endif
+extern "C" const char *rkmpp_dma_error(void) { return dma_error; }

libs/hwcodec/cpp/ffmpeg_hw/rkmpp_dmabuf_ffi.h

@@ -0,0 +1,31 @@
+#pragma once
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct RkmppDmaEncoder RkmppDmaEncoder;
+// format: 0=NV12, 1=BGR24, 2=YUYV, 3=RGB24 (byte stride), 4=MJPEG (stride ignored).
+// codec: 0=H264, 1=HEVC. MJPEG is decoded to hardware NV12, then encoded.
+RkmppDmaEncoder *rkmpp_dma_new(int width, int height, int stride, int format,
+                              int codec, int fps, int kbps, int gop,
+                              const int *fds, const size_t *sizes, size_t count);
+// Synchronous input-completion boundary. On failure the encoder is destroyed
+// internally BEFORE returning, so it cannot keep reading the capture buffer.
+// Output is borrowed until the next call or destruction; copy before reusing it.
+// bytes_used must be the actual captured payload. MJPEG needs 64 bytes of
+// readable allocation headroom; never pass sizeimage as the compressed length.
+// fresh_fd=-1 reuses the original import (native HDMI). UVC supplies a new
+// export of this dequeued slot. Keep it open until replacement/free; the old
+// export can be closed AFTER this call, including on failure.
+int rkmpp_dma_encode(RkmppDmaEncoder *encoder, size_t index, size_t bytes_used, int fresh_fd, int64_t pts_us,
+                     int force_idr, const uint8_t **data, size_t *size);
+int rkmpp_dma_reconfigure(RkmppDmaEncoder *encoder, int kbps, int gop);
+void rkmpp_dma_free(RkmppDmaEncoder *encoder);
+const char *rkmpp_dma_error(void);
+
+#ifdef __cplusplus
+}
+#endif

libs/hwcodec/cpp/ffmpeg_ram/ffmpeg_ram_encode.cpp

@@ -26,7 +26,6 @@ static thread_local std::string g_encoder_last_error;
 
 static void set_encoder_last_error(const std::string &message) {
   g_encoder_last_error = message;
-  LOG_ERROR(message);
 }
 
 static int calculate_offset_length(int pix_fmt, int height, const int *linesize,
@@ -380,12 +379,12 @@ private:
     frame->pts = ms;
 
     // Force keyframe if requested
-    if (force_keyframe_) {
+    if (force_keyframe_ && util_encode::supports_forced_keyframe(name_)) {
       frame->pict_type = AV_PICTURE_TYPE_I;
-      force_keyframe_ = false;
     } else {
       frame->pict_type = AV_PICTURE_TYPE_NONE;
     }
+    force_keyframe_ = false;
 
     ret = avcodec_send_frame(c_, frame);
     if (ret == AVERROR(EAGAIN)) {
@@ -646,8 +645,8 @@ ffmpeg_ram_new_encoder(const char *name, int width,
     // allowing CQP-only drivers to pass probing and normal encoder creation.
     if (name && std::string(name).find("vaapi") != std::string::npos &&
         rc != RC_CQ) {
-      LOG_WARN(std::string("VAAPI bitrate-based rate control failed for ") +
-               name + ", retrying with CQP");
+      LOG_DEBUG(std::string("VAAPI bitrate-based rate control failed for ") +
+                name + ", retrying with CQP");
       encoder = try_create(RC_CQ, 0);
       if (encoder) {
         return encoder;

libs/hwcodec/src/ffmpeg.rs

@@ -32,14 +32,14 @@ pub extern "C" fn hwcodec_av_log_callback(level: i32, message: *const std::os::r
         if let Ok(str_slice) = c_str.to_str() {
             let string = String::from(str_slice);
             if level == AV_LOG_ERROR as i32 {
-                log::error!("{}", string);
                 if string.contains(could_not_find_ref_with_poc) {
                     hwcodec_set_flag_could_not_find_ref_with_poc();
                 }
+                log::debug!("{}", string);
             } else if level == AV_LOG_PANIC as i32 || level == AV_LOG_FATAL as i32 {
                 log::error!("{}", string);
             } else if level == AV_LOG_WARNING as i32 {
-                log::warn!("{}", string);
+                log::debug!("{}", string);
             } else if level == AV_LOG_INFO as i32 {
                 log::info!("{}", string);
             } else if level == AV_LOG_VERBOSE as i32 || level == AV_LOG_DEBUG as i32 {

libs/hwcodec/src/ffmpeg_ram/encode.rs

@@ -343,7 +343,7 @@ fn log_failed_probe_attempt(
 }
 
 fn validate_candidate(codec: &CodecInfo, ctx: &EncodeContext, yuv: &[u8]) -> bool {
-    use log::{debug, warn};
+    use log::debug;
 
     debug!("Testing encoder: {}", codec.name);
 
@@ -395,7 +395,7 @@ fn validate_candidate(codec: &CodecInfo, ctx: &EncodeContext, yuv: &[u8]) -> boo
                     }
                     Err(err) => {
                         last_err = Some(err);
-                        warn!(
+                        debug!(
                             "Encoder {} test attempt {} returned error: {}",
                             codec.name, attempt_no, err
                         );
@@ -412,10 +412,7 @@ fn validate_candidate(codec: &CodecInfo, ctx: &EncodeContext, yuv: &[u8]) -> boo
             );
             false
         }
-        Err(_) => {
-            warn!("Failed to create encoder {}", codec.name);
-            false
-        }
+        Err(_) => false,
     }
 }
 
@@ -543,7 +540,7 @@ impl Encoder {
             if codec.is_null() {
                 let message = encoder_last_error_message();
                 if !message.is_empty() {
-                    log::error!("ffmpeg_ram_new_encoder failed: {}", message);
+                    log::debug!("ffmpeg_ram_new_encoder failed: {}", message);
                 }
                 return Err(());
             }
@@ -595,6 +592,16 @@ impl Encoder {
                 Some(Encoder::packet_callback),
             );
             if result == -11 || result == 0 {
+                if self.ctx.name.contains("v4l2m2m") {
+                    return Ok(frames
+                        .into_iter()
+                        .map(|frame| EncodeBytesFrame {
+                            data: Bytes::copy_from_slice(frame.data.as_ref()),
+                            pts: frame.pts,
+                            key: frame.key,
+                        })
+                        .collect());
+                }
                 return Ok(frames);
             }
             Err(result)

libs/hwcodec/src/lib.rs

@@ -5,6 +5,11 @@ pub mod ffmpeg;
 #[cfg(any(target_arch = "aarch64", target_arch = "arm", feature = "rkmpp"))]
 pub mod ffmpeg_hw;
 pub mod ffmpeg_ram;
+#[cfg(all(
+    target_os = "linux",
+    any(target_arch = "aarch64", target_arch = "arm", feature = "rkmpp")
+))]
+pub mod rkmpp_dmabuf;
 
 #[no_mangle]
 pub extern "C" fn hwcodec_log(level: i32, message: *const std::os::raw::c_char) {

libs/hwcodec/src/rkmpp_dmabuf.rs

@@ -0,0 +1,193 @@
+//! Synchronous RKMPP encoder for pre-exported V4L2 DMA buffers.
+//! Unlike the byte-slice encoder this never reads raw pixels on the CPU.
+
+use std::ffi::{c_char, c_int, c_void, CStr};
+use std::os::fd::{AsRawFd, OwnedFd};
+use std::ptr::NonNull;
+
+unsafe extern "C" {
+    fn rkmpp_dma_new(
+        width: c_int,
+        height: c_int,
+        stride: c_int,
+        format: c_int,
+        codec: c_int,
+        fps: c_int,
+        kbps: c_int,
+        gop: c_int,
+        fds: *const c_int,
+        sizes: *const usize,
+        count: usize,
+    ) -> *mut c_void;
+    fn rkmpp_dma_encode(
+        encoder: *mut c_void,
+        index: usize,
+        bytes_used: usize,
+        fresh_fd: c_int,
+        pts_us: i64,
+        force_idr: c_int,
+        data: *mut *const u8,
+        size: *mut usize,
+    ) -> c_int;
+    fn rkmpp_dma_reconfigure(encoder: *mut c_void, kbps: c_int, gop: c_int) -> c_int;
+    fn rkmpp_dma_free(encoder: *mut c_void);
+    fn rkmpp_dma_error() -> *const c_char;
+}
+
+#[derive(Debug, Clone, Copy)]
+#[repr(i32)]
+pub enum DmaFormat {
+    Nv12 = 0,
+    Bgr24 = 1,
+    Yuyv = 2,
+    Rgb24 = 3,
+    Mjpeg = 4,
+}
+
+pub struct DmaEncoderConfig {
+    pub width: u32,
+    pub height: u32,
+    pub stride: u32,
+    pub format: DmaFormat,
+    pub hevc: bool,
+    pub fps: u32,
+    pub bitrate_kbps: u32,
+    pub gop: u32,
+}
+
+pub struct DmaEncoder {
+    ctx: NonNull<c_void>,
+    // Export FDs remain open until AFTER mpp_destroy and imported buffer release.
+    _buffers: Vec<(OwnedFd, usize)>,
+    // Keep refreshed exports alive until native replacement/release has ended
+    // all references to the previous import. At most one FD per capture slot.
+    fresh_buffers: Vec<Option<OwnedFd>>,
+}
+
+// Exclusive ownership: the context can move between threads but all calls are sequential.
+unsafe impl Send for DmaEncoder {}
+
+fn last_error() -> String {
+    unsafe {
+        CStr::from_ptr(rkmpp_dma_error())
+            .to_string_lossy()
+            .into_owned()
+    }
+}
+
+impl DmaEncoder {
+    pub fn new(config: DmaEncoderConfig, buffers: Vec<(OwnedFd, usize)>) -> Result<Self, String> {
+        let fds: Vec<_> = buffers.iter().map(|(fd, _)| fd.as_raw_fd()).collect();
+        let sizes: Vec<_> = buffers.iter().map(|(_, size)| *size).collect();
+        for value in [
+            config.width,
+            config.height,
+            config.stride,
+            config.fps,
+            config.bitrate_kbps,
+            config.gop,
+        ] {
+            if value > c_int::MAX as u32 {
+                return Err("DMA encoder parameter overflow".into());
+            }
+        }
+        let ptr = unsafe {
+            rkmpp_dma_new(
+                config.width as _,
+                config.height as _,
+                config.stride as _,
+                config.format as c_int,
+                config.hevc as _,
+                config.fps as _,
+                config.bitrate_kbps as _,
+                config.gop as _,
+                fds.as_ptr(),
+                sizes.as_ptr(),
+                buffers.len(),
+            )
+        };
+        Ok(Self {
+            ctx: NonNull::new(ptr).ok_or_else(last_error)?,
+            fresh_buffers: (0..buffers.len()).map(|_| None).collect(),
+            _buffers: buffers,
+        })
+    }
+
+    /// # Safety
+    /// The indexed buffer must be dequeued and exclusively leased to this call.
+    /// Do not requeue/write it until this function returns. On failure native MPP
+    /// is synchronously destroyed before returning, ending all input access.
+    /// `bytes_used` is the actual DQBUF payload length, not the buffer capacity.
+    /// A refreshed FD, if supplied, must refer to the same leased capture slot
+    /// with the capacity registered at construction. Ownership is retained here.
+    pub unsafe fn encode(
+        &mut self,
+        index: usize,
+        bytes_used: usize,
+        fresh_fd: Option<OwnedFd>,
+        pts_ms: i64,
+        force_idr: bool,
+    ) -> Result<Vec<u8>, String> {
+        let mut data = std::ptr::null();
+        let mut size = 0;
+        if index >= self.fresh_buffers.len() {
+            return Err("Invalid DMA capture index".into());
+        }
+        let ret = unsafe {
+            rkmpp_dma_encode(
+                self.ctx.as_ptr(),
+                index,
+                bytes_used,
+                fresh_fd.as_ref().map_or(-1, AsRawFd::as_raw_fd),
+                pts_ms.saturating_mul(1000),
+                force_idr as _,
+                &mut data,
+                &mut size,
+            )
+        };
+        if fresh_fd.is_some() {
+            // Native has now released the previous import, or destroyed both
+            // hardware contexts on error. Only now may its old FD be closed.
+            self.fresh_buffers[index] = fresh_fd;
+        }
+        if ret != 0 {
+            return Err(last_error());
+        }
+        if data.is_null() || size == 0 {
+            return Err("Empty RKMPP DMA packet".into());
+        }
+        // Copy only the compressed output, releasing the driver's packet promptly
+        // regardless of how long a network subscriber retains its Bytes.
+        Ok(unsafe { std::slice::from_raw_parts(data, size) }.to_vec())
+    }
+
+    pub fn reconfigure(&mut self, kbps: u32, gop: u32) -> Result<(), String> {
+        if kbps > c_int::MAX as u32 || gop > c_int::MAX as u32 {
+            return Err("DMA encoder parameter overflow".into());
+        }
+        if unsafe { rkmpp_dma_reconfigure(self.ctx.as_ptr(), kbps as _, gop as _) } != 0 {
+            return Err(last_error());
+        }
+        Ok(())
+    }
+}
+
+impl Drop for DmaEncoder {
+    fn drop(&mut self) {
+        unsafe { rkmpp_dma_free(self.ctx.as_ptr()) };
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn format_discriminants_match_native_abi() {
+        assert_eq!(DmaFormat::Nv12 as c_int, 0);
+        assert_eq!(DmaFormat::Bgr24 as c_int, 1);
+        assert_eq!(DmaFormat::Yuyv as c_int, 2);
+        assert_eq!(DmaFormat::Rgb24 as c_int, 3);
+        assert_eq!(DmaFormat::Mjpeg as c_int, 4);
+    }
+}

libs/ventoy-img-rs/Cargo.toml

@@ -3,7 +3,7 @@ name = "ventoy-img"
 version = "0.1.0"
 edition = "2021"
 description = "Create and manage Ventoy bootable IMG files without root or loop devices"
-license = "GPL-2.0"
+license = "AGPL-3.0-only"
 
 [dependencies]
 # CLI

libs/ventoy-img-rs/README.md

@@ -142,7 +142,11 @@ fn main() -> Result<()> {
 
 ## 许可证
 
-GPL-2.0
+AGPL-3.0-only
+
+本 crate 随 One-KVM 整体按 AGPL-3.0-only 发布。其 `resources/` 目录内的
+Ventoy 启动文件衍生自 [Ventoy](https://www.ventoy.net/)（GPL-3.0-or-later），
+引导部分包含 [GRUB](https://www.gnu.org/software/grub/)（GPL-3.0-or-later）。
 
 ## 致谢
 

licenses/AGPL-3.0.txt

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

licenses/GPL-3.0.txt

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

protos/NOTICE

@@ -0,0 +1,24 @@
+Third-Party Code Attribution
+=============================
+
+The files in this directory (message.proto and rendezvous.proto) are derived
+from the protocol definition files of the RustDesk project
+(https://github.com/rustdesk/rustdesk), including the use of the original
+`package hbb;` namespace.
+
+Upstream work:
+  RustDesk - https://github.com/rustdesk/rustdesk
+  Copyright (C) the RustDesk contributors
+  Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only)
+
+Modifications:
+  The files have been adapted and modified for use in One-KVM. They are
+  redistributed under the same license (AGPL-3.0-only), in accordance with
+  sections 4 and 5 of that license.
+
+The complete text of the GNU Affero General Public License v3.0 is available
+in the LICENSE file at the root of this repository and at:
+https://www.gnu.org/licenses/agpl-3.0.en.html
+
+The corresponding source code of One-KVM, including these files, is available
+at https://github.com/mofeng-git/One-KVM (see the release tags).

res/vcpkg/libyuv/build.rs

@@ -5,7 +5,8 @@ use std::{
 };
 
 fn main() {
-    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    // Read the current source path when running, since build artifacts may move.
+    let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
     let cpp_dir = manifest_dir.join("cpp");
 
     println!("cargo:rerun-if-changed=cpp/yuv_ffi.h");

res/vcpkg/libyuv/src/lib.rs

@@ -1119,25 +1119,73 @@ pub fn mjpg_size(src: &[u8]) -> Result<(i32, i32)> {
 
 /// Decode MJPEG directly to NV12.
 pub fn mjpg_to_nv12(src: &[u8], dst: &mut [u8], width: i32, height: i32) -> Result<()> {
-    if width % 2 != 0 || height % 2 != 0 {
-        return Err(YuvError::InvalidDimensions);
-    }
-
-    let w = width as usize;
-    let h = height as usize;
-    if dst.len() < nv12_size(w, h) {
+    let (y_size, output_size) = mjpg_nv12_plane_sizes(width, height)?;
+    if dst.len() < output_size {
         return Err(YuvError::BufferTooSmall);
     }
 
-    let y_size = w * h;
     let (dst_y, dst_uv) = dst.split_at_mut(y_size);
+    // SAFETY: the length check above guarantees writable storage for both planes.
+    unsafe { mjpg_to_nv12_raw(src, dst_y.as_mut_ptr(), dst_uv.as_mut_ptr(), width, height) }
+}
 
+/// Decode MJPEG directly into a reusable `Vec` without zero-filling the output first.
+///
+/// `Vec::resize` must initialize every byte before libyuv immediately overwrites the
+/// complete NV12 frame. This variant lets libyuv initialize spare capacity directly
+/// and publishes the new length only after a successful conversion.
+pub fn mjpg_to_nv12_vec(src: &[u8], dst: &mut Vec<u8>, width: i32, height: i32) -> Result<()> {
+    let (y_size, output_size) = mjpg_nv12_plane_sizes(width, height)?;
+
+    dst.clear();
+    dst.reserve(output_size);
+
+    // SAFETY: reserve above guarantees writable capacity for the Y and UV planes.
+    // MJPGToNV12 writes the complete output on success; set_len is deliberately
+    // delayed until then so callers can never observe partially initialized bytes.
+    let result = unsafe {
+        let dst_y = dst.as_mut_ptr();
+        mjpg_to_nv12_raw(src, dst_y, dst_y.add(y_size), width, height)
+    };
+    result?;
+
+    // SAFETY: a successful MJPGToNV12 call initialized exactly output_size bytes.
+    unsafe { dst.set_len(output_size) };
+    Ok(())
+}
+
+#[inline]
+fn mjpg_nv12_plane_sizes(width: i32, height: i32) -> Result<(usize, usize)> {
+    if width % 2 != 0 || height % 2 != 0 || width <= 0 || height <= 0 {
+        return Err(YuvError::InvalidDimensions);
+    }
+    let y_size = (width as usize)
+        .checked_mul(height as usize)
+        .ok_or(YuvError::InvalidDimensions)?;
+    let output_size = y_size
+        .checked_mul(3)
+        .map(|size| size / 2)
+        .ok_or(YuvError::InvalidDimensions)?;
+    Ok((y_size, output_size))
+}
+
+/// # Safety
+///
+/// `dst_y` and `dst_uv` must point to writable planes sized for `width` x `height` NV12.
+#[inline]
+unsafe fn mjpg_to_nv12_raw(
+    src: &[u8],
+    dst_y: *mut u8,
+    dst_uv: *mut u8,
+    width: i32,
+    height: i32,
+) -> Result<()> {
     call_yuv!(MJPGToNV12(
         src.as_ptr(),
         usize_to_size_t(src.len()),
-        dst_y.as_mut_ptr(),
+        dst_y,
         width,
-        dst_uv.as_mut_ptr(),
+        dst_uv,
         width,
         width,
         height,

src/atx/mod.rs

@@ -27,7 +27,7 @@ pub use types::{
     ActiveLevel, AtxAction, AtxDevices, AtxDriverType, AtxInputBinding, AtxKeyConfig,
     AtxOutputBinding, AtxPowerRequest, AtxState, HddStatus, PowerStatus, LCUS_RELAY_MAX_CHANNEL,
 };
-pub use wol::{list_wol_history, record_wol_history, send_wol};
+pub use wol::send_wol;
 
 #[cfg(any(unix, test))]
 fn hidraw_uevent_is_usb_relay(uevent: &str) -> bool {

src/atx/wol.rs

@@ -7,8 +7,6 @@ use tracing::info;
 
 use crate::error::{AppError, Result};
 
-const WOL_HISTORY_MAX_ENTRIES: i64 = 50;
-
 const MAGIC_PACKET_SIZE: usize = 102;
 
 fn parse_mac_address(mac: &str) -> Result<[u8; 6]> {
@@ -118,55 +116,6 @@ pub fn send_wol(mac_address: &str, interface: Option<&str>) -> Result<()> {
     Ok(())
 }
 
-pub async fn record_wol_history(pool: &sqlx::Pool<sqlx::Sqlite>, mac_address: &str) -> Result<()> {
-    sqlx::query(
-        r#"
-        INSERT INTO wol_history (mac_address, updated_at)
-        VALUES (?1, CAST(strftime('%s', 'now') AS INTEGER))
-        ON CONFLICT(mac_address) DO UPDATE SET
-            updated_at = excluded.updated_at
-        "#,
-    )
-    .bind(mac_address)
-    .execute(pool)
-    .await?;
-
-    sqlx::query(
-        r#"
-        DELETE FROM wol_history
-        WHERE mac_address NOT IN (
-            SELECT mac_address FROM wol_history
-            ORDER BY updated_at DESC
-            LIMIT ?1
-        )
-        "#,
-    )
-    .bind(WOL_HISTORY_MAX_ENTRIES)
-    .execute(pool)
-    .await?;
-
-    Ok(())
-}
-
-pub async fn list_wol_history(
-    pool: &sqlx::Pool<sqlx::Sqlite>,
-    limit: usize,
-) -> Result<Vec<(String, i64)>> {
-    let rows = sqlx::query_as(
-        r#"
-        SELECT mac_address, updated_at
-        FROM wol_history
-        ORDER BY updated_at DESC
-        LIMIT ?1
-        "#,
-    )
-    .bind(limit as i64)
-    .fetch_all(pool)
-    .await?;
-
-    Ok(rows)
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

src/audio/capture.rs

@@ -1,3 +1,15 @@
+//! Platform-neutral capture lifecycle and PCM frame types.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use bytes::Bytes;
+use tokio::sync::{broadcast, watch, Mutex};
+use tracing::{debug, info};
+
+use crate::error::Result;
+use crate::utils::LogThrottler;
+
 #[cfg(unix)]
 #[path = "capture_linux.rs"]
 mod imp;
@@ -6,4 +18,146 @@ mod imp;
 #[path = "capture_windows.rs"]
 mod imp;
 
-pub use imp::*;
+#[derive(Debug, Clone)]
+pub struct AudioConfig {
+    pub device_name: String,
+    pub sample_rate: u32,
+    pub channels: u32,
+    pub buffer_frames: u32,
+    pub period_frames: u32,
+}
+
+impl Default for AudioConfig {
+    fn default() -> Self {
+        Self {
+            device_name: String::new(),
+            sample_rate: 48_000,
+            channels: 2,
+            buffer_frames: 4096,
+            period_frames: 960,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct AudioFrame {
+    pub data: Bytes,
+    pub sample_rate: u32,
+    pub channels: u32,
+}
+
+impl AudioFrame {
+    pub fn new_interleaved(data: Bytes, channels: u32, sample_rate: u32) -> Self {
+        Self {
+            data,
+            sample_rate,
+            channels,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CaptureState {
+    Stopped,
+    Starting,
+    Running,
+    Error,
+}
+
+pub struct AudioCapturer {
+    config: AudioConfig,
+    state: watch::Sender<CaptureState>,
+    state_rx: watch::Receiver<CaptureState>,
+    frame_tx: broadcast::Sender<AudioFrame>,
+    stop_flag: Arc<AtomicBool>,
+    task: Mutex<Option<tokio::task::JoinHandle<()>>>,
+    lifecycle: Mutex<()>,
+    log_throttler: LogThrottler,
+}
+
+impl AudioCapturer {
+    pub fn new(config: AudioConfig) -> Self {
+        let (state, state_rx) = watch::channel(CaptureState::Stopped);
+        let (frame_tx, _) = broadcast::channel(16);
+
+        Self {
+            config,
+            state,
+            state_rx,
+            frame_tx,
+            stop_flag: Arc::new(AtomicBool::new(false)),
+            task: Mutex::new(None),
+            lifecycle: Mutex::new(()),
+            log_throttler: LogThrottler::with_secs(5),
+        }
+    }
+
+    pub fn state(&self) -> CaptureState {
+        *self.state_rx.borrow()
+    }
+
+    pub fn state_watch(&self) -> watch::Receiver<CaptureState> {
+        self.state_rx.clone()
+    }
+
+    pub fn subscribe(&self) -> broadcast::Receiver<AudioFrame> {
+        self.frame_tx.subscribe()
+    }
+
+    pub async fn start(&self) -> Result<()> {
+        let _lifecycle = self.lifecycle.lock().await;
+        if matches!(self.state(), CaptureState::Starting | CaptureState::Running) {
+            return Ok(());
+        }
+
+        if let Some(previous) = self.task.lock().await.take() {
+            let _ = previous.await;
+        }
+
+        debug!(
+            "Starting audio capture on {} at {}Hz {}ch",
+            self.config.device_name, self.config.sample_rate, self.config.channels
+        );
+
+        self.stop_flag.store(false, Ordering::Release);
+        let _ = self.state.send(CaptureState::Starting);
+
+        let config = self.config.clone();
+        let state = self.state.clone();
+        let frame_tx = self.frame_tx.clone();
+        let stop_flag = Arc::clone(&self.stop_flag);
+        let log_throttler = self.log_throttler.clone();
+
+        let task = tokio::task::spawn_blocking(move || {
+            match imp::run_capture(&config, &state, &frame_tx, &stop_flag, &log_throttler) {
+                Ok(()) => {
+                    let _ = state.send(CaptureState::Stopped);
+                }
+                Err(error) => {
+                    crate::error_throttled!(
+                        log_throttler,
+                        "capture_error",
+                        "Audio capture error: {}",
+                        error
+                    );
+                    let _ = state.send(CaptureState::Error);
+                }
+            }
+        });
+        *self.task.lock().await = Some(task);
+        Ok(())
+    }
+
+    pub async fn stop(&self) -> Result<()> {
+        let _lifecycle = self.lifecycle.lock().await;
+        self.stop_flag.store(true, Ordering::Release);
+
+        if let Some(task) = self.task.lock().await.take() {
+            let _ = task.await;
+        }
+
+        let _ = self.state.send(CaptureState::Stopped);
+        info!("Audio capture stopped");
+        Ok(())
+    }
+}

src/audio/capture_linux.rs

@@ -1,271 +1,60 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::thread;
+use std::time::Duration;
+
 use alsa::pcm::{Access, Format, Frames, HwParams, State, IO};
 use alsa::{Direction, ValueOr, PCM};
 use bytes::Bytes;
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::sync::Arc;
-use std::time::Instant;
-use tokio::sync::{broadcast, watch, Mutex};
-use tracing::{debug, info};
+use tokio::sync::{broadcast, watch};
+use tracing::debug;
 
-use crate::audio::device::AudioDeviceInfo;
+use super::{AudioConfig, AudioFrame, CaptureState};
 use crate::error::{AppError, Result};
 use crate::utils::LogThrottler;
-use crate::{error_throttled, warn_throttled};
+use crate::warn_throttled;
 
-#[derive(Debug, Clone)]
-pub struct AudioConfig {
-    pub device_name: String,
-    pub sample_rate: u32,
-    pub channels: u32,
-    pub frame_size: u32,
-    pub buffer_frames: u32,
-    pub period_frames: u32,
-}
+const RETRY_DELAY: Duration = Duration::from_millis(5);
+const MAX_CONSECUTIVE_READ_ERRORS: u32 = 10;
 
-impl Default for AudioConfig {
-    fn default() -> Self {
-        Self {
-            device_name: String::new(),
-            sample_rate: 48000,
-            channels: 2,
-            frame_size: 960,
-            buffer_frames: 4096,
-            period_frames: 960,
-        }
-    }
-}
-
-impl AudioConfig {
-    pub fn for_device(device: &AudioDeviceInfo) -> Self {
-        Self {
-            device_name: device.name.clone(),
-            ..Default::default()
-        }
-    }
-
-    pub fn bytes_per_sample(&self) -> u32 {
-        2 * self.channels
-    }
-
-    pub fn bytes_per_frame(&self) -> usize {
-        (self.frame_size * self.bytes_per_sample()) as usize
-    }
-}
-
-#[derive(Debug, Clone)]
-pub struct AudioFrame {
-    pub data: Bytes,
-    pub sample_rate: u32,
-    pub channels: u32,
-    pub samples: u32,
-    pub sequence: u64,
-    pub timestamp: Instant,
-}
-
-impl AudioFrame {
-    pub fn new_interleaved(data: Bytes, channels: u32, sample_rate: u32, sequence: u64) -> Self {
-        let bps = 2 * channels;
-        Self {
-            samples: data.len() as u32 / bps,
-            data,
-            sample_rate,
-            channels,
-            sequence,
-            timestamp: Instant::now(),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum CaptureState {
-    Stopped,
-    Running,
-    Error,
-}
-
-pub struct AudioCapturer {
-    config: AudioConfig,
-    state: Arc<watch::Sender<CaptureState>>,
-    state_rx: watch::Receiver<CaptureState>,
-    frame_tx: broadcast::Sender<AudioFrame>,
-    stop_flag: Arc<AtomicBool>,
-    sequence: Arc<AtomicU64>,
-    capture_handle: Mutex<Option<tokio::task::JoinHandle<()>>>,
-    log_throttler: LogThrottler,
-}
-
-impl AudioCapturer {
-    pub fn new(config: AudioConfig) -> Self {
-        let (state_tx, state_rx) = watch::channel(CaptureState::Stopped);
-        let (frame_tx, _) = broadcast::channel(16);
-
-        Self {
-            config,
-            state: Arc::new(state_tx),
-            state_rx,
-            frame_tx,
-            stop_flag: Arc::new(AtomicBool::new(false)),
-            sequence: Arc::new(AtomicU64::new(0)),
-            capture_handle: Mutex::new(None),
-            log_throttler: LogThrottler::with_secs(5),
-        }
-    }
-
-    pub fn state(&self) -> CaptureState {
-        *self.state_rx.borrow()
-    }
-
-    pub fn state_watch(&self) -> watch::Receiver<CaptureState> {
-        self.state_rx.clone()
-    }
-
-    pub fn subscribe(&self) -> broadcast::Receiver<AudioFrame> {
-        self.frame_tx.subscribe()
-    }
-
-    pub async fn start(&self) -> Result<()> {
-        if self.state() == CaptureState::Running {
-            return Ok(());
-        }
-
-        debug!(
-            "Starting audio capture on {} at {}Hz {}ch",
-            self.config.device_name, self.config.sample_rate, self.config.channels
-        );
-
-        self.stop_flag.store(false, Ordering::SeqCst);
-
-        let config = self.config.clone();
-        let state = self.state.clone();
-        let frame_tx = self.frame_tx.clone();
-        let stop_flag = self.stop_flag.clone();
-        let sequence = self.sequence.clone();
-        let log_throttler = self.log_throttler.clone();
-
-        let handle = tokio::task::spawn_blocking(move || {
-            let result = run_capture(
-                &config,
-                &state,
-                &frame_tx,
-                &stop_flag,
-                &sequence,
-                &log_throttler,
-            );
-
-            if let Err(e) = result {
-                error_throttled!(log_throttler, "capture_error", "Audio capture error: {}", e);
-                let _ = state.send(CaptureState::Error);
-            } else {
-                let _ = state.send(CaptureState::Stopped);
-            }
-        });
-
-        *self.capture_handle.lock().await = Some(handle);
-        Ok(())
-    }
-
-    pub async fn stop(&self) -> Result<()> {
-        info!("Stopping audio capture");
-        self.stop_flag.store(true, Ordering::SeqCst);
-
-        if let Some(handle) = self.capture_handle.lock().await.take() {
-            let _ = handle.await;
-        }
-
-        let _ = self.state.send(CaptureState::Stopped);
-        Ok(())
-    }
-
-    pub fn is_running(&self) -> bool {
-        self.state() == CaptureState::Running
-    }
-}
-
-fn run_capture(
+pub(super) fn run_capture(
     config: &AudioConfig,
     state: &watch::Sender<CaptureState>,
     frame_tx: &broadcast::Sender<AudioFrame>,
     stop_flag: &AtomicBool,
-    sequence: &AtomicU64,
     log_throttler: &LogThrottler,
 ) -> Result<()> {
-    let pcm = PCM::new(&config.device_name, Direction::Capture, false).map_err(|e| {
+    // Non-blocking mode guarantees that stop() can always join the worker.
+    let pcm = PCM::new(&config.device_name, Direction::Capture, true).map_err(|error| {
         AppError::AudioError(format!(
             "Failed to open audio device {}: {}",
-            config.device_name, e
+            config.device_name, error
         ))
     })?;
 
-    {
-        let hwp = HwParams::any(&pcm)
-            .map_err(|e| AppError::AudioError(format!("Failed to get HwParams: {}", e)))?;
-
-        hwp.set_channels(config.channels)
-            .map_err(|e| AppError::AudioError(format!("Failed to set channels: {}", e)))?;
-
-        hwp.set_rate(config.sample_rate, ValueOr::Nearest)
-            .map_err(|e| AppError::AudioError(format!("Failed to set sample rate: {}", e)))?;
-
-        hwp.set_format(Format::s16())
-            .map_err(|e| AppError::AudioError(format!("Failed to set format: {}", e)))?;
-
-        hwp.set_access(Access::RWInterleaved)
-            .map_err(|e| AppError::AudioError(format!("Failed to set access: {}", e)))?;
-
-        hwp.set_buffer_size_near(config.buffer_frames as Frames)
-            .map_err(|e| AppError::AudioError(format!("Failed to set buffer size: {}", e)))?;
-
-        hwp.set_period_size_near(config.period_frames as Frames, ValueOr::Nearest)
-            .map_err(|e| AppError::AudioError(format!("Failed to set period size: {}", e)))?;
-
-        pcm.hw_params(&hwp)
-            .map_err(|e| AppError::AudioError(format!("Failed to apply hw params: {}", e)))?;
-    }
-
-    let hw_now = pcm.hw_params_current().map_err(|e| {
-        AppError::AudioError(format!("Failed to read hw_params after apply: {}", e))
-    })?;
-    let actual_rate = hw_now
-        .get_rate()
-        .map_err(|e| AppError::AudioError(format!("Failed to read sample rate: {}", e)))?;
-    let actual_ch = hw_now
-        .get_channels()
-        .map_err(|e| AppError::AudioError(format!("Failed to read channels: {}", e)))?;
-    if actual_rate != 48_000 {
-        return Err(AppError::AudioError(format!(
-            "Audio capture requires 48000 Hz; device is {} Hz",
-            actual_rate
-        )));
-    }
-    if actual_ch != 2 {
-        return Err(AppError::AudioError(format!(
-            "Audio capture requires 2 channels (stereo); device has {}",
-            actual_ch
-        )));
-    }
-    debug!("Audio capture: 48000 Hz, 2 ch");
-
+    configure_pcm(&pcm, config)?;
     pcm.prepare()
-        .map_err(|e| AppError::AudioError(format!("Failed to prepare PCM: {}", e)))?;
-
+        .map_err(|error| AppError::AudioError(format!("Failed to prepare PCM: {error}")))?;
     let _ = state.send(CaptureState::Running);
 
     let period_frames = pcm
         .hw_params_current()
         .ok()
-        .and_then(|h| h.get_period_size().ok())
-        .map(|f| f as usize)
-        .unwrap_or(1024)
+        .and_then(|params| params.get_period_size().ok())
+        .map(|frames| frames as usize)
+        .unwrap_or(config.period_frames as usize)
         .max(256);
-    let buf_frames = period_frames.saturating_mul(4).max(2048);
-    let bytes_per_frame = (config.channels as usize) * 2;
-    let mut buffer = vec![0u8; buf_frames * bytes_per_frame];
+    let mut buffer = vec![0u8; period_frames * config.channels as usize * 2];
+    let io: IO<u8> = pcm.io_bytes();
+    let mut consecutive_errors = 0;
 
-    while !stop_flag.load(Ordering::Relaxed) {
+    while !stop_flag.load(Ordering::Acquire) {
         match pcm.state() {
             State::XRun => {
                 warn_throttled!(log_throttler, "xrun", "Audio buffer overrun, recovering");
-                let _ = pcm.prepare();
+                pcm.prepare().map_err(|error| {
+                    AppError::AudioError(format!("Failed to recover audio xrun: {error}"))
+                })?;
+                consecutive_errors = 0;
                 continue;
             }
             State::Suspended => {
@@ -274,61 +63,95 @@ fn run_capture(
                     "suspended",
                     "Audio device suspended, recovering"
                 );
-                let _ = pcm.resume();
+                if pcm.resume().is_err() {
+                    pcm.prepare().map_err(|error| {
+                        AppError::AudioError(format!("Failed to resume audio capture: {error}"))
+                    })?;
+                }
+                consecutive_errors = 0;
                 continue;
             }
             _ => {}
         }
 
-        // io_bytes: USB capture often lacks mmap (io_checked requires it).
-        let io: IO<u8> = pcm.io_bytes();
-
         match io.readi(&mut buffer) {
+            Ok(0) => thread::sleep(RETRY_DELAY),
             Ok(frames_read) => {
-                if frames_read == 0 {
-                    continue;
-                }
-
+                consecutive_errors = 0;
                 let byte_count = frames_read * config.channels as usize * 2;
-
-                let seq = sequence.fetch_add(1, Ordering::Relaxed);
                 let frame = AudioFrame::new_interleaved(
                     Bytes::copy_from_slice(&buffer[..byte_count]),
                     config.channels,
-                    48_000,
-                    seq,
+                    config.sample_rate,
                 );
-
                 if frame_tx.receiver_count() > 0 {
-                    if let Err(e) = frame_tx.send(frame) {
-                        debug!("No audio receivers: {}", e);
-                    }
+                    let _ = frame_tx.send(frame);
                 }
             }
-            Err(e) => {
-                let desc = e.to_string();
-                if is_device_lost_error(&desc) {
+            Err(error) if error.errno() == libc::EAGAIN => thread::sleep(RETRY_DELAY),
+            Err(error) if is_device_lost_errno(error.errno()) => {
+                return Err(AppError::AudioError(format!(
+                    "Audio device lost while reading {}: {}",
+                    config.device_name, error
+                )));
+            }
+            Err(error) if error.errno() == libc::EPIPE => {
+                warn_throttled!(log_throttler, "buffer_overrun", "Audio buffer overrun");
+                pcm.prepare().map_err(|prepare_error| {
+                    AppError::AudioError(format!(
+                        "Failed to recover after audio overrun ({error}): {prepare_error}"
+                    ))
+                })?;
+                consecutive_errors = 0;
+            }
+            Err(error) => {
+                consecutive_errors += 1;
+                warn_throttled!(log_throttler, "read_error", "Audio read error: {}", error);
+                if consecutive_errors >= MAX_CONSECUTIVE_READ_ERRORS {
                     return Err(AppError::AudioError(format!(
-                        "Audio device lost while reading {}: {}",
-                        config.device_name, e
+                        "Audio capture failed {consecutive_errors} times consecutively: {error}"
                     )));
-                } else if desc.contains("EPIPE") || desc.contains("Broken pipe") {
-                    warn_throttled!(log_throttler, "buffer_overrun", "Audio buffer overrun");
-                    let _ = pcm.prepare();
-                } else {
-                    error_throttled!(log_throttler, "read_error", "Audio read error: {}", e);
                 }
+                thread::sleep(RETRY_DELAY);
             }
         }
     }
 
-    info!("Audio capture stopped");
+    debug!("ALSA capture worker stopped");
     Ok(())
 }
 
-fn is_device_lost_error(desc: &str) -> bool {
-    desc.contains("No such device")
-        || desc.contains("ENODEV")
-        || desc.contains("ENXIO")
-        || desc.contains("ESHUTDOWN")
+fn configure_pcm(pcm: &PCM, config: &AudioConfig) -> Result<()> {
+    let params = HwParams::any(pcm)
+        .map_err(|error| AppError::AudioError(format!("Failed to get HwParams: {error}")))?;
+    params
+        .set_channels(config.channels)
+        .and_then(|_| params.set_rate(config.sample_rate, ValueOr::Nearest))
+        .and_then(|_| params.set_format(Format::s16()))
+        .and_then(|_| params.set_access(Access::RWInterleaved))
+        .and_then(|_| params.set_buffer_size_near(config.buffer_frames as Frames))
+        .and_then(|_| params.set_period_size_near(config.period_frames as Frames, ValueOr::Nearest))
+        .and_then(|_| pcm.hw_params(&params))
+        .map_err(|error| AppError::AudioError(format!("Failed to configure audio PCM: {error}")))?;
+
+    let actual = pcm
+        .hw_params_current()
+        .map_err(|error| AppError::AudioError(format!("Failed to read PCM parameters: {error}")))?;
+    let actual_rate = actual
+        .get_rate()
+        .map_err(|error| AppError::AudioError(format!("Failed to read sample rate: {error}")))?;
+    let actual_channels = actual
+        .get_channels()
+        .map_err(|error| AppError::AudioError(format!("Failed to read channels: {error}")))?;
+    if actual_rate != config.sample_rate || actual_channels != config.channels {
+        return Err(AppError::AudioError(format!(
+            "Audio device negotiated {actual_rate} Hz/{actual_channels} ch; expected {} Hz/{} ch",
+            config.sample_rate, config.channels
+        )));
+    }
+    Ok(())
+}
+
+fn is_device_lost_errno(errno: i32) -> bool {
+    matches!(errno, libc::ENODEV | libc::ENXIO | libc::ESHUTDOWN)
 }

src/audio/capture_windows.rs

@@ -1,198 +1,23 @@
 use bytes::Bytes;
 use cpal::traits::{DeviceTrait, StreamTrait};
 use cpal::{BufferSize, SampleFormat, StreamConfig};
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::mpsc;
 use std::sync::Arc;
-use std::time::{Duration, Instant};
-use tokio::sync::{broadcast, watch, Mutex};
+use std::time::Duration;
+use tokio::sync::{broadcast, watch};
 use tracing::{debug, info};
 
-use crate::audio::device::{find_wasapi_device, AudioDeviceInfo};
+use super::{AudioConfig, AudioFrame, CaptureState};
+use crate::audio::device::find_wasapi_device;
 use crate::error::{AppError, Result};
-use crate::error_throttled;
 use crate::utils::LogThrottler;
 
-#[derive(Debug, Clone)]
-pub struct AudioConfig {
-    pub device_name: String,
-    pub sample_rate: u32,
-    pub channels: u32,
-    pub frame_size: u32,
-    pub buffer_frames: u32,
-    pub period_frames: u32,
-}
-
-impl Default for AudioConfig {
-    fn default() -> Self {
-        Self {
-            device_name: String::new(),
-            sample_rate: 48000,
-            channels: 2,
-            frame_size: 960,
-            buffer_frames: 4096,
-            period_frames: 960,
-        }
-    }
-}
-
-impl AudioConfig {
-    pub fn for_device(device: &AudioDeviceInfo) -> Self {
-        Self {
-            device_name: device.name.clone(),
-            ..Default::default()
-        }
-    }
-
-    pub fn bytes_per_sample(&self) -> u32 {
-        2 * self.channels
-    }
-
-    pub fn bytes_per_frame(&self) -> usize {
-        (self.frame_size * self.bytes_per_sample()) as usize
-    }
-}
-
-#[derive(Debug, Clone)]
-pub struct AudioFrame {
-    pub data: Bytes,
-    pub sample_rate: u32,
-    pub channels: u32,
-    pub samples: u32,
-    pub sequence: u64,
-    pub timestamp: Instant,
-}
-
-impl AudioFrame {
-    pub fn new_interleaved(data: Bytes, channels: u32, sample_rate: u32, sequence: u64) -> Self {
-        let bps = 2 * channels;
-        Self {
-            samples: data.len() as u32 / bps,
-            data,
-            sample_rate,
-            channels,
-            sequence,
-            timestamp: Instant::now(),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum CaptureState {
-    Stopped,
-    Running,
-    Error,
-}
-
-pub struct AudioCapturer {
-    config: AudioConfig,
-    state: Arc<watch::Sender<CaptureState>>,
-    state_rx: watch::Receiver<CaptureState>,
-    frame_tx: broadcast::Sender<AudioFrame>,
-    stop_flag: Arc<AtomicBool>,
-    sequence: Arc<AtomicU64>,
-    capture_handle: Mutex<Option<tokio::task::JoinHandle<()>>>,
-    log_throttler: LogThrottler,
-}
-
-impl AudioCapturer {
-    pub fn new(config: AudioConfig) -> Self {
-        let (state_tx, state_rx) = watch::channel(CaptureState::Stopped);
-        let (frame_tx, _) = broadcast::channel(16);
-
-        Self {
-            config,
-            state: Arc::new(state_tx),
-            state_rx,
-            frame_tx,
-            stop_flag: Arc::new(AtomicBool::new(false)),
-            sequence: Arc::new(AtomicU64::new(0)),
-            capture_handle: Mutex::new(None),
-            log_throttler: LogThrottler::with_secs(5),
-        }
-    }
-
-    pub fn state(&self) -> CaptureState {
-        *self.state_rx.borrow()
-    }
-
-    pub fn state_watch(&self) -> watch::Receiver<CaptureState> {
-        self.state_rx.clone()
-    }
-
-    pub fn subscribe(&self) -> broadcast::Receiver<AudioFrame> {
-        self.frame_tx.subscribe()
-    }
-
-    pub async fn start(&self) -> Result<()> {
-        if self.state() == CaptureState::Running {
-            return Ok(());
-        }
-
-        debug!(
-            "Starting WASAPI audio capture on {} at {}Hz {}ch",
-            self.config.device_name, self.config.sample_rate, self.config.channels
-        );
-
-        self.stop_flag.store(false, Ordering::SeqCst);
-
-        let config = self.config.clone();
-        let state = self.state.clone();
-        let frame_tx = self.frame_tx.clone();
-        let stop_flag = self.stop_flag.clone();
-        let sequence = self.sequence.clone();
-        let log_throttler = self.log_throttler.clone();
-
-        let handle = tokio::task::spawn_blocking(move || {
-            let result = run_capture(
-                &config,
-                &state,
-                &frame_tx,
-                &stop_flag,
-                &sequence,
-                &log_throttler,
-            );
-
-            if let Err(e) = result {
-                error_throttled!(
-                    log_throttler,
-                    "capture_error",
-                    "WASAPI audio capture error: {}",
-                    e
-                );
-                let _ = state.send(CaptureState::Error);
-            } else {
-                let _ = state.send(CaptureState::Stopped);
-            }
-        });
-
-        *self.capture_handle.lock().await = Some(handle);
-        Ok(())
-    }
-
-    pub async fn stop(&self) -> Result<()> {
-        info!("Stopping WASAPI audio capture");
-        self.stop_flag.store(true, Ordering::SeqCst);
-
-        if let Some(handle) = self.capture_handle.lock().await.take() {
-            let _ = handle.await;
-        }
-
-        let _ = self.state.send(CaptureState::Stopped);
-        Ok(())
-    }
-
-    pub fn is_running(&self) -> bool {
-        self.state() == CaptureState::Running
-    }
-}
-
-fn run_capture(
+pub(super) fn run_capture(
     config: &AudioConfig,
     state: &watch::Sender<CaptureState>,
     frame_tx: &broadcast::Sender<AudioFrame>,
     stop_flag: &AtomicBool,
-    sequence: &AtomicU64,
     log_throttler: &LogThrottler,
 ) -> Result<()> {
     let device = find_wasapi_device(&config.device_name)?;
@@ -272,12 +97,10 @@ fn run_capture(
                 if samples.is_empty() {
                     continue;
                 }
-                let seq = sequence.fetch_add(1, Ordering::Relaxed);
                 let frame = AudioFrame::new_interleaved(
                     Bytes::copy_from_slice(bytemuck::cast_slice(&samples)),
                     2,
                     48_000,
-                    seq,
                 );
                 if frame_tx.receiver_count() > 0 {
                     if let Err(e) = frame_tx.send(frame) {

src/audio/controller.rs

@@ -1,8 +1,7 @@
 //! Device selection, quality presets, streaming.
 
-use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
-use tokio::sync::RwLock;
+use tokio::sync::{Mutex, RwLock};
 use tracing::{debug, info};
 
 use super::capture::AudioConfig;
@@ -22,23 +21,37 @@ pub(super) type AudioRecoveredCallback = Arc<dyn Fn() + Send + Sync>;
 pub struct AudioController {
     config: Arc<RwLock<AudioControllerConfig>>,
     streamer: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
-    devices: Arc<RwLock<Vec<AudioDeviceInfo>>>,
     event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
     monitor: Arc<AudioHealthMonitor>,
-    recovery_in_progress: Arc<AtomicBool>,
+    recovery: recovery::AudioRecovery,
     recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
+    operation: Arc<Mutex<()>>,
 }
 
 impl AudioController {
     pub fn new(config: AudioControllerConfig) -> Self {
+        let config = Arc::new(RwLock::new(config));
+        let streamer = Arc::new(RwLock::new(None));
+        let event_bus = Arc::new(RwLock::new(None));
+        let monitor = Arc::new(AudioHealthMonitor::new());
+        let recovered_callback = Arc::new(RwLock::new(None));
+        let operation = Arc::new(Mutex::new(()));
+        let recovery = recovery::AudioRecovery::new(
+            config.clone(),
+            streamer.clone(),
+            event_bus.clone(),
+            monitor.clone(),
+            recovered_callback.clone(),
+            operation.clone(),
+        );
         Self {
-            config: Arc::new(RwLock::new(config)),
-            streamer: Arc::new(RwLock::new(None)),
-            devices: Arc::new(RwLock::new(Vec::new())),
-            event_bus: Arc::new(RwLock::new(None)),
-            monitor: Arc::new(AudioHealthMonitor::new()),
-            recovery_in_progress: Arc::new(AtomicBool::new(false)),
-            recovered_callback: Arc::new(RwLock::new(None)),
+            config,
+            streamer,
+            event_bus,
+            monitor,
+            recovery,
+            recovered_callback,
+            operation,
         }
     }
 
@@ -55,31 +68,6 @@ impl AudioController {
             bus.mark_device_info_dirty();
         }
     }
-    fn spawn_recovery_task(&self, lost_device: String, reason: String) {
-        recovery::spawn_recovery_task(
-            self.config.clone(),
-            self.streamer.clone(),
-            self.event_bus.clone(),
-            self.monitor.clone(),
-            self.recovery_in_progress.clone(),
-            self.recovered_callback.clone(),
-            lost_device,
-            reason,
-        );
-    }
-
-    fn spawn_stream_monitor(&self, streamer: Arc<AudioStreamer>, device: String) {
-        recovery::spawn_stream_monitor(
-            self.config.clone(),
-            self.streamer.clone(),
-            self.event_bus.clone(),
-            self.monitor.clone(),
-            self.recovery_in_progress.clone(),
-            self.recovered_callback.clone(),
-            streamer,
-            device,
-        );
-    }
 
     pub async fn list_devices(&self) -> Result<Vec<AudioDeviceInfo>> {
         let current_device = if self.is_streaming().await {
@@ -88,26 +76,19 @@ impl AudioController {
             None
         };
 
-        let devices = enumerate_audio_devices_with_current(current_device.as_deref())?;
-        *self.devices.write().await = devices.clone();
-        Ok(devices)
-    }
-
-    pub async fn get_cached_devices(&self) -> Vec<AudioDeviceInfo> {
-        self.devices.read().await.clone()
+        enumerate_audio_devices_with_current(current_device.as_deref())
     }
 
     pub async fn select_device(&self, device: &str) -> Result<()> {
+        let _operation = self.operation.lock().await;
+        self.recovery.cancel();
         let devices = self.list_devices().await?;
         let found = devices
             .iter()
             .any(|d| d.name == device || d.description.contains(device));
 
         if !found {
-            return Err(AppError::AudioError(format!(
-                "Audio device not found: {}",
-                device
-            )));
+            return Err(AppError::NotFound(format!("audio device {device}")));
         }
 
         {
@@ -118,14 +99,15 @@ impl AudioController {
         info!("Audio device selected: {}", device);
 
         if self.is_streaming().await {
-            self.stop_streaming().await?;
-            self.start_streaming().await?;
+            self.stop_streaming_inner().await?;
+            self.start_streaming_inner().await?;
         }
 
         Ok(())
     }
 
     pub async fn set_quality(&self, quality: AudioQuality) -> Result<()> {
+        let _operation = self.operation.lock().await;
         {
             let mut config = self.config.write().await;
             config.quality = quality;
@@ -144,6 +126,12 @@ impl AudioController {
     }
 
     pub async fn start_streaming(&self) -> Result<()> {
+        let _operation = self.operation.lock().await;
+        self.recovery.cancel();
+        self.start_streaming_inner().await
+    }
+
+    async fn start_streaming_inner(&self) -> Result<()> {
         {
             let config = self.config.read().await;
             if !config.enabled {
@@ -171,7 +159,7 @@ impl AudioController {
 
         if let Some(error_msg) = select_error {
             self.monitor.report_error(&error_msg, "start_failed").await;
-            self.spawn_recovery_task("auto".to_string(), error_msg.clone());
+            self.recovery.start("auto".to_string(), error_msg.clone());
             self.mark_device_info_dirty().await;
             return Err(AppError::AudioError(error_msg));
         }
@@ -194,7 +182,7 @@ impl AudioController {
             let error_msg = format!("Failed to start audio: {}", e);
 
             self.monitor.report_error(&error_msg, "start_failed").await;
-            self.spawn_recovery_task(device_name.clone(), error_msg.clone());
+            self.recovery.start(device_name.clone(), error_msg.clone());
 
             self.mark_device_info_dirty().await;
 
@@ -203,14 +191,13 @@ impl AudioController {
 
         let streamer_for_monitor = streamer.clone();
         *self.streamer.write().await = Some(streamer);
-        self.spawn_stream_monitor(streamer_for_monitor, device_name.clone());
+        self.recovery
+            .monitor(streamer_for_monitor, device_name.clone());
 
         if self.monitor.is_error().await {
             self.monitor.report_recovered().await;
         }
 
-        self.recovery_in_progress.store(false, Ordering::SeqCst);
-
         self.mark_device_info_dirty().await;
 
         info!("Audio streaming started");
@@ -218,7 +205,12 @@ impl AudioController {
     }
 
     pub async fn stop_streaming(&self) -> Result<()> {
-        self.recovery_in_progress.store(false, Ordering::SeqCst);
+        let _operation = self.operation.lock().await;
+        self.stop_streaming_inner().await
+    }
+
+    async fn stop_streaming_inner(&self) -> Result<()> {
+        self.recovery.cancel();
 
         if let Some(streamer) = self.streamer.write().await.take() {
             streamer.stop().await?;
@@ -249,7 +241,7 @@ impl AudioController {
         let (streaming, subscriber_count) = if let Some(ref streamer) = *self.streamer.read().await
         {
             let streaming = streamer.is_running();
-            let subscriber_count = streamer.stats().subscriber_count;
+            let subscriber_count = streamer.subscriber_count();
             (streaming, subscriber_count)
         } else {
             (false, 0)
@@ -278,13 +270,15 @@ impl AudioController {
     }
 
     pub async fn set_enabled(&self, enabled: bool) -> Result<()> {
+        let _operation = self.operation.lock().await;
+        self.recovery.cancel();
         {
             let mut config = self.config.write().await;
             config.enabled = enabled;
         }
 
         if !enabled && self.is_streaming().await {
-            self.stop_streaming().await?;
+            self.stop_streaming_inner().await?;
         }
 
         info!("Audio enabled: {}", enabled);
@@ -292,16 +286,18 @@ impl AudioController {
     }
 
     pub async fn update_config(&self, new_config: AudioControllerConfig) -> Result<()> {
+        let _operation = self.operation.lock().await;
+        self.recovery.cancel();
         let was_streaming = self.is_streaming().await;
 
         if was_streaming {
-            self.stop_streaming().await?;
+            self.stop_streaming_inner().await?;
         }
 
         *self.config.write().await = new_config.clone();
 
         if new_config.enabled {
-            self.start_streaming().await?;
+            self.start_streaming_inner().await?;
         }
 
         Ok(())

src/audio/device.rs

@@ -1,3 +1,9 @@
+//! Shared device description with platform-specific enumeration backends.
+
+use serde::Serialize;
+
+use crate::error::Result;
+
 #[cfg(unix)]
 #[path = "device_linux.rs"]
 mod imp;
@@ -6,4 +12,32 @@ mod imp;
 #[path = "device_windows.rs"]
 mod imp;
 
-pub use imp::*;
+#[derive(Debug, Clone, Serialize)]
+pub struct AudioDeviceInfo {
+    pub name: String,
+    pub description: String,
+    pub card_index: i32,
+    pub device_index: i32,
+    pub sample_rates: Vec<u32>,
+    pub channels: Vec<u32>,
+    pub is_capture: bool,
+    pub is_hdmi: bool,
+    pub usb_bus: Option<String>,
+}
+
+pub fn enumerate_audio_devices() -> Result<Vec<AudioDeviceInfo>> {
+    imp::enumerate_audio_devices_with_current(None)
+}
+
+pub fn enumerate_audio_devices_with_current(
+    current_device: Option<&str>,
+) -> Result<Vec<AudioDeviceInfo>> {
+    imp::enumerate_audio_devices_with_current(current_device)
+}
+
+pub(crate) fn find_best_audio_device() -> Result<AudioDeviceInfo> {
+    imp::find_best_audio_device()
+}
+
+#[cfg(windows)]
+pub(crate) use imp::find_wasapi_device;

src/audio/device_linux.rs

@@ -1,23 +1,10 @@
 use alsa::pcm::HwParams;
 use alsa::{Direction, PCM};
-use serde::Serialize;
 use tracing::{debug, info, warn};
 
+use super::AudioDeviceInfo;
 use crate::error::{AppError, Result};
 
-#[derive(Debug, Clone, Serialize)]
-pub struct AudioDeviceInfo {
-    pub name: String,
-    pub description: String,
-    pub card_index: i32,
-    pub device_index: i32,
-    pub sample_rates: Vec<u32>,
-    pub channels: Vec<u32>,
-    pub is_capture: bool,
-    pub is_hdmi: bool,
-    pub usb_bus: Option<String>,
-}
-
 fn get_usb_bus_info(card_index: i32) -> Option<String> {
     if card_index < 0 {
         return None;
@@ -28,26 +15,18 @@ fn get_usb_bus_info(card_index: i32) -> Option<String> {
     let link_str = link_target.to_string_lossy();
 
     for component in link_str.split('/') {
-        if component.contains('-') && !component.contains(':') {
-            if component
-                .chars()
-                .next()
-                .map(|c| c.is_ascii_digit())
-                .unwrap_or(false)
-            {
-                return Some(component.to_string());
-            }
+        if component.contains('-')
+            && !component.contains(':')
+            && component.chars().next().is_some_and(|c| c.is_ascii_digit())
+        {
+            return Some(component.to_string());
         }
     }
 
     None
 }
 
-pub fn enumerate_audio_devices() -> Result<Vec<AudioDeviceInfo>> {
-    enumerate_audio_devices_with_current(None)
-}
-
-pub fn enumerate_audio_devices_with_current(
+pub(super) fn enumerate_audio_devices_with_current(
     current_device: Option<&str>,
 ) -> Result<Vec<AudioDeviceInfo>> {
     let mut devices = Vec::new();
@@ -153,8 +132,8 @@ fn query_device_caps(pcm: &PCM) -> (Vec<u32>, Vec<u32>) {
     (supported_rates, supported_channels)
 }
 
-pub fn find_best_audio_device() -> Result<AudioDeviceInfo> {
-    let devices = enumerate_audio_devices()?;
+pub(super) fn find_best_audio_device() -> Result<AudioDeviceInfo> {
+    let devices = enumerate_audio_devices_with_current(None)?;
 
     if devices.is_empty() {
         return Err(AppError::AudioError(
@@ -194,7 +173,7 @@ mod tests {
 
     #[test]
     fn test_enumerate_devices() {
-        let result = enumerate_audio_devices();
+        let result = enumerate_audio_devices_with_current(None);
         println!("Audio devices: {:?}", result);
         assert!(result.is_ok());
     }

src/audio/device_windows.rs

@@ -1,29 +1,12 @@
 use cpal::traits::{DeviceTrait, HostTrait};
 use cpal::DeviceId;
-use serde::Serialize;
 use std::str::FromStr;
 use tracing::{debug, info, warn};
 
+use super::AudioDeviceInfo;
 use crate::error::{AppError, Result};
 
-#[derive(Debug, Clone, Serialize)]
-pub struct AudioDeviceInfo {
-    pub name: String,
-    pub description: String,
-    pub card_index: i32,
-    pub device_index: i32,
-    pub sample_rates: Vec<u32>,
-    pub channels: Vec<u32>,
-    pub is_capture: bool,
-    pub is_hdmi: bool,
-    pub usb_bus: Option<String>,
-}
-
-pub fn enumerate_audio_devices() -> Result<Vec<AudioDeviceInfo>> {
-    enumerate_audio_devices_with_current(None)
-}
-
-pub fn enumerate_audio_devices_with_current(
+pub(super) fn enumerate_audio_devices_with_current(
     current_device: Option<&str>,
 ) -> Result<Vec<AudioDeviceInfo>> {
     let host = cpal::default_host();
@@ -192,8 +175,8 @@ pub(crate) fn find_wasapi_device(requested_device: &str) -> Result<cpal::Device>
     )))
 }
 
-pub fn find_best_audio_device() -> Result<AudioDeviceInfo> {
-    let devices = enumerate_audio_devices()?;
+pub(super) fn find_best_audio_device() -> Result<AudioDeviceInfo> {
+    let devices = enumerate_audio_devices_with_current(None)?;
 
     if devices.is_empty() {
         return Err(AppError::AudioError(

src/audio/encoder.rs

@@ -5,7 +5,6 @@ use audiopus::{coder::Encoder, Application, Bitrate, Channels, SampleRate};
 use bytes::Bytes;
 use tracing::debug;
 
-use super::capture::AudioFrame;
 use crate::error::{AppError, Result};
 
 #[derive(Debug, Clone)]
@@ -154,11 +153,6 @@ impl OpusEncoder {
         })
     }
 
-    pub fn encode_frame(&mut self, frame: &AudioFrame) -> Result<OpusFrame> {
-        let samples: &[i16] = bytemuck::cast_slice(&frame.data);
-        self.encode(samples)
-    }
-
     pub fn config(&self) -> &OpusConfig {
         &self.config
     }

src/audio/mod.rs

@@ -1,16 +1,18 @@
 //! Platform audio capture, Opus encode, device enumeration, streaming, controller, health monitor.
 
 #[cfg(any(unix, windows))]
-pub mod capture;
-pub mod controller;
+mod capture;
+mod controller;
 #[cfg(any(unix, windows))]
-pub mod device;
+mod device;
 #[cfg(any(unix, windows))]
-pub mod encoder;
-pub mod monitor;
-pub mod recovery;
-pub mod streamer;
-pub mod types;
+mod encoder;
+mod monitor;
+mod recovery;
+mod streamer;
+mod types;
+#[cfg(unix)]
+pub mod uac;
 
 pub use capture::{AudioCapturer, AudioConfig, AudioFrame};
 pub use controller::AudioController;

src/audio/monitor.rs

@@ -71,14 +71,14 @@ impl AudioHealthMonitor {
 
     pub async fn report_recovered(&self) {
         let prev_status = self.status.read().await.clone();
+        self.suppress_display.store(false, Ordering::Relaxed);
 
         if prev_status != AudioHealthStatus::Healthy {
             let retry_count = self.retry_count.load(Ordering::Relaxed);
             info!("Audio recovered after {} retries", retry_count);
 
-            self.suppress_display.store(false, Ordering::Relaxed);
             self.retry_count.store(0, Ordering::Relaxed);
-            self.throttler.clear("audio_");
+            self.throttler.clear_all();
             *self.last_error_code.write().await = None;
             *self.status.write().await = AudioHealthStatus::Healthy;
         }

src/audio/recovery.rs

@@ -1,6 +1,9 @@
-use std::sync::atomic::{AtomicBool, Ordering};
+//! Audio device-loss monitoring and serialized recovery.
+
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
-use tokio::sync::RwLock;
+
+use tokio::sync::{Mutex, RwLock};
 use tracing::{debug, info, warn};
 
 use super::capture::AudioConfig;
@@ -9,312 +12,395 @@ use super::device::{enumerate_audio_devices, AudioDeviceInfo};
 use super::monitor::AudioHealthMonitor;
 use super::streamer::{AudioStreamState, AudioStreamer, AudioStreamerConfig};
 use super::types::AudioControllerConfig;
-use crate::events::{EventBus, StreamDeviceLostKind, SystemEvent};
+use crate::events::{EventBus, StreamKind, SystemEvent};
 
-const AUDIO_RECOVERY_RETRY_DELAY: std::time::Duration = std::time::Duration::from_secs(1);
+const RETRY_DELAY: std::time::Duration = std::time::Duration::from_secs(1);
+
+struct RecoveryControl {
+    /// Even values are idle; the following odd value is that recovery's token.
+    /// A single compare-exchange therefore owns both activity and generation.
+    state: AtomicU64,
+}
+
+impl RecoveryControl {
+    fn new() -> Self {
+        Self {
+            state: AtomicU64::new(0),
+        }
+    }
+
+    fn begin(&self) -> Option<u64> {
+        let idle = self.state.load(Ordering::Acquire);
+        if !idle.is_multiple_of(2) {
+            return None;
+        }
+        let token = idle.wrapping_add(1);
+        self.state
+            .compare_exchange(idle, token, Ordering::AcqRel, Ordering::Acquire)
+            .ok()
+            .map(|_| token)
+    }
+
+    fn is_current(&self, token: u64) -> bool {
+        self.state.load(Ordering::Acquire) == token
+    }
+
+    fn finish(&self, token: u64) {
+        let _ = self.state.compare_exchange(
+            token,
+            token.wrapping_add(1),
+            Ordering::AcqRel,
+            Ordering::Acquire,
+        );
+    }
+
+    fn cancel(&self) {
+        let token = self.state.load(Ordering::Acquire);
+        if !token.is_multiple_of(2) {
+            let _ = self.state.compare_exchange(
+                token,
+                token.wrapping_add(1),
+                Ordering::AcqRel,
+                Ordering::Acquire,
+            );
+        }
+    }
+}
+
+struct RecoveryLease {
+    control: Arc<RecoveryControl>,
+    generation: u64,
+}
+
+impl Drop for RecoveryLease {
+    fn drop(&mut self) {
+        self.control.finish(self.generation);
+    }
+}
+
+struct RecoveryInner {
+    config: Arc<RwLock<AudioControllerConfig>>,
+    streamer: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
+    event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
+    monitor: Arc<AudioHealthMonitor>,
+    recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
+    operation: Arc<Mutex<()>>,
+    control: Arc<RecoveryControl>,
+}
+
+#[derive(Clone)]
+pub(super) struct AudioRecovery {
+    inner: Arc<RecoveryInner>,
+}
+
+impl AudioRecovery {
+    pub(super) fn new(
+        config: Arc<RwLock<AudioControllerConfig>>,
+        streamer: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
+        event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
+        monitor: Arc<AudioHealthMonitor>,
+        recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
+        operation: Arc<Mutex<()>>,
+    ) -> Self {
+        Self {
+            inner: Arc::new(RecoveryInner {
+                config,
+                streamer,
+                event_bus,
+                monitor,
+                recovered_callback,
+                operation,
+                control: Arc::new(RecoveryControl::new()),
+            }),
+        }
+    }
+
+    pub(super) fn cancel(&self) {
+        self.inner.control.cancel();
+    }
+
+    pub(super) fn monitor(&self, streamer: Arc<AudioStreamer>, device: String) {
+        let recovery = self.clone();
+        let mut state = streamer.state_watch();
+        tokio::spawn(async move {
+            loop {
+                let current_state = *state.borrow();
+                match current_state {
+                    AudioStreamState::Error => {}
+                    AudioStreamState::Stopped => return,
+                    AudioStreamState::Starting | AudioStreamState::Running => {
+                        if state.changed().await.is_err() {
+                            return;
+                        }
+                        continue;
+                    }
+                }
+
+                // Serialize the ownership check with user-driven start/stop
+                // operations. If a stop already owns the operation lock, it
+                // removes the streamer before this monitor may start recovery.
+                let _operation = recovery.inner.operation.lock().await;
+                let is_current = recovery
+                    .inner
+                    .streamer
+                    .read()
+                    .await
+                    .as_ref()
+                    .is_some_and(|current| Arc::ptr_eq(current, &streamer));
+                if !is_current {
+                    return;
+                }
+
+                let reason = format!("Audio device lost: {device}");
+                recovery
+                    .inner
+                    .monitor
+                    .report_error(&reason, "device_lost")
+                    .await;
+                recovery.start(device, reason);
+                return;
+            }
+        });
+    }
+
+    pub(super) fn start(&self, lost_device: String, reason: String) {
+        let Some(generation) = self.inner.control.begin() else {
+            debug!("Audio recovery already in progress");
+            return;
+        };
+        let recovery = self.clone();
+        tokio::spawn(async move {
+            let _lease = RecoveryLease {
+                control: recovery.inner.control.clone(),
+                generation,
+            };
+            recovery.run(generation, lost_device, reason).await;
+        });
+    }
+
+    async fn run(&self, generation: u64, lost_device: String, reason: String) {
+        warn!("Audio recovery started for {lost_device}: {reason}");
+        self.publish_device_lost(&lost_device, &reason).await;
+        self.publish_state(
+            "device_lost",
+            Some(lost_device.clone()),
+            Some("audio_device_lost"),
+            Some(RETRY_DELAY.as_millis() as u64),
+        )
+        .await;
+
+        let mut attempt = 0u32;
+        while self.inner.control.is_current(generation) {
+            let config = self.inner.config.read().await.clone();
+            if !config.enabled {
+                return;
+            }
+            if self
+                .inner
+                .streamer
+                .read()
+                .await
+                .as_ref()
+                .is_some_and(|streamer| streamer.is_running())
+            {
+                return;
+            }
+
+            attempt = attempt.saturating_add(1);
+            self.publish_reconnecting(&lost_device, attempt).await;
+            self.publish_state(
+                "device_lost",
+                Some(lost_device.clone()),
+                Some("audio_reconnecting"),
+                Some(RETRY_DELAY.as_millis() as u64),
+            )
+            .await;
+            tokio::time::sleep(RETRY_DELAY).await;
+            if !self.inner.control.is_current(generation) {
+                return;
+            }
+
+            let devices = match enumerate_audio_devices() {
+                Ok(devices) => devices,
+                Err(error) => {
+                    debug!("Audio recovery enumeration attempt {attempt} failed: {error}");
+                    continue;
+                }
+            };
+            let Some(device) = select_recovery_device(&devices, &config.device) else {
+                debug!("No audio device found on recovery attempt {attempt}");
+                continue;
+            };
+            let streamer = Arc::new(AudioStreamer::with_config(AudioStreamerConfig {
+                capture: AudioConfig {
+                    device_name: device.name.clone(),
+                    ..Default::default()
+                },
+                opus: config.quality.to_opus_config(),
+            }));
+
+            if let Err(error) = streamer.start().await {
+                debug!(
+                    "Audio recovery attempt {attempt} failed with {}: {error}",
+                    device.name
+                );
+                continue;
+            }
+
+            // Commit a recovered streamer under the same operation lock used by
+            // user-driven start/stop/config updates. Cancellation is rechecked
+            // after acquiring the lock so an old task cannot resurrect itself.
+            let _operation = self.inner.operation.lock().await;
+            if !self.inner.control.is_current(generation) || !self.inner.config.read().await.enabled
+            {
+                let _ = streamer.stop().await;
+                return;
+            }
+
+            self.inner.config.write().await.device = device.name.clone();
+            *self.inner.streamer.write().await = Some(streamer.clone());
+            self.inner.monitor.report_recovered().await;
+            self.publish_recovered(&device.name).await;
+            if let Some(callback) = self.inner.recovered_callback.read().await.clone() {
+                callback();
+            }
+            self.publish_state("streaming", Some(device.name.clone()), None, None)
+                .await;
+            info!(
+                "Audio recovered with {} after {} attempts",
+                device.name, attempt
+            );
+            self.inner.control.finish(generation);
+            self.monitor(streamer, device.name);
+            drop(_operation);
+            return;
+        }
+    }
+
+    async fn publish_state(
+        &self,
+        state: &str,
+        device: Option<String>,
+        reason: Option<&str>,
+        next_retry_ms: Option<u64>,
+    ) {
+        if let Some(bus) = self.inner.event_bus.read().await.as_ref() {
+            bus.publish(SystemEvent::StreamStateChanged {
+                kind: StreamKind::Audio,
+                state: state.to_string(),
+                device,
+                reason: reason.map(str::to_string),
+                next_retry_ms,
+            });
+            bus.mark_device_info_dirty();
+        }
+    }
+
+    async fn publish_device_lost(&self, device: &str, reason: &str) {
+        if let Some(bus) = self.inner.event_bus.read().await.as_ref() {
+            bus.publish(SystemEvent::StreamDeviceLost {
+                kind: StreamKind::Audio,
+                device: device.to_string(),
+                reason: reason.to_string(),
+            });
+        }
+    }
+
+    async fn publish_reconnecting(&self, device: &str, attempt: u32) {
+        if let Some(bus) = self.inner.event_bus.read().await.as_ref() {
+            bus.publish(SystemEvent::StreamReconnecting {
+                device: device.to_string(),
+                attempt,
+            });
+        }
+    }
+
+    async fn publish_recovered(&self, device: &str) {
+        if let Some(bus) = self.inner.event_bus.read().await.as_ref() {
+            bus.publish(SystemEvent::StreamRecovered {
+                device: device.to_string(),
+            });
+        }
+    }
+}
 
 pub(super) fn select_recovery_device(
     devices: &[AudioDeviceInfo],
     preferred: &str,
 ) -> Option<AudioDeviceInfo> {
-    if let Some(device) = devices
-        .iter()
-        .find(|d| !preferred.trim().is_empty() && d.name == preferred)
-    {
-        return Some(device.clone());
-    }
-
     devices
         .iter()
-        .find(|d| d.is_hdmi && d.sample_rates.contains(&48_000) && d.channels.contains(&2))
+        .find(|device| !preferred.trim().is_empty() && device.name == preferred)
         .or_else(|| {
-            devices
-                .iter()
-                .find(|d| d.sample_rates.contains(&48_000) && d.channels.contains(&2))
+            devices.iter().find(|device| {
+                device.is_hdmi
+                    && device.sample_rates.contains(&48_000)
+                    && device.channels.contains(&2)
+            })
+        })
+        .or_else(|| {
+            devices.iter().find(|device| {
+                device.sample_rates.contains(&48_000) && device.channels.contains(&2)
+            })
         })
         .or_else(|| devices.first())
         .cloned()
 }
 
-async fn publish_state(
-    event_bus: &Arc<RwLock<Option<Arc<EventBus>>>>,
-    state: &str,
-    device: Option<String>,
-    reason: Option<&str>,
-    next_retry_ms: Option<u64>,
-) {
-    if let Some(bus) = event_bus.read().await.as_ref() {
-        bus.publish(SystemEvent::StreamStateChanged {
-            state: state.to_string(),
-            device,
-            reason: reason.map(str::to_string),
-            next_retry_ms,
-        });
-        bus.mark_device_info_dirty();
-    }
-}
+#[cfg(test)]
+mod tests {
+    use super::*;
 
-async fn publish_device_lost(
-    event_bus: &Arc<RwLock<Option<Arc<EventBus>>>>,
-    device: &str,
-    reason: &str,
-) {
-    if let Some(bus) = event_bus.read().await.as_ref() {
-        bus.publish(SystemEvent::StreamDeviceLost {
-            kind: StreamDeviceLostKind::Audio,
-            device: device.to_string(),
-            reason: reason.to_string(),
-        });
-    }
-}
-
-async fn publish_reconnecting(
-    event_bus: &Arc<RwLock<Option<Arc<EventBus>>>>,
-    device: &str,
-    attempt: u32,
-) {
-    if let Some(bus) = event_bus.read().await.as_ref() {
-        bus.publish(SystemEvent::StreamReconnecting {
-            device: device.to_string(),
-            attempt,
-        });
-    }
-}
-
-async fn publish_recovered(event_bus: &Arc<RwLock<Option<Arc<EventBus>>>>, device: &str) {
-    if let Some(bus) = event_bus.read().await.as_ref() {
-        bus.publish(SystemEvent::StreamRecovered {
-            device: device.to_string(),
-        });
-    }
-}
-
-fn spawn_stream_monitor_from_parts(
-    config: Arc<RwLock<AudioControllerConfig>>,
-    streamer_slot: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
-    event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
-    monitor: Arc<AudioHealthMonitor>,
-    recovery_in_progress: Arc<AtomicBool>,
-    recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
-    streamer: Arc<AudioStreamer>,
-    device: String,
-) {
-    let mut state_rx = streamer.state_watch();
-
-    tokio::spawn(async move {
-        loop {
-            if state_rx.changed().await.is_err() {
-                return;
-            }
-
-            if *state_rx.borrow() != AudioStreamState::Error {
-                continue;
-            }
-
-            {
-                let current = streamer_slot.read().await;
-                if !current
-                    .as_ref()
-                    .is_some_and(|current| Arc::ptr_eq(current, &streamer))
-                {
-                    return;
-                }
-            }
-
-            let reason = format!("Audio device lost: {}", device);
-            monitor.report_error(&reason, "device_lost").await;
-            spawn_recovery_task_from_parts(
-                config,
-                streamer_slot,
-                event_bus,
-                monitor,
-                recovery_in_progress,
-                recovered_callback,
-                device,
-                reason,
-            );
-            return;
+    fn device(name: &str, compatible: bool, hdmi: bool) -> AudioDeviceInfo {
+        AudioDeviceInfo {
+            name: name.to_string(),
+            description: name.to_string(),
+            card_index: 0,
+            device_index: 0,
+            sample_rates: if compatible {
+                vec![48_000]
+            } else {
+                vec![44_100]
+            },
+            channels: vec![2],
+            is_capture: true,
+            is_hdmi: hdmi,
+            usb_bus: None,
         }
-    });
-}
-
-fn spawn_recovery_task_from_parts(
-    config: Arc<RwLock<AudioControllerConfig>>,
-    streamer_slot: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
-    event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
-    monitor: Arc<AudioHealthMonitor>,
-    recovery_in_progress: Arc<AtomicBool>,
-    recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
-    lost_device: String,
-    reason: String,
-) {
-    if recovery_in_progress.swap(true, Ordering::SeqCst) {
-        debug!("Audio recovery already in progress");
-        return;
     }
 
-    tokio::spawn(async move {
-        warn!("Audio recovery started for {}: {}", lost_device, reason);
-        publish_device_lost(&event_bus, &lost_device, &reason).await;
-        publish_state(
-            &event_bus,
-            "device_lost",
-            Some(lost_device.clone()),
-            Some("audio_device_lost"),
-            Some(AUDIO_RECOVERY_RETRY_DELAY.as_millis() as u64),
-        )
-        .await;
+    #[test]
+    fn stale_recovery_cannot_finish_a_new_generation() {
+        let control = RecoveryControl::new();
+        let stale = control.begin().unwrap();
+        control.cancel();
+        let current = control.begin().unwrap();
 
-        let mut attempt = 0u32;
+        control.finish(stale);
+        assert!(control.is_current(current));
+    }
 
-        loop {
-            if !recovery_in_progress.load(Ordering::SeqCst) {
-                debug!("Audio recovery canceled");
-                return;
-            }
+    #[test]
+    fn completed_recovery_cannot_finish_the_next_recovery() {
+        let control = RecoveryControl::new();
+        let completed = control.begin().unwrap();
+        control.finish(completed);
+        let current = control.begin().unwrap();
 
-            if streamer_slot
-                .read()
-                .await
-                .as_ref()
-                .is_some_and(|s| s.is_running())
-            {
-                recovery_in_progress.store(false, Ordering::SeqCst);
-                return;
-            }
+        control.finish(completed);
+        assert!(control.is_current(current));
+    }
 
-            let cfg: AudioControllerConfig = config.read().await.clone();
-            if !cfg.enabled {
-                recovery_in_progress.store(false, Ordering::SeqCst);
-                return;
-            }
-
-            attempt = attempt.saturating_add(1);
-            publish_reconnecting(&event_bus, &lost_device, attempt).await;
-            publish_state(
-                &event_bus,
-                "device_lost",
-                Some(lost_device.clone()),
-                Some("audio_reconnecting"),
-                Some(AUDIO_RECOVERY_RETRY_DELAY.as_millis() as u64),
-            )
-            .await;
-
-            tokio::time::sleep(AUDIO_RECOVERY_RETRY_DELAY).await;
-
-            let devices = match enumerate_audio_devices() {
-                Ok(devices) => devices,
-                Err(e) => {
-                    debug!(
-                        "Audio recovery enumerate failed (attempt {}): {}",
-                        attempt, e
-                    );
-                    continue;
-                }
-            };
-
-            let Some(device) = select_recovery_device(&devices, &cfg.device) else {
-                debug!("No audio devices found during recovery attempt {}", attempt);
-                continue;
-            };
-
-            let streamer_config = AudioStreamerConfig {
-                capture: AudioConfig {
-                    device_name: device.name.clone(),
-                    ..Default::default()
-                },
-                opus: cfg.quality.to_opus_config(),
-            };
-            let new_streamer = Arc::new(AudioStreamer::with_config(streamer_config));
-
-            match new_streamer.start().await {
-                Ok(()) => {
-                    {
-                        let mut cfg = config.write().await;
-                        cfg.device = device.name.clone();
-                    }
-                    *streamer_slot.write().await = Some(new_streamer.clone());
-                    monitor.report_recovered().await;
-                    publish_recovered(&event_bus, &device.name).await;
-                    if let Some(callback) = recovered_callback.read().await.clone() {
-                        callback();
-                    }
-                    publish_state(
-                        &event_bus,
-                        "streaming",
-                        Some(device.name.clone()),
-                        None,
-                        None,
-                    )
-                    .await;
-                    recovery_in_progress.store(false, Ordering::SeqCst);
-                    info!(
-                        "Audio device recovered with {} after {} attempts",
-                        device.name, attempt
-                    );
-                    spawn_stream_monitor_from_parts(
-                        config,
-                        streamer_slot,
-                        event_bus,
-                        monitor,
-                        recovery_in_progress,
-                        recovered_callback,
-                        new_streamer,
-                        device.name,
-                    );
-                    return;
-                }
-                Err(e) => {
-                    debug!(
-                        "Audio recovery start failed with {} (attempt {}): {}",
-                        device.name, attempt, e
-                    );
-                }
-            }
-        }
-    });
-}
-
-pub(super) fn spawn_stream_monitor(
-    config: Arc<RwLock<AudioControllerConfig>>,
-    streamer_slot: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
-    event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
-    monitor: Arc<AudioHealthMonitor>,
-    recovery_in_progress: Arc<AtomicBool>,
-    recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
-    streamer: Arc<AudioStreamer>,
-    device: String,
-) {
-    spawn_stream_monitor_from_parts(
-        config,
-        streamer_slot,
-        event_bus,
-        monitor,
-        recovery_in_progress,
-        recovered_callback,
-        streamer,
-        device,
-    );
-}
-
-pub(super) fn spawn_recovery_task(
-    config: Arc<RwLock<AudioControllerConfig>>,
-    streamer_slot: Arc<RwLock<Option<Arc<AudioStreamer>>>>,
-    event_bus: Arc<RwLock<Option<Arc<EventBus>>>>,
-    monitor: Arc<AudioHealthMonitor>,
-    recovery_in_progress: Arc<AtomicBool>,
-    recovered_callback: Arc<RwLock<Option<AudioRecoveredCallback>>>,
-    lost_device: String,
-    reason: String,
-) {
-    spawn_recovery_task_from_parts(
-        config,
-        streamer_slot,
-        event_bus,
-        monitor,
-        recovery_in_progress,
-        recovered_callback,
-        lost_device,
-        reason,
-    );
+    #[test]
+    fn recovery_prefers_requested_then_compatible_hdmi() {
+        let devices = vec![device("fallback", true, false), device("hdmi", true, true)];
+        assert_eq!(
+            select_recovery_device(&devices, "fallback").unwrap().name,
+            "fallback"
+        );
+        assert_eq!(
+            select_recovery_device(&devices, "missing").unwrap().name,
+            "hdmi"
+        );
+    }
 }

src/audio/streamer.rs

@@ -2,15 +2,15 @@
 
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
 use tokio::sync::{broadcast, mpsc, watch, Mutex as AsyncMutex, RwLock};
+use tokio::task::JoinHandle;
 use tracing::{debug, error, info, warn};
 
-use super::capture::{AudioCapturer, AudioConfig, AudioFrame, CaptureState};
+use super::capture::{AudioCapturer, AudioConfig, CaptureState};
 use super::encoder::{OpusConfig, OpusEncoder, OpusFrame};
 use crate::error::{AppError, Result};
-use bytemuck;
-use bytes::Bytes;
-use std::time::Duration;
 
 /// 48 kHz stereo: 20 ms = 960 × 2 samples (S16LE).
 const OPUS_STEREO_SAMPLES: usize = 960 * 2;
@@ -40,16 +40,6 @@ impl AudioStreamerConfig {
             opus: OpusConfig::default(),
         }
     }
-
-    pub fn with_bitrate(mut self, bitrate: u32) -> Self {
-        self.opus.bitrate = bitrate;
-        self
-    }
-}
-
-#[derive(Debug, Clone, Default)]
-pub struct AudioStreamStats {
-    pub subscriber_count: usize,
 }
 
 pub struct AudioStreamer {
@@ -60,6 +50,9 @@ pub struct AudioStreamer {
     encoder: Arc<AsyncMutex<Option<OpusEncoder>>>,
     opus_subscribers: Arc<Mutex<Vec<mpsc::Sender<Arc<OpusFrame>>>>>,
     stop_flag: Arc<AtomicBool>,
+    shutdown_generation: watch::Sender<u64>,
+    lifecycle: AsyncMutex<()>,
+    stream_task: AsyncMutex<Option<JoinHandle<()>>>,
 }
 
 impl AudioStreamer {
@@ -69,6 +62,7 @@ impl AudioStreamer {
 
     pub fn with_config(config: AudioStreamerConfig) -> Self {
         let (state_tx, state_rx) = watch::channel(AudioStreamState::Stopped);
+        let (shutdown_generation, _) = watch::channel(0);
 
         Self {
             config: RwLock::new(config),
@@ -78,6 +72,9 @@ impl AudioStreamer {
             encoder: Arc::new(AsyncMutex::new(None)),
             opus_subscribers: Arc::new(Mutex::new(Vec::new())),
             stop_flag: Arc::new(AtomicBool::new(false)),
+            shutdown_generation,
+            lifecycle: AsyncMutex::new(()),
+            stream_task: AsyncMutex::new(None),
         }
     }
 
@@ -90,7 +87,9 @@ impl AudioStreamer {
     }
 
     pub fn subscribe_opus(&self) -> mpsc::Receiver<Arc<OpusFrame>> {
-        let (tx, rx) = mpsc::channel::<Arc<OpusFrame>>(128);
+        // Keep latency bounded for real-time consumers. Slow receivers lose
+        // new frames instead of accumulating seconds of stale audio.
+        let (tx, rx) = mpsc::channel::<Arc<OpusFrame>>(4);
         self.opus_subscribers.lock().unwrap().push(tx);
         rx
     }
@@ -104,22 +103,6 @@ impl AudioStreamer {
             .count()
     }
 
-    pub fn stats(&self) -> AudioStreamStats {
-        AudioStreamStats {
-            subscriber_count: self.subscriber_count(),
-        }
-    }
-
-    pub async fn set_config(&self, config: AudioStreamerConfig) -> Result<()> {
-        if self.state() != AudioStreamState::Stopped {
-            return Err(AppError::AudioError(
-                "Cannot change config while streaming".to_string(),
-            ));
-        }
-        *self.config.write().await = config;
-        Ok(())
-    }
-
     pub async fn set_bitrate(&self, bitrate: u32) -> Result<()> {
         self.config.write().await.opus.bitrate = bitrate;
 
@@ -132,10 +115,25 @@ impl AudioStreamer {
     }
 
     pub async fn start(&self) -> Result<()> {
-        if self.state() == AudioStreamState::Running {
+        let _lifecycle = self.lifecycle.lock().await;
+        if matches!(
+            self.state(),
+            AudioStreamState::Starting | AudioStreamState::Running
+        ) {
             return Ok(());
         }
 
+        // Error and stopped states may still own completed task handles. Reap
+        // them before installing a new capture pipeline so restart is a clean
+        // lifecycle transition rather than an overwrite of old resources.
+        if let Some(capturer) = self.capturer.write().await.take() {
+            let _ = capturer.stop().await;
+        }
+        if let Some(task) = self.stream_task.lock().await.take() {
+            let _ = task.await;
+        }
+        *self.encoder.lock().await = None;
+
         let _ = self.state.send(AudioStreamState::Starting);
         self.stop_flag.store(false, Ordering::SeqCst);
 
@@ -149,13 +147,21 @@ impl AudioStreamer {
             config.opus.bitrate
         );
 
-        let capturer = Arc::new(AudioCapturer::new(config.capture.clone()));
-        *self.capturer.write().await = Some(capturer.clone());
-
-        let encoder = OpusEncoder::new(config.opus.clone())?;
+        let encoder = match OpusEncoder::new(config.opus.clone()) {
+            Ok(encoder) => encoder,
+            Err(error) => {
+                let _ = self.state.send(AudioStreamState::Error);
+                return Err(error);
+            }
+        };
         *self.encoder.lock().await = Some(encoder);
 
-        capturer.start().await?;
+        let capturer = Arc::new(AudioCapturer::new(config.capture.clone()));
+        *self.capturer.write().await = Some(capturer.clone());
+        if let Err(error) = capturer.start().await {
+            self.cleanup_failed_start(&capturer).await;
+            return Err(error);
+        }
 
         let mut capture_state = capturer.state_watch();
         let startup_result = tokio::time::timeout(Duration::from_secs(2), async {
@@ -168,7 +174,7 @@ impl AudioStreamer {
                             "Audio capture failed to start".to_string(),
                         ))
                     }
-                    CaptureState::Stopped => {
+                    CaptureState::Stopped | CaptureState::Starting => {
                         if capture_state.changed().await.is_err() {
                             return Err(AppError::AudioError(
                                 "Audio capture stopped during startup".to_string(),
@@ -183,17 +189,11 @@ impl AudioStreamer {
         match startup_result {
             Ok(Ok(())) => {}
             Ok(Err(e)) => {
-                let _ = capturer.stop().await;
-                *self.capturer.write().await = None;
-                *self.encoder.lock().await = None;
-                let _ = self.state.send(AudioStreamState::Error);
+                self.cleanup_failed_start(&capturer).await;
                 return Err(e);
             }
             Err(_) => {
-                let _ = capturer.stop().await;
-                *self.capturer.write().await = None;
-                *self.encoder.lock().await = None;
-                let _ = self.state.send(AudioStreamState::Error);
+                self.cleanup_failed_start(&capturer).await;
                 return Err(AppError::AudioError(
                     "Timed out waiting for audio capture to start".to_string(),
                 ));
@@ -205,22 +205,27 @@ impl AudioStreamer {
         let opus_subscribers = self.opus_subscribers.clone();
         let state = self.state.clone();
         let stop_flag = self.stop_flag.clone();
+        let shutdown_rx = self.shutdown_generation.subscribe();
+        let _ = self.state.send(AudioStreamState::Running);
 
-        tokio::spawn(async move {
+        let task = tokio::spawn(async move {
             Self::stream_task(
                 capturer_for_task,
                 encoder,
                 opus_subscribers,
                 state,
                 stop_flag,
+                shutdown_rx,
             )
             .await;
         });
+        *self.stream_task.lock().await = Some(task);
 
         Ok(())
     }
 
     pub async fn stop(&self) -> Result<()> {
+        let _lifecycle = self.lifecycle.lock().await;
         if self.state() == AudioStreamState::Stopped {
             return Ok(());
         }
@@ -228,10 +233,16 @@ impl AudioStreamer {
         info!("Stopping audio stream");
 
         self.stop_flag.store(true, Ordering::SeqCst);
+        self.shutdown_generation.send_modify(|generation| {
+            *generation = generation.wrapping_add(1);
+        });
 
         if let Some(ref capturer) = *self.capturer.read().await {
             capturer.stop().await?;
         }
+        if let Some(task) = self.stream_task.lock().await.take() {
+            let _ = task.await;
+        }
 
         *self.capturer.write().await = None;
         *self.encoder.lock().await = None;
@@ -242,28 +253,26 @@ impl AudioStreamer {
         Ok(())
     }
 
+    async fn cleanup_failed_start(&self, capturer: &AudioCapturer) {
+        let _ = capturer.stop().await;
+        *self.capturer.write().await = None;
+        *self.encoder.lock().await = None;
+        let _ = self.state.send(AudioStreamState::Error);
+    }
+
     pub fn is_running(&self) -> bool {
         self.state() == AudioStreamState::Running
     }
 
-    async fn fanout_opus(
+    fn fanout_opus(
         subscribers: &Arc<Mutex<Vec<mpsc::Sender<Arc<OpusFrame>>>>>,
         frame: Arc<OpusFrame>,
     ) {
-        let txs: Vec<_> = {
-            let g = subscribers.lock().unwrap();
-            if g.is_empty() {
-                return;
-            }
-            g.clone()
-        };
-        for tx in &txs {
-            let _ = tx.send(frame.clone()).await;
-        }
-        if txs.iter().any(|tx| tx.is_closed()) {
-            let mut g = subscribers.lock().unwrap();
-            g.retain(|tx| !tx.is_closed());
-        }
+        let mut subscribers = subscribers.lock().unwrap();
+        subscribers.retain(|subscriber| match subscriber.try_send(frame.clone()) {
+            Ok(()) | Err(mpsc::error::TrySendError::Full(_)) => true,
+            Err(mpsc::error::TrySendError::Closed(_)) => false,
+        });
     }
 
     async fn stream_task(
@@ -272,9 +281,9 @@ impl AudioStreamer {
         opus_subscribers: Arc<Mutex<Vec<mpsc::Sender<Arc<OpusFrame>>>>>,
         state: watch::Sender<AudioStreamState>,
         stop_flag: Arc<AtomicBool>,
+        mut shutdown_rx: watch::Receiver<u64>,
     ) {
         let mut pcm_rx = capturer.subscribe();
-        let _ = state.send(AudioStreamState::Running);
 
         debug!("Audio stream task started (48 kHz stereo → Opus, mpsc fan-out)");
 
@@ -291,8 +300,19 @@ impl AudioStreamer {
                 break;
             }
 
-            let recv_result =
-                tokio::time::timeout(std::time::Duration::from_secs(2), pcm_rx.recv()).await;
+            let recv_result = tokio::select! {
+                biased;
+                changed = shutdown_rx.changed() => {
+                    if changed.is_ok() || stop_flag.load(Ordering::Relaxed) {
+                        break;
+                    }
+                    continue;
+                }
+                result = tokio::time::timeout(
+                    std::time::Duration::from_secs(2),
+                    pcm_rx.recv(),
+                ) => result,
+            };
 
             match recv_result {
                 Ok(Ok(audio_frame)) => {
@@ -316,23 +336,17 @@ impl AudioStreamer {
                     }
 
                     while pending.len() >= OPUS_STEREO_SAMPLES {
-                        let pcm_20ms = Bytes::copy_from_slice(bytemuck::cast_slice(
-                            &pending[..OPUS_STEREO_SAMPLES],
-                        ));
-                        pending.drain(..OPUS_STEREO_SAMPLES);
-
-                        let frame_48k = AudioFrame::new_interleaved(pcm_20ms, 2, 48_000, 0);
-
                         let opus_result = {
                             let mut enc_guard = encoder.lock().await;
                             (*enc_guard)
                                 .as_mut()
-                                .map(|enc| enc.encode_frame(&frame_48k))
+                                .map(|enc| enc.encode(&pending[..OPUS_STEREO_SAMPLES]))
                         };
+                        pending.drain(..OPUS_STEREO_SAMPLES);
 
                         match opus_result {
                             Some(Ok(opus_frame)) => {
-                                Self::fanout_opus(&opus_subscribers, Arc::new(opus_frame)).await;
+                                Self::fanout_opus(&opus_subscribers, Arc::new(opus_frame));
                             }
                             Some(Err(e)) => {
                                 error!("Opus encode error: {}", e);
@@ -365,6 +379,7 @@ impl AudioStreamer {
             let _ = state.send(AudioStreamState::Stopped);
         } else {
             opus_subscribers.lock().unwrap().clear();
+            let _ = capturer.stop().await;
         }
         info!("Audio stream task ended");
     }
@@ -379,6 +394,7 @@ impl Default for AudioStreamer {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use bytes::Bytes;
 
     #[test]
     fn test_streamer_config_default() {
@@ -398,4 +414,42 @@ mod tests {
         let streamer = AudioStreamer::new();
         assert_eq!(streamer.state(), AudioStreamState::Stopped);
     }
+
+    #[test]
+    fn slow_subscriber_does_not_block_or_grow_unbounded() {
+        let streamer = AudioStreamer::new();
+        let mut receiver = streamer.subscribe_opus();
+        for sequence in 0..20 {
+            AudioStreamer::fanout_opus(
+                &streamer.opus_subscribers,
+                Arc::new(OpusFrame {
+                    data: Bytes::from_static(&[1]),
+                    duration_ms: 20,
+                    sequence,
+                }),
+            );
+        }
+
+        let mut received = 0;
+        while receiver.try_recv().is_ok() {
+            received += 1;
+        }
+        assert_eq!(received, 4);
+    }
+
+    #[test]
+    fn closed_subscriber_is_pruned() {
+        let streamer = AudioStreamer::new();
+        let receiver = streamer.subscribe_opus();
+        drop(receiver);
+        AudioStreamer::fanout_opus(
+            &streamer.opus_subscribers,
+            Arc::new(OpusFrame {
+                data: Bytes::from_static(&[1]),
+                duration_ms: 20,
+                sequence: 0,
+            }),
+        );
+        assert_eq!(streamer.subscriber_count(), 0);
+    }
 }

src/audio/uac/decoder.rs

@@ -0,0 +1,59 @@
+use audiopus::coder::Decoder;
+use audiopus::{Channels, SampleRate};
+
+use crate::error::{AppError, Result};
+
+const CHANNELS: usize = 2;
+const MAX_PACKET_BYTES: usize = 1275;
+const MAX_SAMPLES_PER_CHANNEL: usize = 5760;
+
+pub struct UacOpusDecoder {
+    decoder: Decoder,
+    buffer: Vec<i16>,
+}
+
+impl UacOpusDecoder {
+    pub fn new() -> Result<Self> {
+        let decoder = Decoder::new(SampleRate::Hz48000, Channels::Stereo)
+            .map_err(|error| AppError::AudioError(format!("Opus decoder init failed: {error}")))?;
+        Ok(Self {
+            decoder,
+            buffer: vec![0; MAX_SAMPLES_PER_CHANNEL * CHANNELS],
+        })
+    }
+
+    pub fn decode(&mut self, packet: &[u8]) -> Result<&[i16]> {
+        if packet.is_empty() || packet.len() > MAX_PACKET_BYTES {
+            return Err(AppError::BadRequest(format!(
+                "invalid Opus packet length {}",
+                packet.len()
+            )));
+        }
+
+        let frames = self
+            .decoder
+            .decode(Some(packet), &mut self.buffer, false)
+            .map_err(|error| AppError::AudioError(format!("Opus decode failed: {error}")))?;
+        Ok(&self.buffer[..frames * CHANNELS])
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use audiopus::coder::Encoder;
+    use audiopus::Application;
+
+    #[test]
+    fn decode_preserves_all_stereo_samples() {
+        let encoder =
+            Encoder::new(SampleRate::Hz48000, Channels::Stereo, Application::Audio).unwrap();
+        let pcm = vec![0i16; 960 * CHANNELS];
+        let mut packet = vec![0u8; MAX_PACKET_BYTES];
+        let packet_len = encoder.encode(&pcm, &mut packet).unwrap();
+
+        let mut decoder = UacOpusDecoder::new().unwrap();
+        let decoded = decoder.decode(&packet[..packet_len]).unwrap();
+        assert_eq!(decoded.len(), pcm.len());
+    }
+}

src/audio/uac/mod.rs

@@ -0,0 +1,9 @@
+//! Browser-to-USB microphone audio pipeline.
+
+mod decoder;
+mod playback;
+mod protocol;
+
+pub use decoder::UacOpusDecoder;
+pub use playback::{UacPlayback, UacPlaybackConfig, UacPlaybackState, UacSession};
+pub use protocol::{parse_audio_packet, UacAudioPacket};

src/audio/uac/playback.rs

@@ -0,0 +1,655 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use alsa::pcm::{Access, Format, Frames, HwParams, State};
+use alsa::{Direction, ValueOr, PCM};
+use tracing::{info, warn};
+
+use crate::error::{AppError, Result};
+
+const RETRY_BACKOFF: Duration = Duration::from_secs(1);
+const PERIOD_FRAMES: Frames = 1_024;
+// Request the same compatibility buffer as the known-working ALSA player.
+// The gadget driver may negotiate a smaller buffer; always use its result.
+const BUFFER_FRAMES: Frames = 32_768;
+const IDLE_REOPEN_TIMEOUT: Duration = Duration::from_secs(5);
+const SINK_STALL_TIMEOUT: Duration = Duration::from_millis(200);
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UacPlaybackState {
+    Idle,
+    Waiting,
+    Active,
+    Stalled,
+}
+
+impl UacPlaybackState {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Idle => "idle",
+            Self::Waiting => "waiting",
+            Self::Active => "active",
+            Self::Stalled => "stalled",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UacPlaybackConfig {
+    pub device_name: String,
+    pub sample_rate: u32,
+    pub channels: u16,
+}
+
+impl Default for UacPlaybackConfig {
+    fn default() -> Self {
+        Self {
+            device_name: crate::otg::uac::find_uac_pcm_device()
+                .unwrap_or_else(crate::otg::uac::uac_pcm_device),
+            sample_rate: 48_000,
+            channels: 2,
+        }
+    }
+}
+
+struct PlaybackInner {
+    config: UacPlaybackConfig,
+    stopped: AtomicBool,
+    active_session: Mutex<Option<Arc<Mutex<SessionRuntime>>>>,
+}
+
+enum SessionSink {
+    Closed {
+        retry_at: Option<Instant>,
+    },
+    Probing {
+        pcm: PlaybackPcm,
+        stalled: bool,
+    },
+    Active {
+        pcm: PlaybackPcm,
+        last_progress: Instant,
+    },
+}
+
+impl SessionSink {
+    fn state(&self) -> UacPlaybackState {
+        match self {
+            Self::Closed { retry_at: None } => UacPlaybackState::Waiting,
+            Self::Closed { retry_at: Some(_) } => UacPlaybackState::Stalled,
+            Self::Probing { stalled: false, .. } => UacPlaybackState::Waiting,
+            Self::Probing { stalled: true, .. } => UacPlaybackState::Stalled,
+            Self::Active { .. } => UacPlaybackState::Active,
+        }
+    }
+}
+
+struct SessionRuntime {
+    sink: SessionSink,
+    last_frame: Option<Instant>,
+}
+
+impl SessionRuntime {
+    fn new() -> Self {
+        Self {
+            sink: SessionSink::Closed { retry_at: None },
+            last_frame: None,
+        }
+    }
+
+    fn state(&self) -> UacPlaybackState {
+        self.sink.state()
+    }
+
+    fn close(&mut self) {
+        self.sink = SessionSink::Closed { retry_at: None };
+        self.last_frame = None;
+    }
+
+    /// Advance playback only when a WebSocket frame arrives. All ALSA handles
+    /// are non-blocking, so a slow or absent USB host drops the current frame
+    /// instead of occupying a worker thread or accumulating stale speech.
+    fn write(&mut self, config: &UacPlaybackConfig, samples: &[i16]) -> bool {
+        // Reopen on resume without an idle timer thread. stop()/session drop
+        // still close the PCM synchronously, even when no frames arrive.
+        if self
+            .last_frame
+            .is_some_and(|last| last.elapsed() >= IDLE_REOPEN_TIMEOUT)
+        {
+            self.close();
+        }
+        self.last_frame = Some(Instant::now());
+        let sink = std::mem::replace(&mut self.sink, SessionSink::Closed { retry_at: None });
+        let (next_sink, accepted) = drive_sink(sink, config, samples);
+        self.sink = next_sink;
+        accepted
+    }
+}
+
+#[derive(Clone)]
+pub struct UacPlayback {
+    inner: Arc<PlaybackInner>,
+}
+
+pub struct UacSession {
+    playback: UacPlayback,
+    runtime: Arc<Mutex<SessionRuntime>>,
+}
+
+impl UacPlayback {
+    pub fn start(config: UacPlaybackConfig) -> Result<Self> {
+        if config.sample_rate != 48_000 || config.channels != 2 {
+            return Err(AppError::BadRequest(
+                "UAC playback supports only 48000 Hz stereo".to_string(),
+            ));
+        }
+
+        Ok(Self {
+            inner: Arc::new(PlaybackInner {
+                config,
+                stopped: AtomicBool::new(false),
+                active_session: Mutex::new(None),
+            }),
+        })
+    }
+
+    pub fn acquire_session(&self) -> Result<UacSession> {
+        let mut active = self.inner.active_session.lock().unwrap();
+        if self.inner.stopped.load(Ordering::Acquire) {
+            return Err(AppError::ServiceUnavailable(
+                "UAC playback is stopping".to_string(),
+            ));
+        }
+        if active.is_some() {
+            return Err(AppError::ServiceUnavailable(
+                "another UAC microphone session is already active".to_string(),
+            ));
+        }
+
+        let runtime = Arc::new(Mutex::new(SessionRuntime::new()));
+        *active = Some(Arc::clone(&runtime));
+        Ok(UacSession {
+            playback: self.clone(),
+            runtime,
+        })
+    }
+
+    /// Stop accepting frames and synchronously close an active ALSA handle.
+    /// This guarantees configfs may rebuild the UAC function after this call.
+    pub fn stop(&self) {
+        if self.inner.stopped.swap(true, Ordering::AcqRel) {
+            return;
+        }
+        let runtime = self.inner.active_session.lock().unwrap().take();
+        if let Some(runtime) = runtime {
+            runtime.lock().unwrap().close();
+        }
+    }
+}
+
+impl UacSession {
+    pub fn state(&self) -> UacPlaybackState {
+        self.runtime.lock().unwrap().state()
+    }
+
+    /// Returns whether the frame was accepted and the resulting target state.
+    pub fn try_write(&self, pcm: &[i16]) -> Result<(bool, UacPlaybackState)> {
+        let channels = self.playback.inner.config.channels as usize;
+        if pcm.is_empty() || !pcm.len().is_multiple_of(channels) {
+            return Err(AppError::BadRequest(
+                "UAC PCM must contain complete stereo frames".to_string(),
+            ));
+        }
+        if self.playback.inner.stopped.load(Ordering::Acquire) {
+            return Err(AppError::ServiceUnavailable(
+                "UAC playback has stopped".to_string(),
+            ));
+        }
+
+        let mut runtime = self.runtime.lock().unwrap();
+        if self.playback.inner.stopped.load(Ordering::Acquire) {
+            runtime.close();
+            return Err(AppError::ServiceUnavailable(
+                "UAC playback has stopped".to_string(),
+            ));
+        }
+        let accepted = runtime.write(&self.playback.inner.config, pcm);
+        Ok((accepted, runtime.state()))
+    }
+}
+
+impl Drop for UacSession {
+    fn drop(&mut self) {
+        let mut active = self.playback.inner.active_session.lock().unwrap();
+        if active
+            .as_ref()
+            .is_some_and(|session| Arc::ptr_eq(session, &self.runtime))
+        {
+            *active = None;
+        }
+        drop(active);
+        self.runtime.lock().unwrap().close();
+    }
+}
+
+fn drive_sink(
+    sink: SessionSink,
+    config: &UacPlaybackConfig,
+    samples: &[i16],
+) -> (SessionSink, bool) {
+    match sink {
+        SessionSink::Closed { retry_at } => {
+            if retry_at.is_some_and(|deadline| Instant::now() < deadline) {
+                return (SessionSink::Closed { retry_at }, false);
+            }
+
+            match open_pcm(config).and_then(|mut pcm| {
+                pcm.prime_with_silence(config.channels as usize)?;
+                Ok(pcm)
+            }) {
+                Ok(pcm) => drive_probe(pcm, false, config, samples),
+                Err(error) => {
+                    warn!("Failed to open UAC playback device; retrying later: {error}");
+                    (
+                        SessionSink::Closed {
+                            retry_at: Some(Instant::now() + RETRY_BACKOFF),
+                        },
+                        false,
+                    )
+                }
+            }
+        }
+        SessionSink::Probing { pcm, stalled } => drive_probe(pcm, stalled, config, samples),
+        SessionSink::Active { pcm, last_progress } => {
+            drive_active(pcm, last_progress, config, samples)
+        }
+    }
+}
+
+fn drive_probe(
+    mut pcm: PlaybackPcm,
+    stalled: bool,
+    config: &UacPlaybackConfig,
+    samples: &[i16],
+) -> (SessionSink, bool) {
+    match pcm.consumption_progress() {
+        Ok(false) => (SessionSink::Probing { pcm, stalled }, false),
+        Ok(true) => {
+            // Keep the stream that has just started consuming. Dropping and
+            // preparing it here creates another startup/underrun window.
+            info!("UAC target started consuming microphone audio");
+            drive_active(pcm, Instant::now(), config, samples)
+        }
+        Err(error) => recover_sink(pcm, config, error),
+    }
+}
+
+fn drive_active(
+    mut pcm: PlaybackPcm,
+    last_progress: Instant,
+    config: &UacPlaybackConfig,
+    samples: &[i16],
+) -> (SessionSink, bool) {
+    let last_progress = match pcm.consumption_progress() {
+        Ok(true) => Instant::now(),
+        Ok(false) => last_progress,
+        Err(error) => return recover_sink(pcm, config, error),
+    };
+    if last_progress.elapsed() >= SINK_STALL_TIMEOUT {
+        // Discard queued speech before probing an unavailable host again.
+        if let Err(error) = pcm.reset_and_prime(config.channels as usize) {
+            warn!("Failed to reset stalled UAC playback: {error}");
+            return retry_later();
+        }
+        info!("UAC target stopped consuming audio; waiting for playback activity");
+        return (SessionSink::Probing { pcm, stalled: true }, false);
+    }
+
+    match pcm.write_samples(samples, config.channels as usize) {
+        Ok(accepted) => (SessionSink::Active { pcm, last_progress }, accepted),
+        Err(error) => recover_sink(pcm, config, error),
+    }
+}
+
+fn recover_sink(
+    mut pcm: PlaybackPcm,
+    config: &UacPlaybackConfig,
+    error: alsa::Error,
+) -> (SessionSink, bool) {
+    match error.errno() {
+        libc::EAGAIN | libc::EINTR => (SessionSink::Probing { pcm, stalled: true }, false),
+        libc::EPIPE | libc::ESTRPIPE => {
+            // prepare restarts after XRUN/suspend without snd_pcm_recover's
+            // potentially unbounded resume loop. Start again with silence,
+            // and require fresh consumption before reporting Active.
+            match pcm.reset_and_prime(config.channels as usize) {
+                Ok(()) => (SessionSink::Probing { pcm, stalled: true }, false),
+                Err(error) => {
+                    warn!("Failed to recover UAC playback: {error}");
+                    retry_later()
+                }
+            }
+        }
+        _ => {
+            warn!("UAC playback failed; reopening later: {error}");
+            retry_later()
+        }
+    }
+}
+
+fn retry_later() -> (SessionSink, bool) {
+    (
+        SessionSink::Closed {
+            retry_at: Some(Instant::now() + RETRY_BACKOFF),
+        },
+        false,
+    )
+}
+
+fn open_pcm(config: &UacPlaybackConfig) -> Result<PlaybackPcm> {
+    let pcm = PCM::new(&config.device_name, Direction::Playback, true).map_err(|error| {
+        AppError::AudioError(format!(
+            "Failed to open UAC device {}: {error}",
+            config.device_name
+        ))
+    })?;
+    {
+        let params = HwParams::any(&pcm)
+            .map_err(|error| AppError::AudioError(format!("UAC HwParams failed: {error}")))?;
+        params
+            .set_channels(config.channels as u32)
+            .and_then(|_| params.set_rate(config.sample_rate, ValueOr::Nearest))
+            .and_then(|_| params.set_format(Format::s16()))
+            .and_then(|_| params.set_access(Access::RWInterleaved))
+            .and_then(|_| params.set_period_size_near(PERIOD_FRAMES, ValueOr::Nearest))
+            .and_then(|_| params.set_buffer_size_near(BUFFER_FRAMES))
+            .and_then(|_| pcm.hw_params(&params))
+            .map_err(|error| {
+                AppError::AudioError(format!("Failed to configure UAC playback: {error}"))
+            })?;
+    }
+
+    let (buffer_frames, period_frames) = pcm.get_params().map_err(|error| {
+        AppError::AudioError(format!("Failed to read UAC PCM parameters: {error}"))
+    })?;
+    {
+        let params = pcm.sw_params_current().map_err(|error| {
+            AppError::AudioError(format!("Failed to read UAC SwParams: {error}"))
+        })?;
+        params
+            .set_start_threshold(buffer_frames as Frames)
+            .and_then(|_| params.set_stop_threshold(buffer_frames as Frames))
+            .and_then(|_| params.set_avail_min(period_frames as Frames))
+            .and_then(|_| pcm.sw_params(&params))
+            .map_err(|error| {
+                AppError::AudioError(format!("Failed to configure UAC SwParams: {error}"))
+            })?;
+    }
+    pcm.prepare().map_err(|error| {
+        AppError::AudioError(format!("Failed to prepare UAC playback: {error}"))
+    })?;
+    info!(
+        "UAC playback opened on {} (buffer={} frames, period={} frames)",
+        config.device_name, buffer_frames, period_frames
+    );
+    Ok(PlaybackPcm {
+        pcm,
+        buffer_frames: buffer_frames as Frames,
+        period_frames: period_frames as Frames,
+        submitted_frames: 0,
+        consumed_frames: 0,
+    })
+}
+
+struct PlaybackPcm {
+    pcm: PCM,
+    buffer_frames: Frames,
+    period_frames: Frames,
+    submitted_frames: u64,
+    consumed_frames: u64,
+}
+
+impl PlaybackPcm {
+    fn consumption_progress(&mut self) -> std::result::Result<bool, alsa::Error> {
+        // avail synchronizes the hardware pointer. Successful writes alone
+        // only show that the ring buffer has room, not that USB is consuming.
+        let available = self.pcm.avail()?;
+        match self.pcm.state() {
+            State::XRun => return Err(alsa::Error::new("UAC PCM state", libc::EPIPE)),
+            State::Suspended => return Err(alsa::Error::new("UAC PCM state", libc::ESTRPIPE)),
+            State::Disconnected => return Err(alsa::Error::new("UAC PCM state", libc::ENODEV)),
+            State::Running => {}
+            _ => return Ok(false),
+        }
+        let consumed = consumed_frames(self.submitted_frames, self.buffer_frames, available);
+        let progressed = consumed > self.consumed_frames;
+        self.consumed_frames = consumed;
+        Ok(progressed)
+    }
+
+    fn write_samples(
+        &mut self,
+        samples: &[i16],
+        channels: usize,
+    ) -> std::result::Result<bool, alsa::Error> {
+        let io = self.pcm.io_i16()?;
+        let written = write_frames(samples, channels, self.period_frames as usize, |chunk| {
+            let written = io.writei(chunk)?;
+            self.submitted_frames += written as u64;
+            Ok(written)
+        })?;
+        Ok(written == samples.len() / channels)
+    }
+
+    fn prime_with_silence(&mut self, channels: usize) -> Result<()> {
+        // Use the negotiated capacity, not BUFFER_FRAMES. A near request is
+        // often clamped by u_audio's DMA buffer limit.
+        let silence = vec![0i16; self.buffer_frames as usize * channels];
+        let complete = self
+            .write_samples(&silence, channels)
+            .map_err(|error| AppError::AudioError(format!("Failed to prime UAC PCM: {error}")))?;
+        if !complete {
+            return Err(AppError::AudioError(
+                "UAC PCM priming was interrupted".into(),
+            ));
+        }
+        // Most hardware starts automatically at the threshold. Some PCM
+        // plugins remain Prepared despite accepting the complete prefill.
+        // Start explicitly only after priming, and never restart a running PCM.
+        if self.pcm.state() == State::Prepared {
+            self.pcm.start().map_err(|error| {
+                AppError::AudioError(format!("Failed to start primed UAC PCM: {error}"))
+            })?;
+        }
+        Ok(())
+    }
+
+    fn reset_and_prime(&mut self, channels: usize) -> Result<()> {
+        self.pcm
+            .drop()
+            .and_then(|_| self.pcm.prepare())
+            .map_err(|error| AppError::AudioError(format!("Failed to reset UAC PCM: {error}")))?;
+        self.submitted_frames = 0;
+        self.consumed_frames = 0;
+        self.prime_with_silence(channels)
+    }
+}
+
+fn consumed_frames(submitted: u64, buffer: Frames, available: Frames) -> u64 {
+    let queued = (buffer - available.clamp(0, buffer)) as u64;
+    submitted.saturating_sub(queued)
+}
+
+/// Bound each write to one negotiated period and advance by actual frames,
+/// including short writes. Never wait for space or retain stale audio.
+fn write_frames(
+    samples: &[i16],
+    channels: usize,
+    period_frames: usize,
+    mut write: impl FnMut(&[i16]) -> std::result::Result<usize, alsa::Error>,
+) -> std::result::Result<usize, alsa::Error> {
+    let total_frames = samples.len() / channels;
+    let mut offset = 0;
+    while offset < total_frames {
+        let end = (offset + period_frames).min(total_frames);
+        match write(&samples[offset * channels..end * channels]) {
+            Ok(0) => break,
+            Ok(written) => offset += written,
+            Err(error) if matches!(error.errno(), libc::EAGAIN | libc::EINTR) => break,
+            Err(error) => return Err(error),
+        }
+    }
+    Ok(offset)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn writes_short_frames_without_skipping_stereo_samples() {
+        let samples: Vec<i16> = (0..24).collect();
+        let mut received = Vec::new();
+        let written = write_frames(&samples, 2, 4, |chunk| {
+            assert!(chunk.len() <= 8);
+            // Simulate a device accepting only one frame per write.
+            received.extend_from_slice(&chunk[..2]);
+            Ok(1)
+        })
+        .unwrap();
+        assert_eq!(written, 12);
+        assert_eq!(received, samples);
+    }
+
+    #[test]
+    fn full_device_stops_writing_without_waiting_or_claiming_whole_packet() {
+        let mut calls = 0;
+        let written = write_frames(&[0; 24], 2, 4, |_| {
+            calls += 1;
+            if calls == 1 {
+                Ok(2)
+            } else {
+                Err(alsa::Error::new("test write", libc::EAGAIN))
+            }
+        })
+        .unwrap();
+        assert_eq!(written, 2);
+        assert_eq!(calls, 2);
+    }
+
+    #[test]
+    fn writing_into_free_space_is_not_host_consumption() {
+        // A partially filled or full buffer can exist without any USB I/O.
+        assert_eq!(consumed_frames(1024, 4096, 3072), 0);
+        assert_eq!(consumed_frames(4096, 4096, 0), 0);
+        // Consuming a period, followed by filling it again, preserves progress.
+        assert_eq!(consumed_frames(4096, 4096, 1024), 1024);
+        assert_eq!(consumed_frames(5120, 4096, 0), 1024);
+    }
+
+    fn null_config() -> UacPlaybackConfig {
+        UacPlaybackConfig {
+            device_name: "null".into(),
+            sample_rate: 48_000,
+            channels: 2,
+        }
+    }
+
+    #[test]
+    fn native_pcm_uses_negotiated_start_threshold_and_recovers_to_probing() {
+        // ALSA's null plugin exercises real libasound configuration and I/O
+        // without requiring a USB controller. It cannot verify DWC3 behavior.
+        let config = null_config();
+        let mut pcm = open_pcm(&config).unwrap();
+        assert_eq!(
+            pcm.pcm
+                .sw_params_current()
+                .unwrap()
+                .get_start_threshold()
+                .unwrap(),
+            pcm.buffer_frames
+        );
+        pcm.prime_with_silence(2).unwrap();
+        assert!(pcm.consumption_progress().unwrap());
+        let (sink, accepted) =
+            recover_sink(pcm, &config, alsa::Error::new("test xrun", libc::EPIPE));
+        assert!(!accepted);
+        assert!(matches!(sink, SessionSink::Probing { stalled: true, .. }));
+    }
+
+    #[test]
+    fn stop_closes_an_open_native_pcm_before_returning() {
+        let playback = UacPlayback::start(null_config()).unwrap();
+        let session = playback.acquire_session().unwrap();
+        session.try_write(&[0; 2048]).unwrap();
+        assert!(!matches!(
+            session.runtime.lock().unwrap().sink,
+            SessionSink::Closed { .. }
+        ));
+        playback.stop();
+        assert!(matches!(
+            session.runtime.lock().unwrap().sink,
+            SessionSink::Closed { retry_at: None }
+        ));
+    }
+
+    #[test]
+    fn idle_resume_reopens_instead_of_reusing_previous_sink() {
+        let config = null_config();
+        let mut runtime = SessionRuntime::new();
+        runtime.sink = SessionSink::Closed {
+            retry_at: Some(Instant::now() + Duration::from_secs(60)),
+        };
+        runtime.last_frame = Some(Instant::now() - IDLE_REOPEN_TIMEOUT);
+        runtime.write(&config, &[0; 2048]);
+        assert!(!matches!(runtime.sink, SessionSink::Closed { .. }));
+    }
+
+    #[test]
+    fn permits_only_one_microphone_session() {
+        let playback = UacPlayback::start(UacPlaybackConfig::default()).unwrap();
+        let first = playback.acquire_session().unwrap();
+        assert_eq!(first.state(), UacPlaybackState::Waiting);
+        assert!(playback.acquire_session().is_err());
+
+        drop(first);
+        assert!(playback.acquire_session().is_ok());
+        playback.stop();
+    }
+
+    #[test]
+    fn stop_rejects_new_and_existing_session_writes() {
+        let playback = UacPlayback::start(UacPlaybackConfig::default()).unwrap();
+        let session = playback.acquire_session().unwrap();
+
+        playback.stop();
+
+        assert!(session.try_write(&[0, 0]).is_err());
+        assert!(playback.acquire_session().is_err());
+    }
+
+    #[test]
+    fn rejects_incomplete_stereo_frames_before_opening_alsa() {
+        let playback = UacPlayback::start(UacPlaybackConfig::default()).unwrap();
+        let session = playback.acquire_session().unwrap();
+
+        assert!(session.try_write(&[0]).is_err());
+        assert_eq!(session.state(), UacPlaybackState::Waiting);
+    }
+
+    #[test]
+    fn closed_sink_state_reflects_retry_backoff() {
+        assert_eq!(
+            SessionSink::Closed { retry_at: None }.state(),
+            UacPlaybackState::Waiting
+        );
+        assert_eq!(
+            SessionSink::Closed {
+                retry_at: Some(Instant::now())
+            }
+            .state(),
+            UacPlaybackState::Stalled
+        );
+    }
+}

src/audio/uac/protocol.rs

@@ -0,0 +1,98 @@
+use crate::error::{AppError, Result};
+
+const HEADER_SIZE: usize = 15;
+const OPUS_MESSAGE: u8 = 0x03;
+const PCM_MESSAGE: u8 = 0x04;
+const CHANNELS: usize = 2;
+const MAX_PCM_SAMPLES: usize = 5760 * CHANNELS;
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum UacAudioPacket<'a> {
+    Opus(&'a [u8]),
+    Pcm(&'a [u8]),
+}
+
+impl UacAudioPacket<'_> {
+    pub fn pcm_samples(&self) -> Result<Vec<i16>> {
+        let Self::Pcm(bytes) = self else {
+            return Err(AppError::BadRequest("packet is not raw PCM".to_string()));
+        };
+        if bytes.is_empty() || bytes.len() % (CHANNELS * 2) != 0 {
+            return Err(AppError::BadRequest(format!(
+                "invalid stereo PCM byte length {}",
+                bytes.len()
+            )));
+        }
+        if bytes.len() / 2 > MAX_PCM_SAMPLES {
+            return Err(AppError::BadRequest("PCM frame exceeds 120 ms".to_string()));
+        }
+
+        Ok(bytes
+            .chunks_exact(2)
+            .map(|sample| i16::from_le_bytes([sample[0], sample[1]]))
+            .collect())
+    }
+}
+
+pub fn parse_audio_packet(data: &[u8]) -> Result<UacAudioPacket<'_>> {
+    if data.len() < HEADER_SIZE {
+        return Err(AppError::BadRequest(
+            "UAC frame is shorter than its header".to_string(),
+        ));
+    }
+
+    let payload_len = u32::from_le_bytes([data[11], data[12], data[13], data[14]]) as usize;
+    let expected_len = HEADER_SIZE
+        .checked_add(payload_len)
+        .ok_or_else(|| AppError::BadRequest("UAC payload length overflow".to_string()))?;
+    if data.len() != expected_len {
+        return Err(AppError::BadRequest(
+            "UAC payload length does not match its header".to_string(),
+        ));
+    }
+
+    let payload = &data[HEADER_SIZE..];
+    match data[0] {
+        OPUS_MESSAGE => Ok(UacAudioPacket::Opus(payload)),
+        PCM_MESSAGE => Ok(UacAudioPacket::Pcm(payload)),
+        message_type => Err(AppError::BadRequest(format!(
+            "unsupported UAC message type 0x{message_type:02x}"
+        ))),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn message(message_type: u8, payload: &[u8]) -> Vec<u8> {
+        let mut data = vec![0; HEADER_SIZE + payload.len()];
+        data[0] = message_type;
+        data[11..15].copy_from_slice(&(payload.len() as u32).to_le_bytes());
+        data[HEADER_SIZE..].copy_from_slice(payload);
+        data
+    }
+
+    #[test]
+    fn requires_exact_payload_length() {
+        let valid = message(OPUS_MESSAGE, &[1, 2, 3]);
+        assert_eq!(
+            parse_audio_packet(&valid).unwrap(),
+            UacAudioPacket::Opus(&[1, 2, 3])
+        );
+
+        let mut trailing = valid.clone();
+        trailing.push(4);
+        assert!(parse_audio_packet(&trailing).is_err());
+        assert!(parse_audio_packet(&valid[..valid.len() - 1]).is_err());
+    }
+
+    #[test]
+    fn converts_little_endian_stereo_pcm() {
+        let data = message(PCM_MESSAGE, &[1, 0, 255, 255]);
+        assert_eq!(
+            parse_audio_packet(&data).unwrap().pcm_samples().unwrap(),
+            vec![1, -1]
+        );
+    }
+}

src/auth/middleware.rs

@@ -71,6 +71,7 @@ pub async fn auth_middleware(
 fn unauthorized_response(message: &str) -> Response {
     let body = ErrorResponse {
         success: false,
+        code: None,
         message: message.to_string(),
     };
     (StatusCode::UNAUTHORIZED, Json(body)).into_response()
@@ -92,6 +93,12 @@ fn is_public_endpoint(path: &str) -> bool {
 fn is_setup_public_endpoint(path: &str) -> bool {
     matches!(
         path,
-        "/setup" | "/setup/init" | "/devices" | "/stream/codecs"
+        "/setup"
+            | "/setup/init"
+            | "/devices"
+            | "/hid/bluetooth/adapters"
+            | "/video/input-status"
+            | "/stream/codecs"
+            | "/video/codecs"
     )
 }

src/auth/two_factor.rs

@@ -227,15 +227,14 @@ impl TwoFactorService {
             return Err(AppError::AuthError("Invalid TOTP code".to_string()));
         }
 
-        let mut transaction = self.pool.begin().await?;
         let result =
             sqlx::query("INSERT INTO user_totp_credentials (user_id, secret) VALUES (?1, ?2)")
                 .bind(user_id)
                 .bind(secret.to_string())
-                .execute(&mut *transaction)
+                .execute(&self.pool)
                 .await;
         match result {
-            Ok(_) => transaction.commit().await?,
+            Ok(_) => {}
             Err(sqlx::Error::Database(error)) if error.is_unique_violation() => {
                 return Err(AppError::Conflict("TOTP is already enabled".to_string()));
             }

src/auth/user.rs

@@ -1,7 +1,5 @@
 use serde::{Deserialize, Serialize};
 use sqlx::{Pool, Sqlite};
-use time::format_description::well_known::Rfc3339;
-use time::OffsetDateTime;
 use uuid::Uuid;
 
 use super::password::{hash_password, verify_password};
@@ -112,15 +110,13 @@ impl UserStore {
         }
 
         let password_hash = hash_password(new_password)?;
-        let now = OffsetDateTime::now_utc();
-
-        let result =
-            sqlx::query("UPDATE users SET password_hash = ?1, updated_at = ?2 WHERE id = ?3")
-                .bind(&password_hash)
-                .bind(now.format(&Rfc3339).expect("RFC3339 format"))
-                .bind(user_id)
-                .execute(&self.pool)
-                .await?;
+        let result = sqlx::query(
+            "UPDATE users SET password_hash = ?1, updated_at = datetime('now') WHERE id = ?2",
+        )
+        .bind(&password_hash)
+        .bind(user_id)
+        .execute(&self.pool)
+        .await?;
 
         if result.rows_affected() == 0 {
             return Err(AppError::NotFound("User not found".to_string()));
@@ -143,13 +139,13 @@ impl UserStore {
             return Ok(());
         }
 
-        let now = OffsetDateTime::now_utc();
-        let result = sqlx::query("UPDATE users SET username = ?1, updated_at = ?2 WHERE id = ?3")
-            .bind(new_username)
-            .bind(now.format(&Rfc3339).expect("RFC3339 format"))
-            .bind(user_id)
-            .execute(&self.pool)
-            .await?;
+        let result = sqlx::query(
+            "UPDATE users SET username = ?1, updated_at = datetime('now') WHERE id = ?2",
+        )
+        .bind(new_username)
+        .bind(user_id)
+        .execute(&self.pool)
+        .await?;
 
         if result.rows_affected() == 0 {
             return Err(AppError::NotFound("User not found".to_string()));

src/config/schema/hid.rs

@@ -1,6 +1,54 @@
 use serde::{Deserialize, Serialize};
 use typeshare::typeshare;
 
+#[typeshare]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(default)]
+pub struct BluetoothHidConfig {
+    pub adapter: String,
+    pub name: String,
+    pub peer: Option<String>,
+}
+impl Default for BluetoothHidConfig {
+    fn default() -> Self {
+        Self {
+            adapter: "hci0".into(),
+            name: "One-KVM HID".into(),
+            peer: None,
+        }
+    }
+}
+impl BluetoothHidConfig {
+    pub fn validate(&self) -> crate::error::Result<()> {
+        let invalid = |reason: &str| crate::error::AppError::BadRequest(reason.into());
+        if !self
+            .adapter
+            .strip_prefix("hci")
+            .is_some_and(|s| !s.is_empty() && s.bytes().all(|c| c.is_ascii_digit()))
+        {
+            return Err(invalid(
+                "Bluetooth adapter must be hci followed by an index",
+            ));
+        }
+        if self.name.is_empty() || self.name.len() > 64 || self.name.chars().any(char::is_control) {
+            return Err(invalid(
+                "Bluetooth name must contain 1–64 UTF-8 bytes without control characters",
+            ));
+        }
+        if let Some(peer) = &self.peer {
+            let parts: Vec<_> = peer.split(':').collect();
+            if parts.len() != 6
+                || parts
+                    .iter()
+                    .any(|p| p.len() != 2 || !p.bytes().all(|c| c.is_ascii_hexdigit()))
+            {
+                return Err(invalid("Invalid Bluetooth peer address"));
+            }
+        }
+        Ok(())
+    }
+}
+
 #[typeshare]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "lowercase")]
@@ -8,6 +56,7 @@ use typeshare::typeshare;
 pub enum HidBackend {
     Otg,
     Ch9329,
+    Bluetooth,
     #[default]
     None,
 }
@@ -166,6 +215,7 @@ impl OtgHidProfile {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(default)]
 pub struct HidConfig {
+    pub bluetooth: BluetoothHidConfig,
     pub backend: HidBackend,
     pub otg_udc: Option<String>,
     #[serde(default)]
@@ -181,6 +231,9 @@ pub struct HidConfig {
     #[serde(default)]
     pub ch9329_hybrid_mouse: bool,
     #[serde(default)]
+    #[serde(alias = "ch9329_macos_drag")]
+    pub mouse_macos_drag: bool,
+    #[serde(default)]
     pub ch9329_descriptor: Ch9329DescriptorConfig,
     pub mouse_absolute: bool,
 }
@@ -189,6 +242,7 @@ impl Default for HidConfig {
     fn default() -> Self {
         Self {
             backend: HidBackend::None,
+            bluetooth: BluetoothHidConfig::default(),
             otg_udc: None,
             otg_descriptor: OtgDescriptorConfig::default(),
             otg_profile: OtgHidProfile::default(),
@@ -197,6 +251,7 @@ impl Default for HidConfig {
             ch9329_port: "/dev/ttyUSB0".to_string(),
             ch9329_baudrate: 9600,
             ch9329_hybrid_mouse: false,
+            mouse_macos_drag: false,
             ch9329_descriptor: Ch9329DescriptorConfig::default(),
             mouse_absolute: true,
         }
@@ -222,6 +277,11 @@ impl HidConfig {
         }
 
         let functions = self.effective_otg_functions();
+        if self.mouse_macos_drag && (!functions.mouse_relative || !functions.mouse_absolute) {
+            return Err(crate::error::AppError::BadRequest(
+                "macOS drag compatibility requires both OTG mouse interfaces".to_string(),
+            ));
+        }
         if functions.is_empty() {
             return Err(crate::error::AppError::BadRequest(
                 "OTG HID functions cannot be empty".to_string(),
@@ -252,3 +312,65 @@ impl HidConfig {
             })
     }
 }
+
+#[cfg(test)]
+mod bluetooth_tests {
+    use super::*;
+    #[test]
+    fn mouse_compatibility_defaults_alias_and_otg_validation() {
+        let defaults: HidConfig = serde_json::from_str(r#"{"backend":"otg"}"#).unwrap();
+        assert!(!defaults.mouse_macos_drag);
+        let mut config: HidConfig =
+            serde_json::from_str(r#"{"backend":"otg","ch9329_macos_drag":true}"#).unwrap();
+        assert!(config.mouse_macos_drag);
+        assert!(config.validate_otg_functions().is_ok());
+        config.otg_profile = OtgHidProfile::LegacyMouseRelative;
+        assert!(config.validate_otg_functions().is_err());
+        config.backend = HidBackend::Ch9329;
+        assert!(config.validate_otg_functions().is_ok());
+        let saved = serde_json::to_value(&config).unwrap();
+        assert_eq!(saved["mouse_macos_drag"], true);
+        assert!(saved.get("ch9329_macos_drag").is_none());
+    }
+    #[test]
+    fn old_configs_keep_bluetooth_disabled_and_get_defaults() {
+        let config: HidConfig = serde_json::from_str(r#"{"backend":"otg"}"#).unwrap();
+        assert_eq!(config.backend, HidBackend::Otg);
+        assert_eq!(config.bluetooth, BluetoothHidConfig::default());
+    }
+    #[test]
+    fn obsolete_ble_flag_is_ignored_and_not_saved() {
+        let config: BluetoothHidConfig =
+            serde_json::from_str(r#"{"adapter":"hci0","name":"My keyboard","le_only":true}"#)
+                .unwrap();
+        config.validate().unwrap();
+        assert!(serde_json::to_value(config)
+            .unwrap()
+            .get("le_only")
+            .is_none());
+    }
+    #[test]
+    fn bluetooth_uses_relative_mouse_and_existing_usb_constraints() {
+        let mut config = crate::config::AppConfig::default();
+        config.hid.backend = HidBackend::Bluetooth;
+        config.hid.mouse_absolute = true;
+        config.msd.enabled = true;
+        config.uac.enabled = true;
+        config.otg_network.enabled = true;
+        config.enforce_invariants();
+        assert!(!config.hid.mouse_absolute);
+        assert!(!config.msd.enabled && !config.uac.enabled && !config.otg_network.enabled);
+    }
+    #[test]
+    fn reject_invalid_adapter_address_and_oversize_advertisement_name() {
+        let mut config = BluetoothHidConfig::default();
+        config.adapter = "/dev/hci0".into();
+        assert!(config.validate().is_err());
+        config.adapter = "hci0".into();
+        config.peer = Some("not-a-mac".into());
+        assert!(config.validate().is_err());
+        config.peer = None;
+        config.name = "蓝".repeat(24);
+        assert!(config.validate().is_err());
+    }
+}

src/config/schema/mod.rs

@@ -10,6 +10,7 @@ mod computer_use;
 mod hid;
 mod otg_network;
 mod stream;
+mod uac;
 mod watchdog;
 mod web;
 
@@ -19,6 +20,7 @@ pub use computer_use::*;
 pub use hid::*;
 pub use otg_network::*;
 pub use stream::*;
+pub use uac::*;
 pub use watchdog::*;
 pub use web::*;
 
@@ -44,6 +46,7 @@ pub struct AppConfig {
     pub rtsp: RtspConfig,
     pub redfish: RedfishConfig,
     pub watchdog: WatchdogConfig,
+    pub uac: UacConfig,
 }
 
 impl AppConfig {
@@ -51,6 +54,10 @@ impl AppConfig {
         if self.hid.backend != HidBackend::Otg {
             self.msd.enabled = false;
             self.otg_network.enabled = false;
+            self.uac.enabled = false;
+        }
+        if self.hid.backend == HidBackend::Bluetooth {
+            self.hid.mouse_absolute = false;
         }
         self.atx.normalize();
     }

src/config/schema/stream.rs

@@ -102,6 +102,7 @@ pub enum EncoderType {
     Qsv,
     Amf,
     Rkmpp,
+    #[serde(alias = "amlogic")]
     V4l2m2m,
 }
 

src/config/schema/uac.rs

@@ -0,0 +1,78 @@
+use serde::{Deserialize, Serialize};
+use typeshare::typeshare;
+
+use crate::error::{AppError, Result};
+
+/// Configuration for the USB Audio Class microphone gadget.
+#[typeshare]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct UacConfig {
+    pub enabled: bool,
+    pub sample_rate: u32,
+    pub channels: u8,
+}
+
+impl Default for UacConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            sample_rate: 48_000,
+            channels: 2,
+        }
+    }
+}
+
+impl UacConfig {
+    pub fn validate(&self) -> Result<()> {
+        // Older configurations stored zero-valued placeholders while UAC was
+        // disabled. Accept them until the feature is enabled and normalized.
+        if !self.enabled {
+            return Ok(());
+        }
+        if self.sample_rate != 48_000 {
+            return Err(AppError::BadRequest(format!(
+                "unsupported UAC sample rate {} (expected 48000)",
+                self.sample_rate
+            )));
+        }
+        if self.channels != 2 {
+            return Err(AppError::BadRequest(format!(
+                "unsupported UAC channel count {} (expected 2)",
+                self.channels
+            )));
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn defaults_match_the_audio_transport() {
+        let config = UacConfig::default();
+        assert_eq!(config.sample_rate, 48_000);
+        assert_eq!(config.channels, 2);
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn rejects_formats_the_transport_cannot_convert() {
+        assert!(UacConfig {
+            enabled: true,
+            sample_rate: 44_100,
+            ..Default::default()
+        }
+        .validate()
+        .is_err());
+        assert!(UacConfig {
+            enabled: true,
+            channels: 1,
+            ..Default::default()
+        }
+        .validate()
+        .is_err());
+    }
+}

src/config/schema/web.rs

@@ -44,23 +44,56 @@ impl Default for VideoConfig {
 }
 
 #[typeshare]
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(default)]
 pub struct MsdConfig {
     pub enabled: bool,
     pub msd_dir: String,
+    pub flash_inquiry_string: String,
+    pub cdrom_inquiry_string: String,
 }
 
+pub const DEFAULT_FLASH_INQUIRY_STRING: &str = "One-KVM Virtual Flash";
+pub const DEFAULT_CDROM_INQUIRY_STRING: &str = "One-KVM Virtual CD-ROM";
+pub const MAX_INQUIRY_STRING_BYTES: usize = 28;
+
 impl Default for MsdConfig {
     fn default() -> Self {
         Self {
             enabled: true,
             msd_dir: String::new(),
+            flash_inquiry_string: DEFAULT_FLASH_INQUIRY_STRING.to_string(),
+            cdrom_inquiry_string: DEFAULT_CDROM_INQUIRY_STRING.to_string(),
         }
     }
 }
 
 impl MsdConfig {
+    pub fn validate(&self) -> crate::error::Result<()> {
+        Self::validate_inquiry_string("Flash", &self.flash_inquiry_string)?;
+        Self::validate_inquiry_string("CD-ROM", &self.cdrom_inquiry_string)
+    }
+
+    pub fn validate_inquiry_string(kind: &str, value: &str) -> crate::error::Result<()> {
+        let value = value.trim();
+        if value.is_empty() {
+            return Err(crate::error::AppError::BadRequest(format!(
+                "MSD {kind} inquiry string cannot be empty"
+            )));
+        }
+        if value.len() > MAX_INQUIRY_STRING_BYTES {
+            return Err(crate::error::AppError::BadRequest(format!(
+                "MSD {kind} inquiry string must be at most {MAX_INQUIRY_STRING_BYTES} bytes"
+            )));
+        }
+        if !value.bytes().all(|byte| (0x20..=0x7e).contains(&byte)) {
+            return Err(crate::error::AppError::BadRequest(format!(
+                "MSD {kind} inquiry string must contain printable ASCII characters only"
+            )));
+        }
+        Ok(())
+    }
+
     pub fn msd_dir_path(&self) -> std::path::PathBuf {
         std::path::PathBuf::from(&self.msd_dir)
     }
@@ -123,3 +156,18 @@ impl Default for WebConfig {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn msd_inquiry_strings_default_and_validate() {
+        assert!(MsdConfig::default().validate().is_ok());
+        assert!(MsdConfig::validate_inquiry_string("Flash", "  Custom Drive  ").is_ok());
+        assert!(MsdConfig::validate_inquiry_string("Flash", "").is_err());
+        assert!(MsdConfig::validate_inquiry_string("Flash", &"x".repeat(29)).is_err());
+        assert!(MsdConfig::validate_inquiry_string("CD-ROM", "虚拟光驱").is_err());
+        assert!(MsdConfig::validate_inquiry_string("CD-ROM", "bad\tname").is_err());
+    }
+}

src/config/store.rs

@@ -17,13 +17,13 @@ pub struct ConfigStore {
 }
 
 impl ConfigStore {
-    pub fn new(pool: Pool<Sqlite>) -> Result<Self> {
-        Ok(Self {
+    pub fn new(pool: Pool<Sqlite>) -> Self {
+        Self {
             pool,
             cache: Arc::new(ArcSwap::from_pointee(AppConfig::default())),
             change_tx: broadcast::channel(16).0,
             write_lock: Arc::new(Mutex::new(())),
-        })
+        }
     }
 
     pub async fn load(&self) -> Result<()> {
@@ -83,6 +83,11 @@ impl ConfigStore {
         Ok(())
     }
 
+    #[cfg(target_os = "linux")]
+    pub fn hid_bonds(&self) -> crate::db::hid_bonds::HidBondStore {
+        crate::db::hid_bonds::HidBondStore(self.pool.clone())
+    }
+
     pub fn get(&self) -> Arc<AppConfig> {
         self.cache.load_full()
     }
@@ -145,7 +150,7 @@ mod tests {
         let db = DatabasePool::new(&db_path).await.unwrap();
         db.init_schema().await.unwrap();
 
-        let store = ConfigStore::new(db.clone_pool()).unwrap();
+        let store = ConfigStore::new(db.clone_pool());
         store.load().await.unwrap();
 
         let config = store.get();
@@ -163,7 +168,7 @@ mod tests {
         assert!(config.initialized);
         assert_eq!(config.web.http_port, 9000);
 
-        let store2 = ConfigStore::new(db.clone_pool()).unwrap();
+        let store2 = ConfigStore::new(db.clone_pool());
         store2.load().await.unwrap();
         let config = store2.get();
         assert!(config.initialized);
@@ -176,7 +181,7 @@ mod tests {
         let db_path = dir.path().join("test.db");
         let db = DatabasePool::new(&db_path).await.unwrap();
         db.init_schema().await.unwrap();
-        let store = ConfigStore::new(db.clone_pool()).unwrap();
+        let store = ConfigStore::new(db.clone_pool());
         store.load().await.unwrap();
 
         sqlx::query("DROP TABLE config")
@@ -210,7 +215,7 @@ mod tests {
             .await
             .unwrap();
 
-        let store = ConfigStore::new(db.clone_pool()).unwrap();
+        let store = ConfigStore::new(db.clone_pool());
         store.load().await.unwrap();
         let (persisted,): (String,) =
             sqlx::query_as("SELECT value FROM config WHERE key = 'app_config'")

src/db/hid_bonds.rs

@@ -0,0 +1,80 @@
+use one_kvm_bluetooth_hid::bonds::{Bond, BondStore, Operation};
+use sqlx::{Pool, Sqlite};
+
+#[derive(Clone)]
+pub struct HidBondStore(pub Pool<Sqlite>);
+impl BondStore for HidBondStore {
+    fn list(&self) -> Operation<'_, Vec<Bond>> {
+        Box::pin(async move {
+            let rows: Vec<(String, String, bool)> = sqlx::query_as(
+                "SELECT adapter, peer, pending FROM hid_bonds ORDER BY adapter, peer",
+            )
+            .fetch_all(&self.0)
+            .await
+            .map_err(|e| e.to_string())?;
+            Ok(rows
+                .into_iter()
+                .map(|(adapter, peer, pending)| Bond {
+                    adapter,
+                    peer,
+                    pending,
+                })
+                .collect())
+        })
+    }
+    fn save(&self, bond: Bond) -> Operation<'_, ()> {
+        Box::pin(async move {
+            sqlx::query("INSERT INTO hid_bonds(adapter, peer, pending) VALUES (?, ?, ?) ON CONFLICT(adapter, peer) DO UPDATE SET pending = MAX(pending, excluded.pending)")
+                .bind(bond.adapter.to_ascii_uppercase()).bind(bond.peer.to_ascii_uppercase()).bind(bond.pending)
+                .execute(&self.0).await.map_err(|e| e.to_string())?;
+            Ok(())
+        })
+    }
+    fn remove(&self, bond: Bond) -> Operation<'_, ()> {
+        Box::pin(async move {
+            sqlx::query("DELETE FROM hid_bonds WHERE adapter = ? AND peer = ?")
+                .bind(bond.adapter)
+                .bind(bond.peer)
+                .execute(&self.0)
+                .await
+                .map_err(|e| e.to_string())?;
+            Ok(())
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[tokio::test]
+    async fn ownership_and_pending_cleanup_survive_reopen() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = super::super::open_database_pool(dir.path()).await.unwrap();
+        let store = HidBondStore(db.clone_pool());
+        let bond = Bond {
+            adapter: "AA:BB:CC:DD:EE:FF".into(),
+            peer: "11:22:33:44:55:66".into(),
+            pending: false,
+        };
+        store.save(bond.clone()).await.unwrap();
+        store
+            .save(Bond {
+                pending: true,
+                ..bond.clone()
+            })
+            .await
+            .unwrap();
+        store.save(bond.clone()).await.unwrap(); // Late status cannot undo a pending reset.
+        let reopened = super::super::open_database_pool(dir.path()).await.unwrap();
+        let records = HidBondStore(reopened.clone_pool()).list().await.unwrap();
+        assert_eq!(
+            records,
+            vec![Bond {
+                pending: true,
+                ..bond.clone()
+            }]
+        );
+        store.remove(bond).await.unwrap();
+        assert!(store.list().await.unwrap().is_empty());
+    }
+}

src/db/mod.rs

@@ -1,3 +1,40 @@
+#[cfg(target_os = "linux")]
+pub mod hid_bonds;
 mod pool;
+mod wol_history;
+
+use std::path::Path;
+
+use crate::error::Result;
 
 pub use pool::DatabasePool;
+pub use wol_history::WolHistoryStore;
+
+/// Open the application database stored in `data_dir` and ensure its schema exists.
+pub async fn open_database_pool(data_dir: &Path) -> Result<DatabasePool> {
+    let db = DatabasePool::new(&data_dir.join("one-kvm.db")).await?;
+    db.init_schema().await?;
+    Ok(db)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn open_database_pool_creates_data_dir_and_initializes_schema() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let data_dir = temp_dir.path().join("nested").join("data");
+
+        let db = open_database_pool(&data_dir).await.unwrap();
+
+        assert!(data_dir.join("one-kvm.db").is_file());
+        let users_table: Option<String> = sqlx::query_scalar(
+            "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'users'",
+        )
+        .fetch_optional(db.pool())
+        .await
+        .unwrap();
+        assert_eq!(users_table.as_deref(), Some("users"));
+    }
+}

src/db/pool.rs

@@ -1,4 +1,7 @@
-use sqlx::{sqlite::SqlitePoolOptions, Pool, Sqlite};
+use sqlx::{
+    sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions, SqliteSynchronous},
+    Pool, Sqlite,
+};
 use std::path::Path;
 use std::time::Duration;
 
@@ -15,114 +18,62 @@ impl DatabasePool {
             tokio::fs::create_dir_all(parent).await?;
         }
 
-        let db_url = format!("sqlite:{}?mode=rwc", db_path.display());
+        let options = SqliteConnectOptions::new()
+            .filename(db_path)
+            .create_if_missing(true)
+            .foreign_keys(true)
+            .journal_mode(SqliteJournalMode::Wal)
+            .synchronous(SqliteSynchronous::Full)
+            .busy_timeout(Duration::from_secs(5));
 
         let pool = SqlitePoolOptions::new()
             .max_connections(4)
             .acquire_timeout(Duration::from_secs(5))
             .idle_timeout(Duration::from_secs(300))
-            .connect(&db_url)
+            .connect_with(options)
             .await?;
 
         Ok(Self { pool })
     }
 
     pub async fn init_schema(&self) -> Result<()> {
-        self.create_config_table().await?;
-        self.create_users_table().await?;
-        self.create_user_totp_credentials_table().await?;
-        self.create_api_tokens_table().await?;
-        self.create_wol_history_table().await?;
-        Ok(())
-    }
-
-    async fn create_config_table(&self) -> Result<()> {
+        // Keep migrations embedded in the binary so deployments do not need an
+        // extra migrations directory or another runtime dependency.
+        let mut transaction = self.pool.begin().await?;
         sqlx::query(
             r#"
-            CREATE TABLE IF NOT EXISTS config (
-                key TEXT PRIMARY KEY,
-                value TEXT NOT NULL,
-                updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+            CREATE TABLE IF NOT EXISTS schema_migrations (
+                version INTEGER PRIMARY KEY,
+                applied_at TEXT NOT NULL DEFAULT (datetime('now'))
             )
             "#,
         )
-        .execute(&self.pool)
-        .await?;
-        Ok(())
-    }
-
-    async fn create_users_table(&self) -> Result<()> {
-        sqlx::query(
-            r#"
-            CREATE TABLE IF NOT EXISTS users (
-                id TEXT PRIMARY KEY,
-                username TEXT NOT NULL UNIQUE,
-                password_hash TEXT NOT NULL,
-                created_at TEXT NOT NULL DEFAULT (datetime('now')),
-                updated_at TEXT NOT NULL DEFAULT (datetime('now'))
-            )
-            "#,
-        )
-        .execute(&self.pool)
-        .await?;
-        Ok(())
-    }
-
-    async fn create_api_tokens_table(&self) -> Result<()> {
-        sqlx::query(
-            r#"
-            CREATE TABLE IF NOT EXISTS api_tokens (
-                id TEXT PRIMARY KEY,
-                name TEXT NOT NULL,
-                token_hash TEXT NOT NULL,
-                permissions TEXT NOT NULL,
-                expires_at TEXT,
-                created_at TEXT NOT NULL DEFAULT (datetime('now')),
-                last_used TEXT
-            )
-            "#,
-        )
-        .execute(&self.pool)
-        .await?;
-        Ok(())
-    }
-
-    async fn create_user_totp_credentials_table(&self) -> Result<()> {
-        sqlx::query(
-            r#"
-            CREATE TABLE IF NOT EXISTS user_totp_credentials (
-                user_id TEXT PRIMARY KEY,
-                secret TEXT NOT NULL,
-                created_at TEXT NOT NULL DEFAULT (datetime('now')),
-                FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-            )
-            "#,
-        )
-        .execute(&self.pool)
-        .await?;
-        Ok(())
-    }
-
-    async fn create_wol_history_table(&self) -> Result<()> {
-        sqlx::query(
-            r#"
-            CREATE TABLE IF NOT EXISTS wol_history (
-                mac_address TEXT PRIMARY KEY,
-                updated_at INTEGER NOT NULL
-            )
-            "#,
-        )
-        .execute(&self.pool)
+        .execute(&mut *transaction)
         .await?;
 
-        sqlx::query(
-            r#"
-            CREATE INDEX IF NOT EXISTS idx_wol_history_updated_at
-            ON wol_history(updated_at DESC)
-            "#,
-        )
-        .execute(&self.pool)
-        .await?;
+        let current_version: i64 =
+            sqlx::query_scalar("SELECT COALESCE(MAX(version), 0) FROM schema_migrations")
+                .fetch_one(&mut *transaction)
+                .await?;
+
+        for (version, statements) in SCHEMA_MIGRATIONS
+            .iter()
+            .enumerate()
+            .map(|(index, statements)| ((index + 1) as i64, *statements))
+        {
+            if version <= current_version {
+                continue;
+            }
+            for &statement in statements {
+                sqlx::query(statement).execute(&mut *transaction).await?;
+            }
+            sqlx::query("INSERT INTO schema_migrations (version) VALUES (?1)")
+                .bind(version)
+                .execute(&mut *transaction)
+                .await?;
+        }
+
+        transaction.commit().await?;
         Ok(())
     }
 
@@ -133,4 +84,65 @@ impl DatabasePool {
     pub fn clone_pool(&self) -> Pool<Sqlite> {
         self.pool.clone()
     }
+
+    pub fn wol_history(&self) -> super::WolHistoryStore {
+        super::WolHistoryStore::new(self.pool.clone())
+    }
 }
+
+// Each item is one version; statements within a version run atomically.
+// New schema changes should be appended as a new item, never edited in place.
+const SCHEMA_MIGRATIONS: &[&[&str]] = &[
+    &[
+        r#"
+    CREATE TABLE IF NOT EXISTS config (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+    "#,
+        r#"
+    CREATE TABLE IF NOT EXISTS users (
+        id TEXT PRIMARY KEY,
+        username TEXT NOT NULL UNIQUE,
+        password_hash TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+    "#,
+        r#"
+    CREATE TABLE IF NOT EXISTS user_totp_credentials (
+        user_id TEXT PRIMARY KEY,
+        secret TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    )
+    "#,
+        r#"
+    CREATE TABLE IF NOT EXISTS api_tokens (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        token_hash TEXT NOT NULL,
+        permissions TEXT NOT NULL,
+        expires_at TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_used TEXT
+    )
+    "#,
+        r#"
+    CREATE TABLE IF NOT EXISTS wol_history (
+        mac_address TEXT PRIMARY KEY,
+        updated_at INTEGER NOT NULL
+    )
+    "#,
+        r#"
+    CREATE INDEX IF NOT EXISTS idx_wol_history_updated_at
+    ON wol_history(updated_at DESC)
+    "#,
+    ],
+    &[r#"
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_users_singleton
+    ON users ((1))
+    "#],
+    &["CREATE TABLE hid_bonds (adapter TEXT NOT NULL, peer TEXT NOT NULL, pending INTEGER NOT NULL DEFAULT 0, PRIMARY KEY(adapter, peer))"],
+];

src/db/wol_history.rs

@@ -0,0 +1,39 @@
+use sqlx::{Pool, Sqlite};
+
+use crate::error::Result;
+
+const MAX_ENTRIES: i64 = 50;
+
+#[derive(Clone)]
+pub struct WolHistoryStore {
+    pool: Pool<Sqlite>,
+}
+
+impl WolHistoryStore {
+    pub(crate) fn new(pool: Pool<Sqlite>) -> Self {
+        Self { pool }
+    }
+
+    pub async fn record(&self, mac_address: &str) -> Result<()> {
+        let mut tx = self.pool.begin().await?;
+        sqlx::query("INSERT INTO wol_history (mac_address, updated_at) VALUES (?1, CAST(strftime('%s', 'now') AS INTEGER)) ON CONFLICT(mac_address) DO UPDATE SET updated_at = excluded.updated_at")
+            .bind(mac_address)
+            .execute(&mut *tx)
+            .await?;
+        sqlx::query("DELETE FROM wol_history WHERE mac_address NOT IN (SELECT mac_address FROM wol_history ORDER BY updated_at DESC LIMIT ?1)")
+            .bind(MAX_ENTRIES)
+            .execute(&mut *tx)
+            .await?;
+        tx.commit().await?;
+        Ok(())
+    }
+
+    pub async fn list(&self, limit: usize) -> Result<Vec<(String, i64)>> {
+        Ok(sqlx::query_as(
+            "SELECT mac_address, updated_at FROM wol_history ORDER BY updated_at DESC LIMIT ?1",
+        )
+        .bind(limit as i64)
+        .fetch_all(&self.pool)
+        .await?)
+    }
+}

src/error.rs

@@ -1,5 +1,238 @@
+use serde::Serialize;
+use std::fmt;
 use thiserror::Error;
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum MsdErrorCode {
+    MsdUnavailable,
+    MsdOperationInProgress,
+    MsdOperationFailed,
+    MsdInvalidRequest,
+    MsdResourceNotFound,
+    MsdResourceAlreadyExists,
+    MsdMediaSlotsFull,
+    MsdMediaAlreadyMounted,
+    MsdMediaInUse,
+    MsdImageTooLarge,
+    MsdInvalidUrl,
+    MsdRemoteDownloadFailed,
+    MsdDownloadIncomplete,
+    MsdDriveNotInitialized,
+    MsdDriveConnected,
+    MsdDriveFilesystemUnsupported,
+    MsdDriveSizeInvalid,
+    MsdStorageSpaceUnavailable,
+    MsdStorageFull,
+    MsdStorageReadOnly,
+    MsdStoragePermissionDenied,
+    MsdMediumRemovalPrevented,
+    MsdDisconnectFailed,
+}
+
+impl MsdErrorCode {
+    pub const ALL: [Self; 23] = [
+        Self::MsdUnavailable,
+        Self::MsdOperationInProgress,
+        Self::MsdOperationFailed,
+        Self::MsdInvalidRequest,
+        Self::MsdResourceNotFound,
+        Self::MsdResourceAlreadyExists,
+        Self::MsdMediaSlotsFull,
+        Self::MsdMediaAlreadyMounted,
+        Self::MsdMediaInUse,
+        Self::MsdImageTooLarge,
+        Self::MsdInvalidUrl,
+        Self::MsdRemoteDownloadFailed,
+        Self::MsdDownloadIncomplete,
+        Self::MsdDriveNotInitialized,
+        Self::MsdDriveConnected,
+        Self::MsdDriveFilesystemUnsupported,
+        Self::MsdDriveSizeInvalid,
+        Self::MsdStorageSpaceUnavailable,
+        Self::MsdStorageFull,
+        Self::MsdStorageReadOnly,
+        Self::MsdStoragePermissionDenied,
+        Self::MsdMediumRemovalPrevented,
+        Self::MsdDisconnectFailed,
+    ];
+
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::MsdUnavailable => "MSD_UNAVAILABLE",
+            Self::MsdOperationInProgress => "MSD_OPERATION_IN_PROGRESS",
+            Self::MsdOperationFailed => "MSD_OPERATION_FAILED",
+            Self::MsdInvalidRequest => "MSD_INVALID_REQUEST",
+            Self::MsdResourceNotFound => "MSD_RESOURCE_NOT_FOUND",
+            Self::MsdResourceAlreadyExists => "MSD_RESOURCE_ALREADY_EXISTS",
+            Self::MsdMediaSlotsFull => "MSD_MEDIA_SLOTS_FULL",
+            Self::MsdMediaAlreadyMounted => "MSD_MEDIA_ALREADY_MOUNTED",
+            Self::MsdMediaInUse => "MSD_MEDIA_IN_USE",
+            Self::MsdImageTooLarge => "MSD_IMAGE_TOO_LARGE",
+            Self::MsdInvalidUrl => "MSD_INVALID_URL",
+            Self::MsdRemoteDownloadFailed => "MSD_REMOTE_DOWNLOAD_FAILED",
+            Self::MsdDownloadIncomplete => "MSD_DOWNLOAD_INCOMPLETE",
+            Self::MsdDriveNotInitialized => "MSD_DRIVE_NOT_INITIALIZED",
+            Self::MsdDriveConnected => "MSD_DRIVE_CONNECTED",
+            Self::MsdDriveFilesystemUnsupported => "MSD_DRIVE_FILESYSTEM_UNSUPPORTED",
+            Self::MsdDriveSizeInvalid => "MSD_DRIVE_SIZE_INVALID",
+            Self::MsdStorageSpaceUnavailable => "MSD_STORAGE_SPACE_UNAVAILABLE",
+            Self::MsdStorageFull => "MSD_STORAGE_FULL",
+            Self::MsdStorageReadOnly => "MSD_STORAGE_READ_ONLY",
+            Self::MsdStoragePermissionDenied => "MSD_STORAGE_PERMISSION_DENIED",
+            Self::MsdMediumRemovalPrevented => "MSD_MEDIUM_REMOVAL_PREVENTED",
+            Self::MsdDisconnectFailed => "MSD_DISCONNECT_FAILED",
+        }
+    }
+
+    pub const fn message(self) -> &'static str {
+        match self {
+            Self::MsdUnavailable => "Virtual media service is unavailable.",
+            Self::MsdOperationInProgress => "Another virtual media operation is in progress.",
+            Self::MsdOperationFailed => "The virtual media operation failed.",
+            Self::MsdInvalidRequest => "The virtual media request is invalid.",
+            Self::MsdResourceNotFound => "The requested virtual media resource was not found.",
+            Self::MsdResourceAlreadyExists => "The virtual media resource already exists.",
+            Self::MsdMediaSlotsFull => "All virtual media slots are in use.",
+            Self::MsdMediaAlreadyMounted => "The virtual medium is already mounted.",
+            Self::MsdMediaInUse => "The virtual medium is currently in use.",
+            Self::MsdImageTooLarge => "The virtual media image is too large.",
+            Self::MsdInvalidUrl => "The download URL is invalid.",
+            Self::MsdRemoteDownloadFailed => "The remote image download failed.",
+            Self::MsdDownloadIncomplete => "The remote image download was incomplete.",
+            Self::MsdDriveNotInitialized => "The virtual drive is not initialized.",
+            Self::MsdDriveConnected => "The virtual drive is connected to the controlled computer.",
+            Self::MsdDriveFilesystemUnsupported => {
+                "Web file management does not support this virtual drive format."
+            }
+            Self::MsdDriveSizeInvalid => "The virtual drive size is invalid.",
+            Self::MsdStorageSpaceUnavailable => {
+                "Available virtual media storage space could not be determined."
+            }
+            Self::MsdStorageFull => "Virtual media storage does not have enough free space.",
+            Self::MsdStorageReadOnly => "Virtual media storage is read-only.",
+            Self::MsdStoragePermissionDenied => {
+                "Permission to access virtual media storage was denied."
+            }
+            Self::MsdMediumRemovalPrevented => {
+                "The controlled computer prevented removal of the virtual medium."
+            }
+            Self::MsdDisconnectFailed => "The virtual medium could not be disconnected.",
+        }
+    }
+
+    pub const fn redfish_key(self) -> &'static str {
+        match self {
+            Self::MsdUnavailable => "MsdUnavailable",
+            Self::MsdOperationInProgress => "MsdOperationInProgress",
+            Self::MsdOperationFailed => "MsdOperationFailed",
+            Self::MsdInvalidRequest => "MsdInvalidRequest",
+            Self::MsdResourceNotFound => "MsdResourceNotFound",
+            Self::MsdResourceAlreadyExists => "MsdResourceAlreadyExists",
+            Self::MsdMediaSlotsFull => "MsdMediaSlotsFull",
+            Self::MsdMediaAlreadyMounted => "MsdMediaAlreadyMounted",
+            Self::MsdMediaInUse => "MsdMediaInUse",
+            Self::MsdImageTooLarge => "MsdImageTooLarge",
+            Self::MsdInvalidUrl => "MsdInvalidUrl",
+            Self::MsdRemoteDownloadFailed => "MsdRemoteDownloadFailed",
+            Self::MsdDownloadIncomplete => "MsdDownloadIncomplete",
+            Self::MsdDriveNotInitialized => "MsdDriveNotInitialized",
+            Self::MsdDriveConnected => "MsdDriveConnected",
+            Self::MsdDriveFilesystemUnsupported => "MsdDriveFilesystemUnsupported",
+            Self::MsdDriveSizeInvalid => "MsdDriveSizeInvalid",
+            Self::MsdStorageSpaceUnavailable => "MsdStorageSpaceUnavailable",
+            Self::MsdStorageFull => "MsdStorageFull",
+            Self::MsdStorageReadOnly => "MsdStorageReadOnly",
+            Self::MsdStoragePermissionDenied => "MsdStoragePermissionDenied",
+            Self::MsdMediumRemovalPrevented => "MsdMediumRemovalPrevented",
+            Self::MsdDisconnectFailed => "MsdDisconnectFailed",
+        }
+    }
+
+    pub const fn severity(self) -> &'static str {
+        match self {
+            Self::MsdUnavailable | Self::MsdOperationFailed | Self::MsdDisconnectFailed => {
+                "Critical"
+            }
+            _ => "Warning",
+        }
+    }
+
+    pub const fn resolution(self) -> &'static str {
+        match self {
+            Self::MsdUnavailable => "Enable or restore the virtual media service, then retry.",
+            Self::MsdOperationInProgress => {
+                "Wait for the current virtual media operation to finish, then retry."
+            }
+            Self::MsdResourceNotFound | Self::MsdDriveNotInitialized => {
+                "Verify that the requested virtual media resource exists, then retry."
+            }
+            Self::MsdResourceAlreadyExists => {
+                "Use a different resource name or remove the existing resource, then retry."
+            }
+            Self::MsdMediaSlotsFull => "Eject an inserted virtual medium, then retry.",
+            Self::MsdMediaAlreadyMounted => {
+                "Eject the existing virtual medium before mounting it again."
+            }
+            Self::MsdMediaInUse | Self::MsdDriveConnected | Self::MsdMediumRemovalPrevented => {
+                "Eject or unmount the virtual medium on the controlled computer, then retry."
+            }
+            Self::MsdImageTooLarge | Self::MsdDriveSizeInvalid => {
+                "Use a supported image or virtual drive size, then retry."
+            }
+            Self::MsdInvalidUrl | Self::MsdInvalidRequest => "Correct the request and retry.",
+            Self::MsdRemoteDownloadFailed | Self::MsdDownloadIncomplete => {
+                "Verify the remote server and network connection, then retry."
+            }
+            Self::MsdDriveFilesystemUnsupported => {
+                "Mount the drive on the controlled computer, or use a supported format for web file management."
+            }
+            Self::MsdStorageSpaceUnavailable => {
+                "Verify that virtual media storage is available, then retry."
+            }
+            Self::MsdStorageFull => {
+                "Free space in virtual media storage or select a smaller image, then retry."
+            }
+            Self::MsdStorageReadOnly => "Make virtual media storage writable, then retry.",
+            Self::MsdStoragePermissionDenied => {
+                "Correct virtual media storage permissions, then retry."
+            }
+            Self::MsdOperationFailed | Self::MsdDisconnectFailed => {
+                "Retry the operation. If the problem persists, check the One-KVM system logs."
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MsdError {
+    code: MsdErrorCode,
+}
+
+impl MsdError {
+    pub const fn new(code: MsdErrorCode) -> Self {
+        Self { code }
+    }
+
+    pub const fn code(self) -> MsdErrorCode {
+        self.code
+    }
+}
+
+impl fmt::Display for MsdError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(self.code.message())
+    }
+}
+
+impl std::error::Error for MsdError {}
+
+impl From<MsdErrorCode> for AppError {
+    fn from(code: MsdErrorCode) -> Self {
+        Self::Msd(MsdError::new(code))
+    }
+}
+
 #[derive(Error, Debug)]
 pub enum AppError {
     #[error("Authentication failed: {0}")]
@@ -26,6 +259,9 @@ pub enum AppError {
     #[error("Internal error: {0}")]
     Internal(String),
 
+    #[error(transparent)]
+    Msd(#[from] MsdError),
+
     #[error("Configuration error: {0}")]
     Config(String),
 
@@ -66,3 +302,135 @@ impl From<sqlx::Error> for AppError {
         AppError::Persistence(err.to_string())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::MsdErrorCode::*;
+
+    #[test]
+    fn msd_codes_and_messages_are_stable() {
+        let cases = [
+            (
+                MsdUnavailable,
+                "MSD_UNAVAILABLE",
+                "Virtual media service is unavailable.",
+            ),
+            (
+                MsdOperationInProgress,
+                "MSD_OPERATION_IN_PROGRESS",
+                "Another virtual media operation is in progress.",
+            ),
+            (
+                MsdOperationFailed,
+                "MSD_OPERATION_FAILED",
+                "The virtual media operation failed.",
+            ),
+            (
+                MsdInvalidRequest,
+                "MSD_INVALID_REQUEST",
+                "The virtual media request is invalid.",
+            ),
+            (
+                MsdResourceNotFound,
+                "MSD_RESOURCE_NOT_FOUND",
+                "The requested virtual media resource was not found.",
+            ),
+            (
+                MsdResourceAlreadyExists,
+                "MSD_RESOURCE_ALREADY_EXISTS",
+                "The virtual media resource already exists.",
+            ),
+            (
+                MsdMediaSlotsFull,
+                "MSD_MEDIA_SLOTS_FULL",
+                "All virtual media slots are in use.",
+            ),
+            (
+                MsdMediaAlreadyMounted,
+                "MSD_MEDIA_ALREADY_MOUNTED",
+                "The virtual medium is already mounted.",
+            ),
+            (
+                MsdMediaInUse,
+                "MSD_MEDIA_IN_USE",
+                "The virtual medium is currently in use.",
+            ),
+            (
+                MsdImageTooLarge,
+                "MSD_IMAGE_TOO_LARGE",
+                "The virtual media image is too large.",
+            ),
+            (
+                MsdInvalidUrl,
+                "MSD_INVALID_URL",
+                "The download URL is invalid.",
+            ),
+            (
+                MsdRemoteDownloadFailed,
+                "MSD_REMOTE_DOWNLOAD_FAILED",
+                "The remote image download failed.",
+            ),
+            (
+                MsdDownloadIncomplete,
+                "MSD_DOWNLOAD_INCOMPLETE",
+                "The remote image download was incomplete.",
+            ),
+            (
+                MsdDriveNotInitialized,
+                "MSD_DRIVE_NOT_INITIALIZED",
+                "The virtual drive is not initialized.",
+            ),
+            (
+                MsdDriveConnected,
+                "MSD_DRIVE_CONNECTED",
+                "The virtual drive is connected to the controlled computer.",
+            ),
+            (
+                MsdDriveFilesystemUnsupported,
+                "MSD_DRIVE_FILESYSTEM_UNSUPPORTED",
+                "Web file management does not support this virtual drive format.",
+            ),
+            (
+                MsdDriveSizeInvalid,
+                "MSD_DRIVE_SIZE_INVALID",
+                "The virtual drive size is invalid.",
+            ),
+            (
+                MsdStorageSpaceUnavailable,
+                "MSD_STORAGE_SPACE_UNAVAILABLE",
+                "Available virtual media storage space could not be determined.",
+            ),
+            (
+                MsdStorageFull,
+                "MSD_STORAGE_FULL",
+                "Virtual media storage does not have enough free space.",
+            ),
+            (
+                MsdStorageReadOnly,
+                "MSD_STORAGE_READ_ONLY",
+                "Virtual media storage is read-only.",
+            ),
+            (
+                MsdStoragePermissionDenied,
+                "MSD_STORAGE_PERMISSION_DENIED",
+                "Permission to access virtual media storage was denied.",
+            ),
+            (
+                MsdMediumRemovalPrevented,
+                "MSD_MEDIUM_REMOVAL_PREVENTED",
+                "The controlled computer prevented removal of the virtual medium.",
+            ),
+            (
+                MsdDisconnectFailed,
+                "MSD_DISCONNECT_FAILED",
+                "The virtual medium could not be disconnected.",
+            ),
+        ];
+
+        assert_eq!(cases.len(), super::MsdErrorCode::ALL.len());
+        for (code, expected_code, expected_message) in cases {
+            assert_eq!(code.as_str(), expected_code);
+            assert_eq!(code.message(), expected_message);
+        }
+    }
+}

src/events/mod.rs

@@ -6,9 +6,10 @@ use self::types::EXACT_EVENT_TOPICS;
 
 pub use types::{
     AtxDeviceInfo, AudioDeviceInfo, ClientStats, HidDeviceInfo, LedState, MsdDeviceInfo,
-    MsdDeviceMediaInfo, StreamDeviceLostKind, SystemEvent, TtydDeviceInfo, VideoDeviceInfo,
+    MsdDeviceMediaInfo, StreamKind, SystemEvent, TtydDeviceInfo, VideoDeviceInfo,
 };
 
+use std::sync::RwLock;
 use tokio::sync::broadcast;
 
 const EVENT_CHANNEL_CAPACITY: usize = 256;
@@ -40,6 +41,7 @@ pub struct EventBus {
     exact_topics: std::collections::HashMap<&'static str, broadcast::Sender<SystemEvent>>,
     prefix_topics: std::collections::HashMap<String, broadcast::Sender<SystemEvent>>,
     device_info_dirty_tx: broadcast::Sender<()>,
+    latest_video_stream_state: RwLock<Option<SystemEvent>>,
 }
 
 impl EventBus {
@@ -60,12 +62,26 @@ impl EventBus {
             exact_topics,
             prefix_topics,
             device_info_dirty_tx,
+            latest_video_stream_state: RwLock::new(None),
         }
     }
 
     pub fn publish(&self, event: SystemEvent) {
         let event_name = event.event_name();
 
+        if matches!(
+            event,
+            SystemEvent::StreamStateChanged {
+                kind: StreamKind::Video,
+                ..
+            }
+        ) {
+            *self
+                .latest_video_stream_state
+                .write()
+                .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(event.clone());
+        }
+
         if let Some(tx) = self.exact_topics.get(event_name) {
             let _ = tx.send(event.clone());
         }
@@ -103,6 +119,15 @@ impl EventBus {
         self.device_info_dirty_tx.subscribe()
     }
 
+    /// Stateful video status topics replay this value to new WebSocket
+    /// subscribers so a page refresh cannot miss an earlier signal-loss edge.
+    pub fn latest_video_stream_state(&self) -> Option<SystemEvent> {
+        self.latest_video_stream_state
+            .read()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+            .clone()
+    }
+
     pub fn subscriber_count(&self) -> usize {
         self.tx.receiver_count()
     }
@@ -124,6 +149,7 @@ mod tests {
         let mut rx = bus.subscribe();
 
         bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
             state: "streaming".to_string(),
             device: Some("/dev/video0".to_string()),
             reason: None,
@@ -132,6 +158,10 @@ mod tests {
 
         let event = rx.recv().await.unwrap();
         assert!(matches!(event, SystemEvent::StreamStateChanged { .. }));
+        assert!(matches!(
+            bus.latest_video_stream_state(),
+            Some(SystemEvent::StreamStateChanged { state, .. }) if state == "streaming"
+        ));
     }
 
     #[tokio::test]
@@ -143,6 +173,7 @@ mod tests {
         assert_eq!(bus.subscriber_count(), 2);
 
         bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
             state: "ready".to_string(),
             device: Some("/dev/video0".to_string()),
             reason: None,
@@ -162,6 +193,7 @@ mod tests {
         let mut rx = bus.subscribe_topic("stream.state_changed").unwrap();
 
         bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
             state: "ready".to_string(),
             device: None,
             reason: None,
@@ -178,6 +210,7 @@ mod tests {
         let mut rx = bus.subscribe_topic("stream.*").unwrap();
 
         bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
             state: "ready".to_string(),
             device: None,
             reason: None,
@@ -200,10 +233,36 @@ mod tests {
         assert_eq!(bus.subscriber_count(), 0);
 
         bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
             state: "ready".to_string(),
             device: None,
             reason: None,
             next_retry_ms: None,
         });
     }
+
+    #[test]
+    fn audio_state_does_not_replace_latest_video_state() {
+        let bus = EventBus::new();
+        bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
+            state: "no_signal".to_string(),
+            device: Some("/dev/video0".to_string()),
+            reason: Some("no_sync".to_string()),
+            next_retry_ms: Some(500),
+        });
+        bus.publish(SystemEvent::StreamStateChanged {
+            kind: StreamKind::Audio,
+            state: "streaming".to_string(),
+            device: Some("hw:0,0".to_string()),
+            reason: None,
+            next_retry_ms: None,
+        });
+
+        assert!(matches!(
+            bus.latest_video_stream_state(),
+            Some(SystemEvent::StreamStateChanged { state, reason, .. })
+                if state == "no_signal" && reason.as_deref() == Some("no_sync")
+        ));
+    }
 }

src/events/types.rs

@@ -92,10 +92,10 @@ pub struct ClientStats {
     pub connected_secs: u64,
 }
 
-/// Video vs audio source for [`SystemEvent::StreamDeviceLost`] (WebSocket `stream.device_lost`).
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+/// Media subsystem that owns a stream state or device event.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
-pub enum StreamDeviceLostKind {
+pub enum StreamKind {
     Video,
     Audio,
 }
@@ -114,6 +114,7 @@ pub enum SystemEvent {
 
     #[serde(rename = "stream.state_changed")]
     StreamStateChanged {
+        kind: StreamKind,
         state: String,
         device: Option<String>,
         #[serde(skip_serializing_if = "Option::is_none")]
@@ -141,7 +142,7 @@ pub enum SystemEvent {
 
     #[serde(rename = "stream.device_lost")]
     StreamDeviceLost {
-        kind: StreamDeviceLostKind,
+        kind: StreamKind,
         device: String,
         reason: String,
     },
@@ -204,6 +205,8 @@ pub enum SystemEvent {
         total_bytes: Option<u64>,
         progress_pct: Option<f32>,
         status: String,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        error_code: Option<String>,
     },
 
     #[serde(rename = "system.device_info")]
@@ -272,6 +275,7 @@ mod tests {
     #[test]
     fn test_event_name() {
         let event = SystemEvent::StreamStateChanged {
+            kind: StreamKind::Video,
             state: "streaming".to_string(),
             device: Some("/dev/video0".to_string()),
             reason: None,
@@ -283,7 +287,7 @@ mod tests {
     #[test]
     fn stream_device_lost_json_snake_case_kind() {
         let event = SystemEvent::StreamDeviceLost {
-            kind: StreamDeviceLostKind::Audio,
+            kind: StreamKind::Audio,
             device: "hw:0,0".to_string(),
             reason: "test".to_string(),
         };
@@ -304,6 +308,7 @@ mod tests {
                 from_mode: String::new(),
             },
             SystemEvent::StreamStateChanged {
+                kind: StreamKind::Video,
                 state: String::new(),
                 device: None,
                 reason: None,
@@ -321,7 +326,7 @@ mod tests {
                 fps: 0,
             },
             SystemEvent::StreamDeviceLost {
-                kind: StreamDeviceLostKind::Video,
+                kind: StreamKind::Video,
                 device: String::new(),
                 reason: String::new(),
             },
@@ -372,6 +377,7 @@ mod tests {
                 total_bytes: None,
                 progress_pct: None,
                 status: String::new(),
+                error_code: None,
             },
             SystemEvent::DeviceInfo {
                 video: VideoDeviceInfo {

src/extensions/manager.rs

@@ -1,15 +1,15 @@
 use std::collections::{HashMap, VecDeque};
-use std::path::PathBuf;
+use std::path::Path;
 use std::process::Stdio;
 use std::sync::Arc;
 
-use tempfile::TempDir;
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tokio::process::{Child, Command};
 use tokio::sync::RwLock;
-use toml_edit::DocumentMut;
 
+use super::protected_config::ProtectedConfigFile;
 use super::types::*;
+use super::validation::{validate_easytier_config, validate_frpc_config, validate_gostc_config};
 use crate::events::EventBus;
 
 const LOG_BUFFER_SIZE: usize = 200;
@@ -27,12 +27,12 @@ const TTYD_TCP_PORT: &str = "7681";
 struct ExtensionProcess {
     child: Child,
     logs: Arc<RwLock<VecDeque<String>>>,
-    _temp_dir: Option<TempDir>,
+    _config_file: Option<ProtectedConfigFile>,
 }
 
 struct ExtensionLaunch {
     args: Vec<String>,
-    temp_dir: Option<TempDir>,
+    config_file: Option<ProtectedConfigFile>,
 }
 
 pub struct ExtensionManager {
@@ -83,24 +83,12 @@ impl ExtensionManager {
         match id {
             ExtensionId::Ttyd => config.ttyd.enabled,
             ExtensionId::Gostc => {
-                config.gostc.enabled
-                    && !config.gostc.key.is_empty()
-                    && !config.gostc.addr.trim().is_empty()
+                config.gostc.enabled && validate_gostc_config(&config.gostc).is_ok()
             }
             ExtensionId::Easytier => {
-                config.easytier.enabled && !config.easytier.network_name.is_empty()
-            }
-            ExtensionId::Frpc => {
-                config.frpc.enabled
-                    && match config.frpc.config_mode {
-                        FrpcConfigMode::Quick => {
-                            !config.frpc.proxy_name.trim().is_empty()
-                                && !config.frpc.server_addr.trim().is_empty()
-                                && !config.frpc.token.is_empty()
-                        }
-                        FrpcConfigMode::Full => !config.frpc.custom_toml.trim().is_empty(),
-                    }
+                config.easytier.enabled && validate_easytier_config(&config.easytier).is_ok()
             }
+            ExtensionId::Frpc => config.frpc.enabled && validate_frpc_config(&config.frpc).is_ok(),
         }
     }
 
@@ -203,7 +191,7 @@ impl ExtensionManager {
             ExtensionProcess {
                 child,
                 logs,
-                _temp_dir: launch.temp_dir,
+                _config_file: launch.config_file,
             },
         );
         drop(processes);
@@ -286,18 +274,10 @@ impl ExtensionManager {
 
             ExtensionId::Gostc => {
                 let c = &config.gostc;
-                if c.addr.trim().is_empty() {
-                    return Err("GOSTC server address is required".into());
-                }
-                if c.key.is_empty() {
-                    return Err("GOSTC client key is required".into());
-                }
+                validate_gostc_config(c)?;
 
-                let mut args = Vec::new();
-
-                if c.tls {
-                    args.push("--tls=true".to_string());
-                }
+                // gostc defaults to TLS, so disabling it must be explicit.
+                let mut args = vec![format!("--tls={}", c.tls)];
 
                 args.extend(["-addr".to_string(), c.addr.trim().to_string()]);
 
@@ -307,35 +287,7 @@ impl ExtensionManager {
             }
 
             ExtensionId::Easytier => {
-                let c = &config.easytier;
-                if c.network_name.is_empty() {
-                    return Err("EasyTier network name is required".into());
-                }
-
-                let mut args = vec![
-                    "--network-name".to_string(),
-                    c.network_name.clone(),
-                    "--network-secret".to_string(),
-                    c.network_secret.clone(),
-                ];
-
-                for peer in &c.peer_urls {
-                    if !peer.is_empty() {
-                        args.extend(["--peers".to_string(), peer.clone()]);
-                    }
-                }
-
-                if let Some(ref ip) = c.virtual_ip {
-                    if !ip.is_empty() {
-                        args.extend(["-i".to_string(), ip.clone()]);
-                    } else {
-                        args.push("-d".to_string());
-                    }
-                } else {
-                    args.push("-d".to_string());
-                }
-
-                args
+                return Self::build_easytier_launch(&config.easytier).await;
             }
 
             ExtensionId::Frpc => {
@@ -345,58 +297,78 @@ impl ExtensionManager {
 
         Ok(ExtensionLaunch {
             args,
-            temp_dir: None,
+            config_file: None,
         })
     }
 
+    async fn build_easytier_launch(config: &EasytierConfig) -> Result<ExtensionLaunch, String> {
+        validate_easytier_config(config)?;
+
+        match config.config_mode {
+            EasytierConfigMode::Quick => Ok(ExtensionLaunch {
+                args: Self::build_easytier_quick_args(config),
+                config_file: None,
+            }),
+            EasytierConfigMode::Full => {
+                let config_file = ProtectedConfigFile::create(
+                    "EasyTier",
+                    "easytier.toml",
+                    config.custom_toml.as_str(),
+                )
+                .await?;
+
+                Ok(ExtensionLaunch {
+                    args: vec!["-c".to_string(), Self::path_to_arg(config_file.path())],
+                    config_file: Some(config_file),
+                })
+            }
+        }
+    }
+
+    fn build_easytier_quick_args(config: &EasytierConfig) -> Vec<String> {
+        let mut args = vec![
+            "--network-name".to_string(),
+            config.network_name.clone(),
+            "--network-secret".to_string(),
+            config.network_secret.clone(),
+        ];
+
+        for peer in &config.peer_urls {
+            if !peer.is_empty() {
+                args.extend(["--peers".to_string(), peer.clone()]);
+            }
+        }
+
+        if let Some(ref ip) = config.virtual_ip {
+            if !ip.is_empty() {
+                args.extend(["-i".to_string(), ip.clone()]);
+            } else {
+                args.push("-d".to_string());
+            }
+        } else {
+            args.push("-d".to_string());
+        }
+
+        args
+    }
+
     async fn build_frpc_launch(config: &FrpcConfig) -> Result<ExtensionLaunch, String> {
+        validate_frpc_config(config)?;
+
         let config_text = match config.config_mode {
             FrpcConfigMode::Quick => Self::build_frpc_quick_toml(config)?,
-            FrpcConfigMode::Full => Self::validate_frpc_full_toml(config)?.to_string(),
+            FrpcConfigMode::Full => config.custom_toml.clone(),
         };
 
-        let temp_dir =
-            tempfile::tempdir().map_err(|e| format!("Failed to create FRPC config dir: {}", e))?;
-        let config_path = temp_dir.path().join("frpc.toml");
-
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::PermissionsExt;
-            std::fs::set_permissions(temp_dir.path(), std::fs::Permissions::from_mode(0o700))
-                .map_err(|e| format!("Failed to protect FRPC config dir: {}", e))?;
-        }
-
-        tokio::fs::write(&config_path, config_text)
-            .await
-            .map_err(|e| format!("Failed to write FRPC config: {}", e))?;
-
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::PermissionsExt;
-            tokio::fs::set_permissions(&config_path, std::fs::Permissions::from_mode(0o600))
-                .await
-                .map_err(|e| format!("Failed to protect FRPC config: {}", e))?;
-        }
+        let config_file =
+            ProtectedConfigFile::create("FRPC", "frpc.toml", config_text.as_str()).await?;
 
         Ok(ExtensionLaunch {
-            args: vec!["-c".to_string(), Self::path_to_arg(&config_path)],
-            temp_dir: Some(temp_dir),
+            args: vec!["-c".to_string(), Self::path_to_arg(config_file.path())],
+            config_file: Some(config_file),
         })
     }
 
-    fn validate_frpc_full_toml(config: &FrpcConfig) -> Result<&str, String> {
-        let trimmed = config.custom_toml.trim();
-        if trimmed.is_empty() {
-            return Err("FRPC full configuration is required".into());
-        }
-
-        trimmed
-            .parse::<DocumentMut>()
-            .map_err(|e| format!("FRPC full configuration is not valid TOML: {}", e))?;
-
-        Ok(config.custom_toml.as_str())
-    }
-
     fn build_frpc_quick_toml(config: &FrpcConfig) -> Result<String, String> {
         if config.proxy_name.trim().is_empty() {
             return Err("FRPC proxy name is required".into());
@@ -480,7 +452,7 @@ impl ExtensionManager {
         serde_json::to_string(value).unwrap_or_else(|_| "\"\"".to_string())
     }
 
-    fn path_to_arg(path: &PathBuf) -> String {
+    fn path_to_arg(path: &Path) -> String {
         path.to_string_lossy().to_string()
     }
 
@@ -603,3 +575,107 @@ impl ExtensionManager {
         futures::future::join_all(stop_futures).await;
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn easytier_launch_revalidates_full_configuration() {
+        let config = EasytierConfig {
+            config_mode: EasytierConfigMode::Full,
+            custom_toml: "instance_name = [".to_string(),
+            ..Default::default()
+        };
+
+        let error = ExtensionManager::build_easytier_launch(&config)
+            .await
+            .err()
+            .expect("invalid full configuration should fail launch validation");
+        assert!(error.starts_with("EasyTier full configuration is not valid TOML:"));
+    }
+
+    #[test]
+    fn easytier_quick_mode_keeps_command_line_arguments() {
+        let config = EasytierConfig {
+            network_name: "one-kvm".to_string(),
+            network_secret: "secret".to_string(),
+            peer_urls: vec![
+                "tcp://peer-one:11010".to_string(),
+                String::new(),
+                "udp://peer-two:11010".to_string(),
+            ],
+            virtual_ip: Some("10.20.30.40/24".to_string()),
+            ..Default::default()
+        };
+
+        assert_eq!(
+            ExtensionManager::build_easytier_quick_args(&config),
+            vec![
+                "--network-name",
+                "one-kvm",
+                "--network-secret",
+                "secret",
+                "--peers",
+                "tcp://peer-one:11010",
+                "--peers",
+                "udp://peer-two:11010",
+                "-i",
+                "10.20.30.40/24",
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn easytier_full_mode_uses_protected_temporary_config() {
+        let config_text = "instance_name = \"one-kvm\"\n";
+        let config = EasytierConfig {
+            config_mode: EasytierConfigMode::Full,
+            network_name: "ignored-quick-network".to_string(),
+            custom_toml: config_text.to_string(),
+            ..Default::default()
+        };
+
+        let launch = ExtensionManager::build_easytier_launch(&config)
+            .await
+            .expect("full EasyTier launch should build");
+        assert_eq!(launch.args[0], "-c");
+
+        let config_path = std::path::PathBuf::from(&launch.args[1]);
+        assert_eq!(
+            config_path.file_name().and_then(|name| name.to_str()),
+            Some("easytier.toml")
+        );
+        assert_eq!(
+            tokio::fs::read_to_string(&config_path).await.unwrap(),
+            config_text
+        );
+
+        drop(launch);
+        assert!(!config_path.exists());
+    }
+
+    #[test]
+    fn easytier_auto_start_uses_fields_for_selected_mode() {
+        let mut config = ExtensionsConfig::default();
+        config.easytier.enabled = true;
+        config.easytier.network_name = "quick-network".to_string();
+        assert!(ExtensionManager::is_enabled_for_config(
+            ExtensionId::Easytier,
+            &config
+        ));
+
+        config.easytier.config_mode = EasytierConfigMode::Full;
+        assert!(!ExtensionManager::is_enabled_for_config(
+            ExtensionId::Easytier,
+            &config
+        ));
+
+        config.easytier.network_name.clear();
+        config.easytier.custom_toml = "instance_name = \"one-kvm\"".to_string();
+        assert!(ExtensionManager::is_enabled_for_config(
+            ExtensionId::Easytier,
+            &config
+        ));
+    }
+}

src/extensions/mod.rs

@@ -1,6 +1,8 @@
 mod manager;
+mod protected_config;
 mod software;
 mod types;
+mod validation;
 
 pub use manager::ExtensionManager;
 #[cfg(unix)]
@@ -8,3 +10,7 @@ pub use manager::TTYD_SOCKET_PATH;
 #[cfg(windows)]
 pub use manager::TTYD_TCP_ADDR;
 pub use types::*;
+pub(crate) use validation::{
+    validate_easytier_config, validate_extension_config, validate_frpc_config,
+    validate_gostc_config,
+};

src/extensions/protected_config.rs

@@ -0,0 +1,95 @@
+use std::path::{Path, PathBuf};
+
+use tempfile::TempDir;
+
+pub(crate) struct ProtectedConfigFile {
+    _temp_dir: TempDir,
+    path: PathBuf,
+}
+
+impl ProtectedConfigFile {
+    pub(crate) async fn create(
+        extension_name: &str,
+        file_name: &str,
+        contents: &str,
+    ) -> Result<Self, String> {
+        let temp_dir = tempfile::tempdir().map_err(|error| {
+            format!("Failed to create {} config dir: {}", extension_name, error)
+        })?;
+        let path = temp_dir.path().join(file_name);
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+
+            std::fs::set_permissions(temp_dir.path(), std::fs::Permissions::from_mode(0o700))
+                .map_err(|error| {
+                    format!("Failed to protect {} config dir: {}", extension_name, error)
+                })?;
+        }
+
+        tokio::fs::write(&path, contents)
+            .await
+            .map_err(|error| format!("Failed to write {} config: {}", extension_name, error))?;
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+
+            tokio::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600))
+                .await
+                .map_err(|error| {
+                    format!("Failed to protect {} config: {}", extension_name, error)
+                })?;
+        }
+
+        Ok(Self {
+            _temp_dir: temp_dir,
+            path,
+        })
+    }
+
+    pub(crate) fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn protects_and_cleans_up_config_file() {
+        let config =
+            ProtectedConfigFile::create("Test extension", "extension.toml", "enabled = true\n")
+                .await
+                .unwrap();
+        let path = config.path().to_path_buf();
+
+        assert_eq!(
+            tokio::fs::read_to_string(&path).await.unwrap(),
+            "enabled = true\n"
+        );
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+
+            assert_eq!(
+                std::fs::metadata(path.parent().unwrap())
+                    .unwrap()
+                    .permissions()
+                    .mode()
+                    & 0o777,
+                0o700
+            );
+            assert_eq!(
+                std::fs::metadata(&path).unwrap().permissions().mode() & 0o777,
+                0o600
+            );
+        }
+
+        drop(config);
+        assert!(!path.exists());
+    }
+}

src/extensions/types.rs

@@ -103,11 +103,25 @@ impl Default for GostcConfig {
 }
 
 #[typeshare]
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum EasytierConfigMode {
+    Quick,
+    Full,
+}
+
+impl Default for EasytierConfigMode {
+    fn default() -> Self {
+        Self::Quick
+    }
+}
+
+#[typeshare]
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(default)]
-#[derive(Default)]
 pub struct EasytierConfig {
     pub enabled: bool,
+    pub config_mode: EasytierConfigMode,
     pub network_name: String,
     #[serde(skip_serializing_if = "String::is_empty")]
     pub network_secret: String,
@@ -115,6 +129,8 @@ pub struct EasytierConfig {
     pub peer_urls: Vec<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub virtual_ip: Option<String>,
+    #[serde(skip_serializing_if = "String::is_empty")]
+    pub custom_toml: String,
 }
 
 #[typeshare]
@@ -260,3 +276,26 @@ pub struct ExtensionLogs {
     pub id: ExtensionId,
     pub logs: Vec<String>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{EasytierConfig, EasytierConfigMode};
+
+    #[test]
+    fn legacy_easytier_config_defaults_to_quick_mode() {
+        let config: EasytierConfig = serde_json::from_str(
+            r#"{
+                "enabled": true,
+                "network_name": "legacy-network",
+                "network_secret": "secret",
+                "peer_urls": ["tcp://example.com:11010"],
+                "virtual_ip": "10.10.10.2/24"
+            }"#,
+        )
+        .expect("legacy EasyTier config should deserialize");
+
+        assert_eq!(config.config_mode, EasytierConfigMode::Quick);
+        assert!(config.custom_toml.is_empty());
+        assert_eq!(config.network_name, "legacy-network");
+    }
+}

src/extensions/validation.rs

@@ -0,0 +1,119 @@
+use toml_edit::DocumentMut;
+
+use super::types::{
+    EasytierConfig, EasytierConfigMode, ExtensionId, ExtensionsConfig, FrpProxyType, FrpcConfig,
+    FrpcConfigMode, GostcConfig,
+};
+
+pub(crate) fn validate_extension_config(
+    id: ExtensionId,
+    config: &ExtensionsConfig,
+) -> Result<(), String> {
+    match id {
+        ExtensionId::Ttyd => Ok(()),
+        ExtensionId::Gostc => validate_gostc_config(&config.gostc),
+        ExtensionId::Easytier => validate_easytier_config(&config.easytier),
+        ExtensionId::Frpc => validate_frpc_config(&config.frpc),
+    }
+}
+
+pub(crate) fn validate_gostc_config(config: &GostcConfig) -> Result<(), String> {
+    require_non_empty(config.addr.trim(), "GOSTC server address is required")?;
+    require_non_empty(config.key.as_str(), "GOSTC client key is required")
+}
+
+pub(crate) fn validate_easytier_config(config: &EasytierConfig) -> Result<(), String> {
+    match config.config_mode {
+        EasytierConfigMode::Quick => require_non_empty(
+            config.network_name.trim(),
+            "EasyTier network name is required",
+        ),
+        EasytierConfigMode::Full => validate_full_toml("EasyTier", config.custom_toml.as_str()),
+    }
+}
+
+pub(crate) fn validate_frpc_config(config: &FrpcConfig) -> Result<(), String> {
+    match config.config_mode {
+        FrpcConfigMode::Quick => {
+            require_non_empty(config.proxy_name.trim(), "FRPC proxy name is required")?;
+            require_non_empty(config.server_addr.trim(), "FRPC server address is required")?;
+            require_non_empty(config.token.as_str(), "FRPC token is required")?;
+            require_non_empty(config.local_ip.trim(), "FRPC local IP is required")?;
+
+            if matches!(config.proxy_type, FrpProxyType::Tcp | FrpProxyType::Udp)
+                && config.remote_port.is_none()
+            {
+                return Err("FRPC remote port is required for TCP/UDP proxies".to_string());
+            }
+
+            Ok(())
+        }
+        FrpcConfigMode::Full => validate_full_toml("FRPC", config.custom_toml.as_str()),
+    }
+}
+
+fn require_non_empty(value: &str, message: &str) -> Result<(), String> {
+    if value.is_empty() {
+        Err(message.to_string())
+    } else {
+        Ok(())
+    }
+}
+
+fn validate_full_toml(extension_name: &str, config: &str) -> Result<(), String> {
+    let trimmed = config.trim();
+    if trimmed.is_empty() {
+        return Err(format!("{} full configuration is required", extension_name));
+    }
+
+    trimmed.parse::<DocumentMut>().map_err(|error| {
+        format!(
+            "{} full configuration is not valid TOML: {}",
+            extension_name, error
+        )
+    })?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validates_easytier_full_configuration() {
+        let mut config = EasytierConfig {
+            config_mode: EasytierConfigMode::Full,
+            ..Default::default()
+        };
+
+        assert_eq!(
+            validate_easytier_config(&config).unwrap_err(),
+            "EasyTier full configuration is required"
+        );
+
+        config.custom_toml = "instance_name = [".to_string();
+        assert!(validate_easytier_config(&config)
+            .unwrap_err()
+            .starts_with("EasyTier full configuration is not valid TOML:"));
+
+        config.custom_toml = "instance_name = \"one-kvm\"".to_string();
+        assert!(validate_easytier_config(&config).is_ok());
+    }
+
+    #[test]
+    fn validates_frpc_through_the_same_entry_point() {
+        let mut config = FrpcConfig {
+            config_mode: FrpcConfigMode::Full,
+            ..Default::default()
+        };
+
+        assert_eq!(
+            validate_frpc_config(&config).unwrap_err(),
+            "FRPC full configuration is required"
+        );
+
+        config.custom_toml = "serverAddr = \"frps.example.com\"".to_string();
+        assert!(validate_frpc_config(&config).is_ok());
+    }
+}

src/hid/backend.rs

@@ -17,13 +17,21 @@ fn default_ch9329_baud_rate() -> u32 {
 #[serde(tag = "type", rename_all = "lowercase")]
 #[derive(Default)]
 pub enum HidBackendType {
-    Otg,
+    Otg {
+        #[serde(default)]
+        macos_drag: bool,
+    },
+    Bluetooth {
+        config: crate::config::BluetoothHidConfig,
+    },
     Ch9329 {
         port: String,
         #[serde(default = "default_ch9329_baud_rate")]
         baud_rate: u32,
         #[serde(default)]
         hybrid_mouse: bool,
+        #[serde(default)]
+        macos_drag: bool,
     },
     #[default]
     None,
@@ -32,7 +40,8 @@ pub enum HidBackendType {
 impl HidBackendType {
     pub fn name_str(&self) -> &str {
         match self {
-            Self::Otg => "otg",
+            Self::Otg { .. } => "otg",
+            Self::Bluetooth { .. } => "bluetooth",
             Self::Ch9329 { .. } => "ch9329",
             Self::None => "none",
         }
@@ -81,6 +90,17 @@ pub trait HidBackend: Send + Sync {
         ))
     }
 
+    async fn bluetooth_status(&self) -> Result<serde_json::Value> {
+        Err(crate::error::AppError::BadRequest(
+            "Bluetooth HID is not active".into(),
+        ))
+    }
+    async fn bluetooth_action(&self, _action: &str, _seconds: u32) -> Result<()> {
+        Err(crate::error::AppError::BadRequest(
+            "Bluetooth HID is not active".into(),
+        ))
+    }
+
     async fn reset(&self) -> Result<()>;
 
     async fn prepare_rebuild(&self) -> Result<()> {

src/hid/bluetooth.rs

@@ -0,0 +1,283 @@
+//! Translate canonical One-KVM input into the native BlueZ peripheral.
+use super::{
+    backend::{HidBackend, HidBackendRuntimeSnapshot},
+    types::{
+        ConsumerEvent, KeyEventType, KeyboardEvent, KeyboardReport, MouseEvent, MouseEventType,
+    },
+};
+use crate::{
+    config::BluetoothHidConfig,
+    error::{AppError, Result},
+    events::LedState,
+};
+use async_trait::async_trait;
+use one_kvm_bluetooth_hid::{Action, Config, Peripheral, Report};
+use tokio::sync::{watch, Mutex};
+
+fn error(message: String) -> AppError {
+    AppError::HidError {
+        backend: "bluetooth".into(),
+        error_code: "bluetooth_error".into(),
+        reason: message,
+    }
+}
+#[derive(Default)]
+struct InputState {
+    keyboard: KeyboardReport,
+    buttons: u8,
+    generation: u64,
+}
+pub struct BluetoothBackend {
+    peripheral: Peripheral,
+    input: Mutex<InputState>,
+    runtime: watch::Sender<()>,
+    worker: Mutex<Option<tokio::task::JoinHandle<()>>>,
+}
+impl BluetoothBackend {
+    pub fn new(
+        config: BluetoothHidConfig,
+        bonds: Option<std::sync::Arc<dyn one_kvm_bluetooth_hid::bonds::BondStore>>,
+    ) -> Result<Self> {
+        let peripheral = Peripheral::start_with_store(
+            Config {
+                adapter: config.adapter,
+                name: config.name,
+                peer: config.peer,
+            },
+            bonds,
+        )
+        .map_err(error)?;
+        let (runtime, _) = watch::channel(());
+        Ok(Self {
+            peripheral,
+            input: Mutex::new(InputState::default()),
+            runtime,
+            worker: Mutex::new(None),
+        })
+    }
+    fn check(&self, input: &mut InputState) -> Result<()> {
+        let status = self.peripheral.status();
+        if input.generation != status.generation || !status.ready {
+            *input = InputState {
+                generation: status.generation,
+                ..Default::default()
+            };
+        }
+        if !status.ready {
+            return Err(error(status.error.unwrap_or_else(|| {
+                "Pair and connect a computer; HID reports are not ready".into()
+            })));
+        }
+        Ok(())
+    }
+}
+#[async_trait]
+impl HidBackend for BluetoothBackend {
+    async fn init(&self) -> Result<()> {
+        let mut status = self.peripheral.subscribe();
+        let runtime = self.runtime.clone();
+        *self.worker.lock().await = Some(tokio::spawn(async move {
+            let mut last_error = None;
+            while status.changed().await.is_ok() {
+                let error = status.borrow_and_update().error.clone();
+                if error != last_error {
+                    if let Some(reason) = &error {
+                        tracing::warn!(%reason, "Bluetooth HID unavailable");
+                    }
+                    last_error = error;
+                }
+                runtime.send_replace(());
+            }
+        }));
+        Ok(())
+    }
+    async fn send_keyboard(&self, event: KeyboardEvent) -> Result<()> {
+        let mut input = self.input.lock().await;
+        self.check(&mut input)?;
+        apply_key(&mut input.keyboard, &event);
+        let result = self
+            .peripheral
+            .send(Report::Keyboard, input.keyboard.to_bytes().to_vec())
+            .await
+            .map_err(error);
+        if result.is_err() {
+            *input = InputState::default();
+        }
+        result
+    }
+    async fn send_mouse(&self, event: MouseEvent) -> Result<()> {
+        let mut input = self.input.lock().await;
+        self.check(&mut input)?;
+        let (mut x, mut y, wheel) = match event.event_type {
+            MouseEventType::Move => (event.x, event.y, 0),
+            MouseEventType::MoveAbs => {
+                return Err(AppError::BadRequest(
+                    "Bluetooth HID supports relative mouse only".into(),
+                ))
+            }
+            MouseEventType::Down | MouseEventType::Up => {
+                if let Some(button) = event.button {
+                    let bit = button.to_hid_bit();
+                    if event.event_type == MouseEventType::Down {
+                        input.buttons |= bit;
+                    } else {
+                        input.buttons &= !bit;
+                    }
+                }
+                (0, 0, 0)
+            }
+            MouseEventType::Scroll => (0, 0, event.scroll),
+        };
+        // Bound malformed remote input without silently clipping normal relative movements.
+        if x.unsigned_abs() > 32767 || y.unsigned_abs() > 32767 {
+            return Err(AppError::BadRequest(
+                "Relative mouse displacement too large".into(),
+            ));
+        }
+        loop {
+            let dx = x.clamp(-127, 127);
+            let dy = y.clamp(-127, 127);
+            self.peripheral
+                .send(
+                    Report::Mouse,
+                    vec![input.buttons, dx as i8 as u8, dy as i8 as u8, wheel as u8],
+                )
+                .await
+                .map_err(error)?;
+            x -= dx;
+            y -= dy;
+            if x == 0 && y == 0 {
+                break;
+            }
+        }
+        Ok(())
+    }
+    async fn send_consumer(&self, event: ConsumerEvent) -> Result<()> {
+        let mut input = self.input.lock().await;
+        self.check(&mut input)?;
+        if event.usage > 0x3ff {
+            return Err(AppError::BadRequest(
+                "Consumer usage exceeds Bluetooth report range".into(),
+            ));
+        }
+        self.peripheral
+            .send(Report::Consumer, event.usage.to_le_bytes().to_vec())
+            .await
+            .map_err(error)
+    }
+    async fn reset(&self) -> Result<()> {
+        *self.input.lock().await = InputState::default();
+        self.peripheral.action(Action::Reset).await.map_err(error)
+    }
+    async fn shutdown(&self) -> Result<()> {
+        let result = self.peripheral.shutdown().await.map_err(error);
+        if let Some(worker) = self.worker.lock().await.take() {
+            worker.abort();
+        }
+        result
+    }
+    fn runtime_snapshot(&self) -> HidBackendRuntimeSnapshot {
+        let state = self.peripheral.status();
+        HidBackendRuntimeSnapshot {
+            initialized: state.initialized,
+            online: state.ready,
+            supports_absolute_mouse: false,
+            keyboard_leds_enabled: true,
+            led_state: LedState {
+                num_lock: state.leds & 1 != 0,
+                caps_lock: state.leds & 2 != 0,
+                scroll_lock: state.leds & 4 != 0,
+                compose: state.leds & 8 != 0,
+                kana: state.leds & 16 != 0,
+            },
+            device: Some(state.peer.unwrap_or(state.adapter)),
+            screen_resolution: None,
+            error_code: state.error.as_ref().map(|_| "bluetooth_error".into()),
+            error: state.error,
+        }
+    }
+    fn subscribe_runtime(&self) -> watch::Receiver<()> {
+        self.runtime.subscribe()
+    }
+    async fn bluetooth_status(&self) -> Result<serde_json::Value> {
+        serde_json::to_value(self.peripheral.status()).map_err(|e| error(e.to_string()))
+    }
+    async fn bluetooth_action(&self, action: &str, seconds: u32) -> Result<()> {
+        if action == "pair" && !(10..=300).contains(&seconds) {
+            return Err(AppError::BadRequest(
+                "Pairing window must be 10–300 seconds".into(),
+            ));
+        }
+        let action = match action {
+            "pair" => Action::Pair(seconds),
+            "close" => Action::ClosePairing,
+            "forget" => Action::Forget,
+            "disconnect" => Action::Disconnect,
+            _ => return Err(AppError::BadRequest("Unknown Bluetooth action".into())),
+        };
+        self.peripheral.action(action).await.map_err(error)
+    }
+}
+fn apply_key(report: &mut KeyboardReport, event: &KeyboardEvent) {
+    if let Some(bit) = event.key.modifier_bit() {
+        match event.event_type {
+            KeyEventType::Down => report.modifiers |= bit,
+            KeyEventType::Up => report.modifiers &= !bit,
+        }
+    } else {
+        report.modifiers = event.modifiers.to_hid_byte();
+        let usage = event.key.to_hid_usage();
+        match event.event_type {
+            KeyEventType::Down if !report.keys.contains(&usage) => {
+                report.add_key(usage);
+            }
+            KeyEventType::Up => report.remove_key(usage),
+            _ => {}
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::hid::{CanonicalKey, KeyboardModifiers};
+    #[test]
+    fn repeated_keydown_does_not_leave_stuck_keys() {
+        let mut report = KeyboardReport::default();
+        let event = KeyboardEvent {
+            key: CanonicalKey::KeyA,
+            event_type: KeyEventType::Down,
+            modifiers: KeyboardModifiers::default(),
+        };
+        apply_key(&mut report, &event);
+        apply_key(&mut report, &event);
+        assert_eq!(report.keys.iter().filter(|&&key| key == 4).count(), 1);
+        apply_key(
+            &mut report,
+            &KeyboardEvent {
+                event_type: KeyEventType::Up,
+                ..event
+            },
+        );
+        assert_eq!(report.to_bytes(), [0; 8]);
+    }
+    #[test]
+    fn modifier_press_and_release() {
+        let mut report = KeyboardReport::default();
+        let event = KeyboardEvent {
+            key: CanonicalKey::ShiftRight,
+            event_type: KeyEventType::Down,
+            modifiers: KeyboardModifiers::default(),
+        };
+        apply_key(&mut report, &event);
+        assert_eq!(report.modifiers, 0x20);
+        apply_key(
+            &mut report,
+            &KeyboardEvent {
+                event_type: KeyEventType::Up,
+                ..event
+            },
+        );
+        assert_eq!(report.modifiers, 0);
+    }
+}

src/hid/ch9329.rs

@@ -44,7 +44,10 @@ const PARAM_CFG_VID_PID_OFFSET: usize = 11;
 const PARAM_CFG_STRING_FLAGS_OFFSET: usize = 36;
 const DESCRIPTOR_READ_RETRIES: usize = 3;
 const DESCRIPTOR_RETRY_DELAY_MS: u64 = 80;
-const DESCRIPTOR_APPLY_RESET_WAIT_MS: u64 = 3000;
+
+// CH9329/CH9329F can take several seconds to restart after a descriptor update.
+const DESCRIPTOR_APPLY_RESET_WAIT_MS: u64 = 5000;
+
 const USB_STRING_MAX_LEN: usize = 23;
 const USB_STRING_FLAG_ENABLE: u8 = 0x80;
 const USB_STRING_FLAG_MANUFACTURER: u8 = 0x04;
@@ -235,6 +238,8 @@ pub struct Ch9329Backend {
     last_abs_y: Arc<AtomicU16>,
     relative_mouse_active: Arc<AtomicBool>,
     hybrid_mouse: bool,
+    macos_drag: bool,
+    macos_drag_state: Mutex<super::macos_drag::MacosDrag>,
     runtime: Arc<Ch9329RuntimeState>,
 }
 
@@ -248,6 +253,15 @@ impl Ch9329Backend {
     }
 
     pub fn with_options(port_path: &str, baud_rate: u32, hybrid_mouse: bool) -> Result<Self> {
+        Self::with_compatibility_options(port_path, baud_rate, hybrid_mouse, false)
+    }
+
+    pub fn with_compatibility_options(
+        port_path: &str,
+        baud_rate: u32,
+        hybrid_mouse: bool,
+        macos_drag: bool,
+    ) -> Result<Self> {
         Ok(Self {
             port_path: port_path.to_string(),
             baud_rate,
@@ -263,6 +277,8 @@ impl Ch9329Backend {
             last_abs_y: Arc::new(AtomicU16::new(0)),
             relative_mouse_active: Arc::new(AtomicBool::new(false)),
             hybrid_mouse,
+            macos_drag,
+            macos_drag_state: Mutex::new(super::macos_drag::MacosDrag::default()),
             runtime: Arc::new(Ch9329RuntimeState::new()),
         })
     }
@@ -368,33 +384,41 @@ impl Ch9329Backend {
 
         Self::write_packet(port, address, cmd, data)?;
 
-        let mut pending = Vec::with_capacity(128);
+        // Keep enough room for a full parameter response and adjacent packets.
+        let mut pending = Vec::with_capacity(256);
         let deadline = Instant::now() + Duration::from_millis(RESPONSE_TIMEOUT_MS);
         let expected_ok = expected_response_cmd(cmd, false);
         let expected_err = expected_response_cmd(cmd, true);
 
         loop {
-            let mut chunk = [0u8; 128];
+            let mut chunk = [0u8; 256];
             match port.read(&mut chunk) {
                 Ok(n) if n > 0 => {
                     pending.extend_from_slice(&chunk[..n]);
 
+                    // Drain every complete frame so adjacent/out-of-order responses
+                    // cannot block the response for the current command.
                     while let Some((response, consumed)) = try_extract_response(&pending) {
+                        let current_response_cmd = response.cmd;
                         pending.drain(..consumed);
-                        if response.cmd == expected_ok || response.cmd == expected_err {
+
+                        if current_response_cmd == expected_ok
+                            || current_response_cmd == expected_err
+                        {
                             return Ok(response);
                         }
 
                         trace!(
-                            "CH9329 ignored out-of-order response: expected 0x{:02X}/0x{:02X}, got 0x{:02X}",
+                            "CH9329 filtered an overlapping packet: expected 0x{:02X}/0x{:02X}, bypass 0x{:02X}",
                             expected_ok,
                             expected_err,
-                            response.cmd
+                            current_response_cmd
                         );
                     }
 
+                    // Bound memory use if a noisy or disconnected port keeps delivering bytes.
                     if pending.len() > MAX_PACKET_SIZE * 4 {
-                        let keep = MAX_PACKET_SIZE;
+                        let keep = MAX_PACKET_SIZE * 2;
                         pending.drain(..pending.len().saturating_sub(keep));
                     }
                 }
@@ -410,15 +434,19 @@ impl Ch9329Backend {
 
             if Instant::now() >= deadline {
                 return Err(Self::backend_error(
-                    format!("No matching response from CH9329 for cmd 0x{:02X}", cmd),
+                    format!(
+                        "No matching response from CH9329 for cmd 0x{:02X}. Remaining buffer: {}",
+                        cmd,
+                        Self::hex_bytes(&pending)
+                    ),
                     "no_response",
                 ));
             }
 
-            thread::sleep(Duration::from_millis(1));
+            // Give the serial driver a short opportunity to deliver the next chunk.
+            thread::sleep(Duration::from_micros(200));
         }
     }
-
     fn try_best_effort_reset(port: &mut dyn serialport::SerialPort, address: u8) {
         if let Err(err) = Self::write_packet(port, address, cmd::RESET, &[]) {
             trace!("CH9329 best-effort reset failed: {}", err);
@@ -698,7 +726,6 @@ impl Ch9329Backend {
         let mut port = Self::open_port(port_path, baud_rate)?;
         Self::read_device_descriptor_on_port(port.as_mut(), DEFAULT_ADDR)
     }
-
     fn open_ready_port(
         port_path: &str,
         baud_rate: u32,
@@ -869,7 +896,7 @@ impl Ch9329Backend {
             match Self::open_ready_port(port_path, baud_rate, address) {
                 Ok((port, info)) => {
                     info!(
-                        "CH9329 reconnected: {}, USB: {}",
+                        "CH9329-compatible chip reconnected: {}, USB: {}",
                         info.version,
                         if info.usb_connected {
                             "connected"
@@ -892,7 +919,6 @@ impl Ch9329Backend {
             }
         }
     }
-
     fn recover_worker_port(
         mut port: Box<dyn serialport::SerialPort>,
         rx: &mpsc::Receiver<WorkerCommand>,
@@ -965,11 +991,12 @@ impl Ch9329Backend {
     }
 
     fn should_send_button_wheel_relative(&self) -> bool {
-        self.hybrid_mouse || self.relative_mouse_active.load(Ordering::Relaxed)
+        (self.hybrid_mouse && !self.macos_drag)
+            || self.relative_mouse_active.load(Ordering::Relaxed)
     }
 
     fn absolute_move_buttons(&self, buttons: u8) -> u8 {
-        if self.hybrid_mouse {
+        if self.hybrid_mouse && !self.macos_drag {
             0
         } else {
             buttons
@@ -1170,7 +1197,7 @@ impl HidBackend for Ch9329Backend {
         match init_rx.recv_timeout(Duration::from_millis(INIT_WAIT_MS)) {
             Ok(Ok(info)) => {
                 info!(
-                    "CH9329 chip detected: {}, USB: {}, LEDs: NumLock={}, CapsLock={}, ScrollLock={}",
+                    "CH9329-compatible chip detected: {}, USB: {}, LEDs: NumLock={}, CapsLock={}, ScrollLock={}",
                     info.version,
                     if info.usb_connected {
                         "connected"
@@ -1189,13 +1216,13 @@ impl HidBackend for Ch9329Backend {
             Ok(Err(err)) => {
                 self.record_error(
                     format!(
-                        "CH9329 not responding on {} @ {} baud: {}",
+                        "CH9329-compatible chip not responding on {} @ {} baud: {}",
                         self.port_path, self.baud_rate, err
                     ),
                     "init_failed",
                 );
                 warn!(
-                    "CH9329 not responding on {} @ {} baud, retrying in background: {}",
+                    "CH9329-compatible chip not responding on {} @ {} baud, retrying in background: {}",
                     self.port_path, self.baud_rate, err
                 );
                 *self.worker_tx.lock() = Some(tx);
@@ -1205,9 +1232,12 @@ impl HidBackend for Ch9329Backend {
             Err(_) => {
                 let _ = tx.send(WorkerCommand::Shutdown);
                 let _ = handle.join();
-                self.record_error("Timed out waiting for CH9329 worker init", "init_timeout");
+                self.record_error(
+                    "Timed out waiting for CH9329-compatible worker init",
+                    "init_timeout",
+                );
                 Err(AppError::Internal(
-                    "Timed out waiting for CH9329 initialization".to_string(),
+                    "Timed out waiting for CH9329-compatible initialization".to_string(),
                 ))
             }
         }
@@ -1256,6 +1286,31 @@ impl HidBackend for Ch9329Backend {
     async fn send_mouse(&self, event: MouseEvent) -> Result<()> {
         let buttons = self.mouse_buttons.load(Ordering::Relaxed);
 
+        if self.macos_drag {
+            use super::macos_drag::MouseReport;
+            let mut state = self.macos_drag_state.lock();
+            let (buttons, reports) = state.plan(event, buttons, *self.screen_resolution.read());
+            self.mouse_buttons.store(buttons, Ordering::Relaxed);
+            for report in reports {
+                match report {
+                    MouseReport::Absolute { buttons, x, y } => {
+                        let x = (u32::from(x) * CH9329_MOUSE_RESOLUTION / 32768) as u16;
+                        let y = (u32::from(y) * CH9329_MOUSE_RESOLUTION / 32768) as u16;
+                        self.send_mouse_absolute(buttons, x, y, 0)?;
+                    }
+                    MouseReport::Relative {
+                        buttons,
+                        dx,
+                        dy,
+                        wheel,
+                    } => {
+                        self.send_mouse_relative(buttons, dx, dy, wheel)?;
+                    }
+                }
+            }
+            return Ok(());
+        }
+
         match event.event_type {
             MouseEventType::Move => {
                 self.relative_mouse_active.store(true, Ordering::Relaxed);
@@ -1345,6 +1400,7 @@ impl HidBackend for Ch9329Backend {
         }
 
         self.mouse_buttons.store(0, Ordering::Relaxed);
+        self.macos_drag_state.lock().reset();
         self.last_abs_x.store(0, Ordering::Relaxed);
         self.last_abs_y.store(0, Ordering::Relaxed);
         self.relative_mouse_active.store(false, Ordering::Relaxed);
@@ -1650,13 +1706,67 @@ mod tests {
     }
 
     #[test]
-    fn test_hybrid_mouse_routes_buttons_and_wheel_to_relative_reports() {
+    fn test_hybrid_mouse_preserves_linux_compatibility_routing() {
         let backend = Ch9329Backend::with_options("/dev/null", DEFAULT_BAUD_RATE, true).unwrap();
 
         assert!(backend.should_send_button_wheel_relative());
         assert_eq!(backend.absolute_move_buttons(0x07), 0);
     }
 
+    #[tokio::test]
+    async fn test_macos_drag_uses_absolute_edges_and_relative_motion() {
+        let backend =
+            Ch9329Backend::with_compatibility_options("/dev/null", DEFAULT_BAUD_RATE, false, true)
+                .unwrap();
+        let (worker_tx, worker_rx) = mpsc::channel();
+        *backend.worker_tx.lock() = Some(worker_tx);
+        backend.set_screen_resolution(1920, 1080);
+
+        backend
+            .send_mouse(MouseEvent::move_abs(8000, 8000))
+            .await
+            .unwrap();
+        backend
+            .send_mouse(MouseEvent::button_down(crate::hid::MouseButton::Left))
+            .await
+            .unwrap();
+        backend
+            .send_mouse(MouseEvent::move_abs(8064, 8064))
+            .await
+            .unwrap();
+        backend
+            .send_mouse(MouseEvent::button_up(crate::hid::MouseButton::Left))
+            .await
+            .unwrap();
+
+        let packets: Vec<_> = worker_rx
+            .try_iter()
+            .filter_map(|command| match command {
+                WorkerCommand::Packet { cmd, data } => Some((cmd, data)),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(
+            packets,
+            vec![
+                (
+                    cmd::SEND_MS_ABS_DATA,
+                    vec![0x02, 0x00, 0xE8, 0x03, 0xE8, 0x03, 0x00],
+                ),
+                (
+                    cmd::SEND_MS_ABS_DATA,
+                    vec![0x02, 0x01, 0xE8, 0x03, 0xE8, 0x03, 0x00],
+                ),
+                (cmd::SEND_MS_REL_DATA, vec![0x01, 0x01, 0x03, 0x02, 0x00]),
+                (cmd::SEND_MS_REL_DATA, vec![0x01, 0x00, 0x00, 0x00, 0x00]),
+                (
+                    cmd::SEND_MS_ABS_DATA,
+                    vec![0x02, 0x00, 0xF0, 0x03, 0xF0, 0x03, 0x00],
+                ),
+            ]
+        );
+    }
+
     #[test]
     fn test_default_mouse_mode_preserves_absolute_report_buttons() {
         let backend = Ch9329Backend::with_baud_rate("/dev/null", DEFAULT_BAUD_RATE).unwrap();

src/hid/ch9329_proto.rs

@@ -10,6 +10,7 @@ pub const DEFAULT_ADDR: u8 = 0x00;
 pub const DEFAULT_BAUD_RATE: u32 = 9600;
 pub const MAX_DATA_LEN: usize = 64;
 pub const MAX_PACKET_SIZE: usize = 70;
+const EXTENDED_PARAMETER_RESPONSE_SIZES: [usize; 2] = [72, 88];
 
 pub mod cmd {
     pub const GET_INFO: u8 = 0x01;
@@ -130,7 +131,8 @@ impl Response {
 
         let cmd = bytes[3];
         let len = bytes[4] as usize;
-        if bytes.len() < 5 + len + 1 {
+        let expected_frame_len = 6 + len;
+        if bytes.len() < expected_frame_len {
             return None;
         }
 
@@ -139,7 +141,7 @@ impl Response {
             .iter()
             .fold(0u8, |acc, &x| acc.wrapping_add(x));
         if expected_checksum != calculated_checksum {
-            tracing::warn!(
+            tracing::debug!(
                 "CH9329 checksum mismatch: expected {:02X}, got {:02X}",
                 expected_checksum,
                 calculated_checksum
@@ -215,6 +217,11 @@ pub fn try_extract_response(buffer: &[u8]) -> Option<(Response, usize)> {
         }
 
         let len = buffer[offset + 4] as usize;
+        if len > MAX_DATA_LEN {
+            offset += 1;
+            continue;
+        }
+
         let frame_len = 6 + len;
         if offset + frame_len > buffer.len() {
             return None;
@@ -225,8 +232,103 @@ pub fn try_extract_response(buffer: &[u8]) -> Option<(Response, usize)> {
             return Some((response, offset + frame_len));
         }
 
+        // Some CH9329F firmware appends reserved bytes to GET_PARA_CFG while
+        // retaining the protocol LEN value of 50. Locate and validate the real
+        // checksum, return the documented 50-byte payload, and consume the
+        // complete extended frame. Other commands keep strict framing.
+        let cmd = buffer[offset + 3];
+        let data_start = offset + 5;
+        let parameter_payload_is_plausible = cmd == expected_response_cmd(cmd::GET_PARA_CFG, false)
+            && len == 50
+            && matches!(buffer[data_start], 0x00..=0x03 | 0x80..=0x83)
+            && matches!(buffer[data_start + 1], 0x00..=0x02 | 0x80..=0x82);
+        if parameter_payload_is_plausible {
+            for extended_size in EXTENDED_PARAMETER_RESPONSE_SIZES {
+                let extended_end = offset + extended_size;
+                if buffer.len() >= extended_end {
+                    let checksum_index = extended_end - 1;
+                    if calculate_checksum(&buffer[offset..checksum_index]) != buffer[checksum_index]
+                    {
+                        continue;
+                    }
+                    return Some((
+                        Response {
+                            cmd,
+                            data: buffer[data_start..data_start + len].to_vec(),
+                            is_error: false,
+                            error_code: None,
+                        },
+                        extended_end,
+                    ));
+                }
+            }
+
+            if buffer.len() < offset + EXTENDED_PARAMETER_RESPONSE_SIZES[1] {
+                return None;
+            }
+        }
+
         offset += 1;
     }
 
     None
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_standard_response_and_checksum() {
+        let frame = build_packet(DEFAULT_ADDR, 0x81, &[0x30, 0x01, 0x00, 0, 0, 0, 0, 0]);
+        let response = Response::parse(&frame).expect("valid response");
+        assert_eq!(response.cmd, 0x81);
+        assert_eq!(response.data, vec![0x30, 0x01, 0x00, 0, 0, 0, 0, 0]);
+        assert!(!response.is_error);
+    }
+
+    #[test]
+    fn extracts_extended_parameter_response_with_valid_trailing_checksum() {
+        let payload = [
+            0x80, 0x80, 0x00, 0x00, 0x00, 0x25, 0x80, 0x08, 0x00, 0x00, 0x03, 0x86, 0x1A, 0x2A,
+            0xE1, 0x00, 0x00, 0x00, 0x01, 0x00, 0x0D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        ];
+        for reserved_len in [16, 32] {
+            let mut frame = vec![0x57, 0xAB, DEFAULT_ADDR, 0x88, 50];
+            frame.extend_from_slice(&payload);
+            frame.extend_from_slice(&vec![0; reserved_len]);
+            frame.push(calculate_checksum(&frame));
+
+            assert!(Response::parse(&frame[..56]).is_none());
+            let (response, consumed) = try_extract_response(&frame).expect("extended response");
+            assert_eq!(response.cmd, 0x88);
+            assert_eq!(response.data, payload);
+            assert!(!response.is_error);
+            assert_eq!(consumed, frame.len());
+        }
+    }
+
+    #[test]
+    fn rejects_bad_checksum_for_other_commands() {
+        let mut frame = build_packet(DEFAULT_ADDR, 0x89, &[0x00; 50]);
+        *frame.last_mut().unwrap() ^= 0xFF;
+        assert!(Response::parse(&frame).is_none());
+        assert!(try_extract_response(&frame).is_none());
+    }
+
+    #[test]
+    fn extracts_noise_and_adjacent_packets() {
+        let first = build_packet(DEFAULT_ADDR, 0x81, &[0x30, 0x01, 0, 0, 0, 0, 0, 0]);
+        let second = build_packet(DEFAULT_ADDR, 0x82, &[0x00]);
+        let mut buffer = vec![0x00, 0xFF];
+        buffer.extend_from_slice(&first);
+        buffer.extend_from_slice(&second);
+
+        let (_, consumed) = try_extract_response(&buffer).expect("first response");
+        assert_eq!(consumed, 2 + first.len());
+        let (response, _) = try_extract_response(&buffer[consumed..]).expect("second response");
+        assert_eq!(response.cmd, 0x82);
+    }
+}

src/hid/factory.rs

@@ -8,6 +8,8 @@ use crate::error::{AppError, Result};
 use crate::otg::OtgService;
 
 pub struct HidBackendFactory {
+    #[cfg(target_os = "linux")]
+    pub bonds: std::sync::OnceLock<Arc<dyn one_kvm_bluetooth_hid::bonds::BondStore>>,
     #[cfg(unix)]
     otg_service: Option<Arc<OtgService>>,
 }
@@ -15,7 +17,11 @@ pub struct HidBackendFactory {
 impl HidBackendFactory {
     #[cfg(unix)]
     pub fn new(otg_service: Option<Arc<OtgService>>) -> Self {
-        Self { otg_service }
+        Self {
+            otg_service,
+            #[cfg(target_os = "linux")]
+            bonds: Default::default(),
+        }
     }
 
     #[cfg(not(unix))]
@@ -38,21 +44,43 @@ impl HidBackendFactory {
 
     async fn create(&self, backend_type: &HidBackendType) -> Result<Option<Arc<dyn HidBackend>>> {
         match backend_type {
-            HidBackendType::Otg => self.create_otg_backend().await.map(Some),
+            HidBackendType::Otg { macos_drag } => {
+                self.create_otg_backend(*macos_drag).await.map(Some)
+            }
             HidBackendType::Ch9329 {
                 port,
                 baud_rate,
                 hybrid_mouse,
+                macos_drag,
             } => {
                 info!(
-                    "Initializing CH9329 HID backend on {} @ {} baud, hybrid_mouse={}",
-                    port, baud_rate, hybrid_mouse
+                    "Initializing CH9329 HID backend on {} @ {} baud, hybrid_mouse={}, macos_drag={}",
+                    port, baud_rate, hybrid_mouse, macos_drag
                 );
-                Ok(Some(Arc::new(ch9329::Ch9329Backend::with_options(
-                    port,
-                    *baud_rate,
-                    *hybrid_mouse,
-                )?)))
+                Ok(Some(Arc::new(
+                    ch9329::Ch9329Backend::with_compatibility_options(
+                        port,
+                        *baud_rate,
+                        *hybrid_mouse,
+                        *macos_drag,
+                    )?,
+                )))
+            }
+            HidBackendType::Bluetooth { config } => {
+                #[cfg(target_os = "linux")]
+                {
+                    Ok(Some(Arc::new(super::bluetooth::BluetoothBackend::new(
+                        config.clone(),
+                        self.bonds.get().cloned(),
+                    )?)))
+                }
+                #[cfg(not(target_os = "linux"))]
+                {
+                    let _ = config;
+                    Err(AppError::Config(
+                        "Bluetooth HID requires Linux and BlueZ".into(),
+                    ))
+                }
             }
             HidBackendType::None => {
                 warn!("HID backend disabled");
@@ -62,7 +90,7 @@ impl HidBackendFactory {
     }
 
     #[cfg(unix)]
-    async fn create_otg_backend(&self) -> Result<Arc<dyn HidBackend>> {
+    async fn create_otg_backend(&self, macos_drag: bool) -> Result<Arc<dyn HidBackend>> {
         let otg_service = self
             .otg_service
             .as_ref()
@@ -74,11 +102,13 @@ impl HidBackendFactory {
             .ok_or_else(|| AppError::Config("OTG HID paths are not available".to_string()))?;
 
         info!("Creating OTG HID backend from device paths");
-        Ok(Arc::new(super::otg::OtgBackend::from_handles(handles)?))
+        Ok(Arc::new(super::otg::OtgBackend::with_macos_drag(
+            handles, macos_drag,
+        )?))
     }
 
     #[cfg(not(unix))]
-    async fn create_otg_backend(&self) -> Result<Arc<dyn HidBackend>> {
+    async fn create_otg_backend(&self, _macos_drag: bool) -> Result<Arc<dyn HidBackend>> {
         Err(AppError::Config(
             "OTG HID is only available on Linux".to_string(),
         ))

src/hid/macos_drag.rs

@@ -0,0 +1,256 @@
+//! Experimental absolute-button / relative-drag routing shared by USB backends.
+//! Relative counts are subject to host acceleration; they are not screen pixels.
+
+use super::{MouseEvent, MouseEventType};
+
+#[derive(Debug, PartialEq)]
+pub(super) enum MouseReport {
+    Absolute {
+        buttons: u8,
+        x: u16,
+        y: u16,
+    },
+    Relative {
+        buttons: u8,
+        dx: i8,
+        dy: i8,
+        wheel: i8,
+    },
+}
+
+#[derive(Default)]
+pub(super) struct MacosDrag {
+    position: (u16, u16),
+    remainder: (i64, i64),
+    extent: (u32, u32),
+    relative_input: bool,
+    absolute_drag: bool,
+}
+
+impl MacosDrag {
+    pub fn reset(&mut self) {
+        *self = Self::default();
+    }
+
+    pub fn plan(
+        &mut self,
+        event: MouseEvent,
+        buttons: u8,
+        extent: (u32, u32),
+    ) -> (u8, Vec<MouseReport>) {
+        let mut reports = Vec::new();
+        let mut next_buttons = buttons;
+        if extent != self.extent || buttons == 0 {
+            self.remainder = (0, 0);
+            self.extent = extent;
+        }
+        match event.event_type {
+            MouseEventType::MoveAbs => {
+                let position = (
+                    event.x.clamp(0, 32767) as u16,
+                    event.y.clamp(0, 32767) as u16,
+                );
+                self.relative_input = false;
+                if buttons != 0 {
+                    let dx =
+                        Self::delta(position.0, self.position.0, extent.0, &mut self.remainder.0);
+                    let dy =
+                        Self::delta(position.1, self.position.1, extent.1, &mut self.remainder.1);
+                    Self::motion(&mut reports, buttons, dx, dy);
+                } else {
+                    reports.push(MouseReport::Absolute {
+                        buttons: 0,
+                        x: position.0,
+                        y: position.1,
+                    });
+                }
+                self.position = position;
+            }
+            MouseEventType::Move => {
+                self.relative_input = true;
+                Self::motion(
+                    &mut reports,
+                    buttons,
+                    i64::from(event.x.clamp(-127, 127)),
+                    i64::from(event.y.clamp(-127, 127)),
+                );
+            }
+            MouseEventType::Down | MouseEventType::Up => {
+                if let Some(button) = event.button {
+                    let down = event.event_type == MouseEventType::Down;
+                    next_buttons = if down {
+                        buttons | button.to_hid_bit()
+                    } else {
+                        buttons & !button.to_hid_bit()
+                    };
+                    if down && buttons == 0 {
+                        self.absolute_drag = !self.relative_input;
+                    }
+                    // Latch the button route until all buttons are released, even
+                    // if the client changes pointer mode during the drag.
+                    if self.absolute_drag {
+                        if !down {
+                            // Relative drag reports also carry buttons. Clear their
+                            // state before releasing the absolute collection.
+                            reports.push(MouseReport::Relative {
+                                buttons: next_buttons,
+                                dx: 0,
+                                dy: 0,
+                                wheel: 0,
+                            });
+                        }
+                        reports.push(MouseReport::Absolute {
+                            buttons: next_buttons,
+                            x: self.position.0,
+                            y: self.position.1,
+                        });
+                    } else {
+                        reports.push(MouseReport::Relative {
+                            buttons: next_buttons,
+                            dx: 0,
+                            dy: 0,
+                            wheel: 0,
+                        });
+                    }
+                    if next_buttons == 0 {
+                        self.absolute_drag = false;
+                        self.remainder = (0, 0);
+                    }
+                }
+            }
+            MouseEventType::Scroll => {
+                reports.push(MouseReport::Relative {
+                    buttons,
+                    dx: 0,
+                    dy: 0,
+                    wheel: event.scroll,
+                });
+            }
+        }
+        (next_buttons, reports)
+    }
+
+    fn delta(current: u16, previous: u16, extent: u32, remainder: &mut i64) -> i64 {
+        // Keep the original 15-bit input precision and carry fractional counts.
+        let scaled =
+            (i64::from(current) - i64::from(previous)) * i64::from(extent.max(1)) + *remainder;
+        *remainder = scaled % 32768;
+        scaled / 32768
+    }
+
+    fn motion(reports: &mut Vec<MouseReport>, buttons: u8, dx: i64, dy: i64) {
+        // Distribute both axes over the same packets to preserve diagonal paths.
+        let count = (dx.abs().max(dy.abs()) + 126) / 127;
+        let mut previous = (0, 0);
+        for index in 1..=count {
+            let position = (dx * index / count, dy * index / count);
+            reports.push(MouseReport::Relative {
+                buttons,
+                dx: (position.0 - previous.0) as i8,
+                dy: (position.1 - previous.1) as i8,
+                wheel: 0,
+            });
+            previous = position;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::hid::MouseButton;
+
+    fn drag(steps: &[i32], extent: (u32, u32)) -> (i64, i64) {
+        let mut state = MacosDrag::default();
+        state.plan(MouseEvent::move_abs(8000, 8000), 0, extent);
+        state.plan(MouseEvent::button_down(MouseButton::Left), 0, extent);
+        let mut total = (0, 0);
+        for &x in steps {
+            for report in state.plan(MouseEvent::move_abs(x, x), 1, extent).1 {
+                if let MouseReport::Relative { dx, dy, .. } = report {
+                    total.0 += i64::from(dx);
+                    total.1 += i64::from(dy);
+                } else {
+                    panic!("absolute movement during drag");
+                }
+            }
+        }
+        total
+    }
+
+    #[test]
+    fn preserves_total_across_event_splitting_and_large_moves() {
+        let steps: Vec<_> = (8001..=16000).collect();
+        assert_eq!(drag(&[16000], (1920, 1080)), (468, 263));
+        assert_eq!(drag(&steps, (1920, 1080)), (468, 263));
+        assert_eq!(drag(&[16000, 8000], (1920, 1080)), (0, 0));
+        assert_eq!(drag(&[16000], (3840, 2160)), (937, 527));
+    }
+
+    #[test]
+    fn scroll_and_mode_switch_keep_absolute_drag_release() {
+        let mut state = MacosDrag::default();
+        let extent = (1920, 1080);
+        state.plan(MouseEvent::move_abs(8000, 8000), 0, extent);
+        state.plan(MouseEvent::button_down(MouseButton::Left), 0, extent);
+        let mut wheel = MouseEvent::move_abs(0, 0);
+        wheel.event_type = MouseEventType::Scroll;
+        wheel.scroll = 1;
+        assert_eq!(
+            state.plan(wheel, 1, extent).1,
+            vec![MouseReport::Relative {
+                buttons: 1,
+                dx: 0,
+                dy: 0,
+                wheel: 1
+            }]
+        );
+        state.plan(MouseEvent::move_rel(10, 0), 1, extent);
+        assert_eq!(
+            state
+                .plan(MouseEvent::button_up(MouseButton::Left), 1, extent)
+                .1,
+            vec![
+                MouseReport::Relative {
+                    buttons: 0,
+                    dx: 0,
+                    dy: 0,
+                    wheel: 0
+                },
+                MouseReport::Absolute {
+                    buttons: 0,
+                    x: 8000,
+                    y: 8000
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn native_relative_clicks_and_reset() {
+        let mut state = MacosDrag::default();
+        state.plan(MouseEvent::move_rel(1, 1), 0, (1920, 1080));
+        assert_eq!(
+            state
+                .plan(MouseEvent::button_down(MouseButton::Left), 0, (1920, 1080))
+                .1,
+            vec![MouseReport::Relative {
+                buttons: 1,
+                dx: 0,
+                dy: 0,
+                wheel: 0
+            }]
+        );
+        state.reset();
+        assert_eq!(
+            state
+                .plan(MouseEvent::button_down(MouseButton::Left), 0, (1920, 1080))
+                .1,
+            vec![MouseReport::Absolute {
+                buttons: 1,
+                x: 0,
+                y: 0
+            }]
+        );
+    }
+}

src/hid/mod.rs

@@ -1,12 +1,15 @@
 //! HID path: browser (WebSocket or WebRTC DataChannel) → queue → OTG gadget or CH9329.
 
 pub mod backend;
+#[cfg(target_os = "linux")]
+mod bluetooth;
 pub mod ch9329;
 mod ch9329_proto;
 pub mod consumer;
 pub mod datachannel;
 mod factory;
 pub mod keyboard;
+mod macos_drag;
 #[cfg(unix)]
 pub mod otg;
 #[cfg(unix)]
@@ -132,6 +135,8 @@ pub struct HidController {
     hid_worker: Mutex<Option<JoinHandle<()>>>,
     runtime_worker: Mutex<Option<JoinHandle<()>>>,
     backend_available: Arc<AtomicBool>,
+    reset_requested: Arc<AtomicBool>,
+    screen_resolution: parking_lot::RwLock<(u32, u32)>,
 }
 
 impl HidController {
@@ -153,6 +158,8 @@ impl HidController {
             hid_worker: Mutex::new(None),
             runtime_worker: Mutex::new(None),
             backend_available: Arc::new(AtomicBool::new(false)),
+            reset_requested: Arc::new(AtomicBool::new(false)),
+            screen_resolution: parking_lot::RwLock::new((1920, 1080)),
         }
     }
 
@@ -174,9 +181,16 @@ impl HidController {
             hid_worker: Mutex::new(None),
             runtime_worker: Mutex::new(None),
             backend_available: Arc::new(AtomicBool::new(false)),
+            reset_requested: Arc::new(AtomicBool::new(false)),
+            screen_resolution: parking_lot::RwLock::new((1920, 1080)),
         }
     }
 
+    #[cfg(target_os = "linux")]
+    pub fn set_bond_store(&self, store: crate::db::hid_bonds::HidBondStore) {
+        let _ = self.backend_factory.bonds.set(Arc::new(store));
+    }
+
     pub async fn set_event_bus(&self, events: Arc<EventBus>) {
         *self.events.write().await = Some(events);
     }
@@ -200,7 +214,12 @@ impl HidController {
             }
         };
 
-        *self.backend.write().await = Some(backend);
+        {
+            let mut slot = self.backend.write().await;
+            let (width, height) = *self.screen_resolution.read();
+            backend.set_screen_resolution(width, height);
+            *slot = Some(backend);
+        }
         self.sync_runtime_state_from_backend().await;
 
         self.start_event_worker().await;
@@ -235,7 +254,8 @@ impl HidController {
     }
 
     pub async fn prepare_otg_rebuild(&self) -> Result<()> {
-        if !matches!(*self.backend_type.read().await, HidBackendType::Otg) {
+        let backend_type = self.backend_type.read().await.clone();
+        if !matches!(backend_type, HidBackendType::Otg { .. }) {
             return Ok(());
         }
 
@@ -249,7 +269,7 @@ impl HidController {
 
         let current = self.runtime_state.read().await.clone();
         let rebuilding_state = HidRuntimeState::with_error(
-            &HidBackendType::Otg,
+            &backend_type,
             &current,
             "OTG gadget is rebuilding",
             "rebuilding",
@@ -293,6 +313,25 @@ impl HidController {
         self.enqueue_event(QueuedHidEvent::Consumer(event)).await
     }
 
+    pub async fn bluetooth_status(&self) -> Result<serde_json::Value> {
+        let backend = self
+            .backend
+            .read()
+            .await
+            .clone()
+            .ok_or_else(|| AppError::BadRequest("HID unavailable".into()))?;
+        backend.bluetooth_status().await
+    }
+    pub async fn bluetooth_action(&self, action: &str, seconds: u32) -> Result<()> {
+        let backend = self
+            .backend
+            .read()
+            .await
+            .clone()
+            .ok_or_else(|| AppError::BadRequest("HID unavailable".into()))?;
+        backend.bluetooth_action(action, seconds).await
+    }
+
     pub async fn reset(&self) -> Result<()> {
         if !self.backend_available.load(Ordering::Acquire) {
             return Ok(());
@@ -308,6 +347,24 @@ impl HidController {
         self.backend_type.read().await.clone()
     }
 
+    /// Keep the active capture dimensions across HID reloads and USB rebuilds.
+    pub async fn set_screen_resolution(&self, width: u32, height: u32) {
+        if width == 0 || height == 0 || width > 65535 || height > 65535 {
+            return;
+        }
+        {
+            let mut resolution = self.screen_resolution.write();
+            if *resolution == (width, height) {
+                return;
+            }
+            *resolution = (width, height);
+        }
+        if let Some(backend) = self.backend.read().await.as_ref() {
+            let (width, height) = *self.screen_resolution.read();
+            backend.set_screen_resolution(width, height);
+        }
+    }
+
     pub async fn snapshot(&self) -> HidRuntimeState {
         self.runtime_state.read().await.clone()
     }
@@ -349,6 +406,14 @@ impl HidController {
 
         if let Some(backend) = self.backend.write().await.take() {
             if let Err(e) = backend.shutdown().await {
+                // A Bluetooth shutdown may fail to restore adapter settings. Surface
+                // that failure so the config transaction can roll back.
+                if matches!(
+                    *self.backend_type.read().await,
+                    HidBackendType::Bluetooth { .. }
+                ) {
+                    return Err(e);
+                }
                 warn!("Error shutting down old HID backend: {}", e);
             }
         }
@@ -366,7 +431,14 @@ impl HidController {
             }
         };
 
-        *self.backend.write().await = new_backend;
+        {
+            let mut slot = self.backend.write().await;
+            if let Some(backend) = new_backend.as_ref() {
+                let (width, height) = *self.screen_resolution.read();
+                backend.set_screen_resolution(width, height);
+            }
+            *slot = new_backend;
+        }
 
         if matches!(new_backend_type, HidBackendType::None) {
             *self.backend_type.write().await = HidBackendType::None;
@@ -437,6 +509,7 @@ impl HidController {
         let backend = self.backend.clone();
         let pending_move = self.pending_move.clone();
         let pending_move_flag = self.pending_move_flag.clone();
+        let reset_requested = self.reset_requested.clone();
 
         let handle = tokio::spawn(async move {
             let mut rx = rx;
@@ -446,6 +519,15 @@ impl HidController {
                     None => break,
                 };
 
+                if reset_requested.swap(false, Ordering::AcqRel) {
+                    // A full input queue must not lose a key/button release and leave
+                    // the host stuck. Discard the obsolete batch and send all-up.
+                    while rx.try_recv().is_ok() {}
+                    *pending_move.lock() = None;
+                    pending_move_flag.store(false, Ordering::Release);
+                    process_hid_event(QueuedHidEvent::Reset, &backend).await;
+                    continue;
+                }
                 process_hid_event(event, &backend).await;
 
                 if pending_move_flag.swap(false, Ordering::AcqRel) {
@@ -504,7 +586,7 @@ impl HidController {
         match self.hid_tx.try_send(QueuedHidEvent::Mouse(event.clone())) {
             Ok(_) => Ok(()),
             Err(mpsc::error::TrySendError::Full(_)) => {
-                *self.pending_move.lock() = Some(event);
+                merge_pending_move(&mut self.pending_move.lock(), event);
                 self.pending_move_flag.store(true, Ordering::Release);
                 Ok(())
             }
@@ -524,11 +606,16 @@ impl HidController {
                     tx.send(ev),
                 )
                 .await;
-                if send_result.is_ok() {
-                    Ok(())
-                } else {
-                    warn!("HID event queue full, dropping event");
-                    Ok(())
+                match send_result {
+                    Ok(Ok(())) => Ok(()),
+                    Ok(Err(_)) => Err(AppError::BadRequest("HID event queue closed".into())),
+                    Err(_) => {
+                        self.reset_requested.store(true, Ordering::Release);
+                        warn!("HID event queue full; scheduling all-input release");
+                        Err(AppError::ServiceUnavailable(
+                            "HID input queue full; input state will be reset".into(),
+                        ))
+                    }
                 }
             }
             Err(mpsc::error::TrySendError::Closed(_)) => {
@@ -620,3 +707,121 @@ async fn apply_runtime_state(
         events.mark_device_info_dirty();
     }
 }
+
+fn merge_pending_move(pending: &mut Option<MouseEvent>, event: MouseEvent) {
+    if let Some(previous) = pending {
+        if previous.event_type == MouseEventType::Move && event.event_type == MouseEventType::Move {
+            previous.x = previous.x.saturating_add(event.x).clamp(-32767, 32767);
+            previous.y = previous.y.saturating_add(event.y).clamp(-32767, 32767);
+            return;
+        }
+    }
+    *pending = Some(event);
+}
+
+#[cfg(test)]
+mod queue_tests {
+    use super::*;
+    #[tokio::test]
+    async fn screen_resolution_updates_backend_and_retains_valid_dimensions() {
+        #[cfg(unix)]
+        let controller = HidController::new(HidBackendType::None, None);
+        #[cfg(not(unix))]
+        let controller = HidController::new(HidBackendType::None);
+        let backend = Arc::new(ch9329::Ch9329Backend::new("/dev/null").unwrap());
+        *controller.backend.write().await = Some(backend.clone());
+        controller.set_screen_resolution(3840, 2160).await;
+        assert_eq!(
+            backend.runtime_snapshot().screen_resolution,
+            Some((3840, 2160))
+        );
+        controller.set_screen_resolution(0, 0).await;
+        assert_eq!(*controller.screen_resolution.read(), (3840, 2160));
+        controller.set_screen_resolution(1280, 720).await;
+        assert_eq!(
+            backend.runtime_snapshot().screen_resolution,
+            Some((1280, 720))
+        );
+    }
+    struct TestBackend {
+        pressed: Arc<AtomicBool>,
+        reset_done: Arc<tokio::sync::Notify>,
+        runtime: tokio::sync::watch::Sender<()>,
+    }
+    #[async_trait::async_trait]
+    impl HidBackend for TestBackend {
+        async fn init(&self) -> Result<()> {
+            Ok(())
+        }
+        async fn send_keyboard(&self, _: KeyboardEvent) -> Result<()> {
+            self.pressed.store(true, Ordering::Release);
+            Ok(())
+        }
+        async fn send_mouse(&self, _: MouseEvent) -> Result<()> {
+            Ok(())
+        }
+        async fn reset(&self) -> Result<()> {
+            self.pressed.store(false, Ordering::Release);
+            self.reset_done.notify_one();
+            Ok(())
+        }
+        async fn shutdown(&self) -> Result<()> {
+            Ok(())
+        }
+        fn runtime_snapshot(&self) -> HidBackendRuntimeSnapshot {
+            HidBackendRuntimeSnapshot::default()
+        }
+        fn subscribe_runtime(&self) -> tokio::sync::watch::Receiver<()> {
+            self.runtime.subscribe()
+        }
+    }
+    #[tokio::test]
+    async fn congested_queue_releases_host_instead_of_replaying_keydowns() {
+        #[cfg(unix)]
+        let controller = HidController::new(HidBackendType::None, None);
+        #[cfg(not(unix))]
+        let controller = HidController::new(HidBackendType::None);
+        let pressed = Arc::new(AtomicBool::new(true));
+        let done = Arc::new(tokio::sync::Notify::new());
+        let (runtime, _) = tokio::sync::watch::channel(());
+        *controller.backend.write().await = Some(Arc::new(TestBackend {
+            pressed: pressed.clone(),
+            reset_done: done.clone(),
+            runtime,
+        }));
+        for _ in 0..HID_EVENT_QUEUE_CAPACITY {
+            controller
+                .enqueue_event(QueuedHidEvent::Keyboard(KeyboardEvent::key_down(
+                    CanonicalKey::KeyA,
+                    KeyboardModifiers::default(),
+                )))
+                .await
+                .unwrap();
+        }
+        assert!(controller
+            .enqueue_event(QueuedHidEvent::Reset)
+            .await
+            .is_err());
+        controller.start_event_worker().await;
+        tokio::time::timeout(Duration::from_secs(1), done.notified())
+            .await
+            .unwrap();
+        assert!(!pressed.load(Ordering::Acquire));
+    }
+
+    #[test]
+    fn relative_motion_is_accumulated_but_absolute_is_replaced() {
+        let mut pending = Some(MouseEvent::move_rel(100, -20));
+        merge_pending_move(&mut pending, MouseEvent::move_rel(80, 30));
+        assert_eq!(
+            (pending.as_ref().unwrap().x, pending.as_ref().unwrap().y),
+            (180, 10)
+        );
+        merge_pending_move(&mut pending, MouseEvent::move_abs(10, 20));
+        merge_pending_move(&mut pending, MouseEvent::move_abs(30, 40));
+        assert_eq!(
+            (pending.as_ref().unwrap().x, pending.as_ref().unwrap().y),
+            (30, 40)
+        );
+    }
+}

src/hid/otg.rs

@@ -80,6 +80,8 @@ pub struct OtgBackend {
     keyboard_leds_enabled: bool,
     keyboard_state: Mutex<KeyboardReport>,
     mouse_buttons: AtomicU8,
+    macos_drag: bool,
+    macos_drag_state: Mutex<super::macos_drag::MacosDrag>,
     led_state: Arc<parking_lot::RwLock<LedState>>,
     screen_resolution: parking_lot::RwLock<Option<(u32, u32)>>,
     udc_name: Arc<parking_lot::RwLock<Option<String>>>,
@@ -99,6 +101,15 @@ const OTG_RUNTIME_POLL_INTERVAL: Duration = Duration::from_millis(500);
 impl OtgBackend {
     /// Gadget must already exist; paths come from `OtgService`.
     pub fn from_handles(paths: HidDevicePaths) -> Result<Self> {
+        Self::with_macos_drag(paths, false)
+    }
+
+    pub fn with_macos_drag(paths: HidDevicePaths, macos_drag: bool) -> Result<Self> {
+        if macos_drag && (paths.mouse_relative.is_none() || paths.mouse_absolute.is_none()) {
+            return Err(AppError::Config(
+                "macOS drag compatibility requires both OTG mouse interfaces".into(),
+            ));
+        }
         let (runtime_notify_tx, _runtime_notify_rx) = watch::channel(());
         Ok(Self {
             keyboard_path: paths.keyboard,
@@ -112,6 +123,8 @@ impl OtgBackend {
             keyboard_leds_enabled: paths.keyboard_leds_enabled,
             keyboard_state: Mutex::new(KeyboardReport::default()),
             mouse_buttons: AtomicU8::new(0),
+            macos_drag,
+            macos_drag_state: Mutex::new(super::macos_drag::MacosDrag::default()),
             led_state: Arc::new(parking_lot::RwLock::new(LedState::default())),
             screen_resolution: parking_lot::RwLock::new(Some((1920, 1080))),
             udc_name: Arc::new(parking_lot::RwLock::new(paths.udc)),
@@ -167,9 +180,9 @@ impl OtgBackend {
         if now.duration_since(*last_log).as_secs() >= 1 {
             let count = self.error_count.swap(0, Ordering::Relaxed);
             if count > 1 {
-                warn!("{} (repeated {} times)", msg, count);
+                debug!("{} (repeated {} times)", msg, count);
             } else {
-                warn!("{}", msg);
+                debug!("{}", msg);
             }
             *last_log = now;
         } else {
@@ -852,6 +865,28 @@ impl HidBackend for OtgBackend {
     async fn send_mouse(&self, event: MouseEvent) -> Result<()> {
         let buttons = self.mouse_buttons.load(Ordering::Relaxed);
 
+        if self.macos_drag {
+            use super::macos_drag::MouseReport;
+            let mut state = self.macos_drag_state.lock();
+            let extent = self.screen_resolution.read().unwrap_or((1920, 1080));
+            let (buttons, reports) = state.plan(event, buttons, extent);
+            self.mouse_buttons.store(buttons, Ordering::Relaxed);
+            for report in reports {
+                match report {
+                    MouseReport::Absolute { buttons, x, y } => {
+                        self.send_mouse_report_absolute(buttons, x, y, 0)?
+                    }
+                    MouseReport::Relative {
+                        buttons,
+                        dx,
+                        dy,
+                        wheel,
+                    } => self.send_mouse_report_relative(buttons, dx, dy, wheel)?,
+                }
+            }
+            return Ok(());
+        }
+
         match event.event_type {
             MouseEventType::Move => {
                 let dx = event.x.clamp(-127, 127) as i8;
@@ -896,6 +931,7 @@ impl HidBackend for OtgBackend {
         }
 
         self.mouse_buttons.store(0, Ordering::Relaxed);
+        self.macos_drag_state.lock().reset();
         self.send_mouse_report_relative(0, 0, 0, 0)?;
         self.send_mouse_report_absolute(0, 0, 0, 0)?;
 
@@ -988,6 +1024,51 @@ mod tests {
         assert_eq!(kb_report.to_bytes().len(), 8);
     }
 
+    #[tokio::test]
+    async fn mouse_compatibility_writes_both_endpoints_and_preserves_default() {
+        use crate::hid::MouseButton;
+        for enabled in [false, true] {
+            let relative = tempfile::NamedTempFile::new().unwrap();
+            let absolute = tempfile::NamedTempFile::new().unwrap();
+            let backend = OtgBackend::with_macos_drag(
+                HidDevicePaths {
+                    mouse_relative: Some(relative.path().to_path_buf()),
+                    mouse_absolute: Some(absolute.path().to_path_buf()),
+                    ..Default::default()
+                },
+                enabled,
+            )
+            .unwrap();
+            for event in [
+                MouseEvent::move_abs(8000, 8000),
+                MouseEvent::button_down(MouseButton::Left),
+                MouseEvent::move_abs(16000, 16000),
+                MouseEvent::button_up(MouseButton::Left),
+            ] {
+                backend.send_mouse(event).await.unwrap();
+            }
+            let abs = fs::read(absolute.path()).unwrap();
+            let rel = fs::read(relative.path()).unwrap();
+            let buttons: Vec<_> = abs.chunks_exact(6).map(|packet| packet[0]).collect();
+            assert_eq!(buttons, if enabled { vec![0, 1, 0] } else { vec![0, 0] });
+            let dx: i32 = rel
+                .chunks_exact(4)
+                .map(|packet| i32::from(packet[1] as i8))
+                .sum();
+            let dy: i32 = rel
+                .chunks_exact(4)
+                .map(|packet| i32::from(packet[2] as i8))
+                .sum();
+            assert_eq!((dx, dy), if enabled { (468, 263) } else { (0, 0) });
+            assert_eq!(&rel[rel.len() - 4..], &[0, 0, 0, 0]);
+        }
+    }
+
+    #[test]
+    fn compatibility_requires_both_mouse_endpoints() {
+        assert!(OtgBackend::with_macos_drag(HidDevicePaths::default(), true).is_err());
+    }
+
     #[tokio::test]
     async fn prepare_rebuild_closes_devices_without_writing_reset_reports() {
         let mut file = tempfile::tempfile().unwrap();

src/lib.rs

@@ -36,6 +36,8 @@ pub mod redfish;
 #[cfg(feature = "desktop")]
 pub mod rtsp;
 #[cfg(feature = "desktop")]
+pub mod runtime;
+#[cfg(feature = "desktop")]
 pub mod rustdesk;
 #[cfg(feature = "desktop")]
 pub mod state;

src/main.rs

@@ -2,44 +2,21 @@ use std::collections::HashSet;
 use std::future::Future;
 use std::io::Write;
 use std::net::{IpAddr, SocketAddr};
-use std::path::{Path, PathBuf};
-use std::sync::Arc;
+use std::path::PathBuf;
 
 use axum_server::tls_rustls::RustlsConfig;
 use clap::{Args, Parser, Subcommand, ValueEnum};
 use futures::{stream::FuturesUnordered, StreamExt};
 use rustls::crypto::{ring, CryptoProvider};
-use tokio::sync::{broadcast, mpsc};
 use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
 
-use one_kvm::atx::AtxController;
-use one_kvm::audio::{AudioController, AudioControllerConfig, AudioQuality};
 use one_kvm::auth::{SessionStore, TwoFactorService, UserStore};
-use one_kvm::computer_use::ComputerUseManager;
-use one_kvm::config::{self, AppConfig, ConfigStore};
-use one_kvm::db::DatabasePool;
-use one_kvm::events::EventBus;
-use one_kvm::extensions::ExtensionManager;
-use one_kvm::hid::{HidBackendType, HidController};
-#[cfg(unix)]
-use one_kvm::msd::MsdController;
-#[cfg(unix)]
-use one_kvm::otg::OtgService;
+use one_kvm::config;
+use one_kvm::db::open_database_pool;
 use one_kvm::platform::PlatformCapabilities;
-use one_kvm::rtsp::RtspService;
-use one_kvm::rustdesk::RustDeskService;
-use one_kvm::state::{AppState, ShutdownAction};
-use one_kvm::update::UpdateService;
+use one_kvm::runtime::{RuntimeBuilder, WebConfigOverrides};
+use one_kvm::state::ShutdownAction;
 use one_kvm::utils::bind_tcp_listener;
-use one_kvm::video::codec_constraints::{
-    enforce_constraints_with_stream_manager, validate_third_party_codec_compatibility,
-    StreamCodecConstraints,
-};
-use one_kvm::video::format::{PixelFormat, Resolution};
-use one_kvm::video::{Streamer, VideoStreamManager};
-use one_kvm::vnc::VncService;
-use one_kvm::web;
-use one_kvm::webrtc::{WebRtcStreamer, WebRtcStreamerConfig};
 
 #[derive(Debug, Clone, Copy, Default, ValueEnum)]
 enum LogLevel {
@@ -47,7 +24,6 @@ enum LogLevel {
     Warn,
     #[default]
     Info,
-    Verbose,
     Debug,
     Trace,
 }
@@ -93,13 +69,9 @@ struct CliArgs {
     #[arg(short = 'd', long, value_name = "DIR")]
     data_dir: Option<PathBuf>,
 
-    /// Log level (error, warn, info, verbose, debug, trace)
+    /// Log level (error, warn, info, debug, trace)
     #[arg(short = 'l', long, value_name = "LEVEL", default_value = "info")]
     log_level: LogLevel,
-
-    /// Increase verbosity (-v for verbose, -vv for debug, -vvv for trace)
-    #[arg(short = 'v', long, action = clap::ArgAction::Count)]
-    verbose: u8,
 }
 
 #[derive(Subcommand, Debug)]
@@ -126,7 +98,7 @@ enum UserAction {
 async fn main() -> anyhow::Result<()> {
     let args = CliArgs::parse();
 
-    init_logging(args.log_level, args.verbose);
+    init_logging(args.log_level);
 
     CryptoProvider::install_default(ring::default_provider())
         .expect("Failed to install rustls crypto provider");
@@ -147,28 +119,20 @@ async fn main() -> anyhow::Result<()> {
         return Ok(());
     }
 
-    let (db, config_store, mut config) = load_runtime_config(&data_dir).await?;
-
-    if let Some(addr) = args.address {
-        config.web.bind_address = addr.clone();
-        config.web.bind_addresses = vec![addr];
-    }
-    if let Some(port) = args.http_port {
-        config.web.http_port = port;
-    }
-    if let Some(port) = args.https_port {
-        config.web.https_port = port;
-    }
-    if args.enable_https {
-        config.web.https_enabled = true;
-    }
-
-    if let Some(cert_path) = args.ssl_cert {
-        config.web.ssl_cert_path = Some(cert_path.to_string_lossy().to_string());
-    }
-    if let Some(key_path) = args.ssl_key {
-        config.web.ssl_key_path = Some(key_path.to_string_lossy().to_string());
-    }
+    let overrides = WebConfigOverrides {
+        address: args.address,
+        http_port: args.http_port,
+        https_port: args.https_port,
+        enable_https: args.enable_https,
+        ssl_cert: args.ssl_cert,
+        ssl_key: args.ssl_key,
+    };
+    let mut runtime = RuntimeBuilder::new(data_dir.clone())
+        .with_web_overrides(overrides)
+        .build()
+        .await?;
+    let config = runtime.config();
+    let state = runtime.state().clone();
 
     let bind_ips = resolve_bind_addresses(&config.web)?;
     let scheme = if config.web.https_enabled {
@@ -187,495 +151,12 @@ async fn main() -> anyhow::Result<()> {
         tracing::info!("Server will listen on: {}://{}", scheme, addr);
     }
 
-    let session_store = SessionStore::new(config.auth.session_timeout_secs as i64);
-
-    let user_store = UserStore::new(db.clone_pool());
-    let two_factor = TwoFactorService::new(db.clone_pool());
-
-    let (shutdown_tx, _) = broadcast::channel::<ShutdownAction>(1);
-
-    let events = Arc::new(EventBus::new());
-    tracing::info!("Event bus initialized");
-
-    let (video_format, video_resolution) = parse_video_config(&config);
-    tracing::debug!(
-        "Parsed video config: {} @ {}x{}",
-        video_format,
-        video_resolution.width,
-        video_resolution.height
-    );
-
-    let streamer = Streamer::new();
-    streamer.set_event_bus(events.clone()).await;
-    if let Some(ref device_path) = config.video.device {
-        if let Err(e) = streamer
-            .apply_video_config(
-                device_path,
-                video_format,
-                video_resolution,
-                config.video.fps,
-            )
-            .await
-        {
-            tracing::warn!(
-                "Failed to initialize video with config: {}, will auto-detect",
-                e
-            );
-        } else {
-            tracing::info!(
-                "Video configured: {} @ {}x{} {}",
-                device_path,
-                video_resolution.width,
-                video_resolution.height,
-                video_format
-            );
-        }
-    }
-
-    let webrtc_streamer = {
-        let webrtc_config = WebRtcStreamerConfig {
-            resolution: video_resolution,
-            input_format: video_format,
-            fps: config.video.fps,
-            bitrate_preset: config.stream.bitrate_preset,
-            encoder_backend: one_kvm::stream_encoder::encoder_type_to_backend(
-                config.stream.encoder.clone(),
-            ),
-            webrtc: {
-                let mut stun_servers = vec![];
-                let mut turn_servers = vec![];
-
-                let has_custom_stun = config
-                    .stream
-                    .stun_server
-                    .as_ref()
-                    .map(|s| !s.is_empty())
-                    .unwrap_or(false);
-                let has_custom_turn = config
-                    .stream
-                    .turn_server
-                    .as_ref()
-                    .map(|s| !s.is_empty())
-                    .unwrap_or(false);
-
-                if !has_custom_stun && !has_custom_turn {
-                    use one_kvm::webrtc::config::public_ice;
-                    let stun = public_ice::stun_server().to_string();
-                    tracing::info!("Using public STUN server: {}", stun);
-                    stun_servers.push(stun);
-                } else {
-                    if let Some(ref stun) = config.stream.stun_server {
-                        if !stun.is_empty() {
-                            stun_servers.push(stun.clone());
-                            tracing::info!("Using custom STUN server: {}", stun);
-                        }
-                    }
-                    if let Some(ref turn) = config.stream.turn_server {
-                        if !turn.is_empty() {
-                            let username = config.stream.turn_username.clone().unwrap_or_default();
-                            let credential =
-                                config.stream.turn_password.clone().unwrap_or_default();
-                            turn_servers.push(one_kvm::webrtc::config::TurnServer::new(
-                                turn.clone(),
-                                username.clone(),
-                                credential,
-                            ));
-                            tracing::info!(
-                                "Using custom TURN server: {} (user: {})",
-                                turn,
-                                username
-                            );
-                        }
-                    }
-                }
-
-                one_kvm::webrtc::config::WebRtcConfig {
-                    stun_servers,
-                    turn_servers,
-                    ..Default::default()
-                }
-            },
-            ..Default::default()
-        };
-        WebRtcStreamer::with_config(webrtc_config)
-    };
-    tracing::info!("WebRTC streamer created");
-
-    #[cfg(unix)]
-    let otg_service = Arc::new(OtgService::new());
-    #[cfg(unix)]
-    tracing::info!("OTG Service created");
-
-    #[cfg(unix)]
-    if let Err(e) = otg_service
-        .apply_config(&config.hid, &config.msd, &config.otg_network)
-        .await
-    {
-        tracing::warn!("Failed to apply OTG config: {}", e);
-    }
-
-    let hid_backend = match config.hid.backend {
-        config::HidBackend::Otg => HidBackendType::Otg,
-        config::HidBackend::Ch9329 => HidBackendType::Ch9329 {
-            port: config.hid.ch9329_port.clone(),
-            baud_rate: config.hid.ch9329_baudrate,
-            hybrid_mouse: config.hid.ch9329_hybrid_mouse,
-        },
-        config::HidBackend::None => HidBackendType::None,
-    };
-    #[cfg(unix)]
-    let hid = Arc::new(HidController::new(hid_backend, Some(otg_service.clone())));
-    #[cfg(not(unix))]
-    let hid = Arc::new(HidController::new(hid_backend));
-    hid.set_event_bus(events.clone()).await;
-    if let Err(e) = hid.init().await {
-        tracing::warn!("Failed to initialize HID backend: {}", e);
-    }
-
-    #[cfg(unix)]
-    let msd = if config.msd.enabled {
-        let ventoy_resource_dir = data_dir.join("ventoy");
-        let controller = MsdController::new(otg_service.clone(), config.msd.msd_dir_path());
-        if let Err(e) = controller.init(&ventoy_resource_dir).await {
-            tracing::warn!("Failed to initialize MSD controller: {}", e);
-            None
-        } else {
-            controller.set_event_bus(events.clone()).await;
-            Some(controller)
-        }
-    } else {
-        tracing::info!("MSD disabled in configuration");
-        None
-    };
-
-    let atx = if config.atx.enabled {
-        let controller_config = config.atx.to_controller_config();
-        let controller = AtxController::new(controller_config);
-
-        if let Err(e) = controller.init().await {
-            tracing::warn!("Failed to initialize ATX controller: {}", e);
-            None
-        } else {
-            Some(controller)
-        }
-    } else {
-        tracing::info!("ATX disabled in configuration");
-        None
-    };
-
-    let audio = {
-        let audio_config = AudioControllerConfig {
-            enabled: config.audio.enabled,
-            device: config.audio.device.clone(),
-            quality: match config.audio.quality.parse::<AudioQuality>() {
-                Ok(q) => q,
-                Err(e) => {
-                    tracing::warn!(
-                        "Invalid audio quality in config (value={:?}): {}, using balanced",
-                        config.audio.quality,
-                        e
-                    );
-                    AudioQuality::Balanced
-                }
-            },
-        };
-
-        let controller = AudioController::new(audio_config);
-        controller.set_event_bus(events.clone()).await;
-
-        if config.audio.enabled {
-            tracing::info!(
-                "Audio enabled: {}, quality={}",
-                config.audio.device,
-                config.audio.quality
-            );
-            if let Err(e) = controller.start_streaming().await {
-                tracing::warn!("Failed to start audio streaming: {}", e);
-            }
-        } else {
-            tracing::info!("Audio disabled in configuration");
-        }
-
-        Arc::new(controller)
-    };
-
-    let extensions = Arc::new(ExtensionManager::new());
-    tracing::info!("Extension manager initialized");
-
-    webrtc_streamer.set_hid_controller(hid.clone()).await;
-
-    webrtc_streamer.set_audio_controller(audio.clone()).await;
-    if config.audio.enabled {
-        if let Err(e) = webrtc_streamer.set_audio_enabled(true).await {
-            tracing::warn!("Failed to enable WebRTC audio: {}", e);
-        } else {
-            tracing::debug!("WebRTC audio enabled");
-        }
-    }
-
-    let (device_path, actual_resolution, actual_format, actual_fps, jpeg_quality) =
-        streamer.current_capture_config().await;
-    tracing::debug!(
-        "Initial video config: {}x{} {:?} @ {}fps",
-        actual_resolution.width,
-        actual_resolution.height,
-        actual_format,
-        actual_fps
-    );
-    webrtc_streamer
-        .update_video_config(actual_resolution, actual_format, actual_fps)
-        .await;
-    if let Some(device_path) = device_path {
-        let (subdev_path, bridge_kind, v4l2_driver) = streamer
-            .current_device()
-            .await
-            .map(|d| {
-                (
-                    d.subdev_path.clone(),
-                    d.bridge_kind.clone(),
-                    Some(d.driver.clone()),
-                )
-            })
-            .unwrap_or((None, None, None));
-        webrtc_streamer
-            .set_capture_device(
-                device_path,
-                jpeg_quality,
-                subdev_path,
-                bridge_kind,
-                v4l2_driver,
-            )
-            .await;
-        tracing::debug!("WebRTC streamer configured for direct capture");
-    } else {
-        tracing::warn!("No capture device configured for WebRTC");
-    }
-
-    let stream_manager = VideoStreamManager::with_webrtc_streamer(
-        streamer.clone(),
-        webrtc_streamer.clone() as std::sync::Arc<dyn one_kvm::video::traits::VideoOutput>,
-    );
-    stream_manager.set_event_bus(events.clone()).await;
-    stream_manager.set_config_store(config_store.clone()).await;
-    {
-        let stream_manager_weak = Arc::downgrade(&stream_manager);
-        audio
-            .set_recovered_callback(Arc::new(move || {
-                if let Some(stream_manager) = stream_manager_weak.upgrade() {
-                    tokio::spawn(async move {
-                        stream_manager.reconnect_webrtc_audio_sources().await;
-                    });
-                }
-            }))
-            .await;
-    }
-
-    let initial_mode = config.stream.mode.clone();
-    if let Err(e) = stream_manager.init_with_mode(initial_mode.clone()).await {
-        tracing::warn!(
-            "Failed to initialize stream manager with mode {:?}: {}",
-            initial_mode,
-            e
-        );
-    } else {
-        tracing::info!(
-            "Video stream manager initialized with mode: {:?}",
-            initial_mode
-        );
-    }
-
-    let third_party_codec_config_valid = match validate_third_party_codec_compatibility(&config) {
-        Ok(()) => true,
-        Err(e) => {
-            tracing::warn!(
-                    "Third-party access codec configuration is invalid; RustDesk/VNC/RTSP will not start: {}",
-                    e
-                );
-            false
-        }
-    };
-
-    let rustdesk = if third_party_codec_config_valid && config.rustdesk.is_valid() {
-        tracing::info!(
-            "Initializing RustDesk service: ID={} -> {}",
-            config.rustdesk.device_id,
-            config.rustdesk.rendezvous_addr()
-        );
-        let service = RustDeskService::new(
-            config.rustdesk.clone(),
-            stream_manager.clone(),
-            hid.clone(),
-            audio.clone(),
-        );
-        Some(Arc::new(service))
-    } else {
-        if config.rustdesk.enabled {
-            tracing::warn!(
-                "RustDesk enabled but configuration is incomplete (missing server or credentials)"
-            );
-        } else {
-            tracing::info!("RustDesk disabled in configuration");
-        }
-        None
-    };
-
-    let rtsp = if third_party_codec_config_valid && config.rtsp.enabled {
-        tracing::info!(
-            "Initializing RTSP service: rtsp://{}:{}/{}",
-            config.rtsp.bind,
-            config.rtsp.port,
-            config.rtsp.path
-        );
-        let service = RtspService::new(config.rtsp.clone(), stream_manager.clone());
-        Some(Arc::new(service))
-    } else {
-        tracing::info!("RTSP disabled in configuration");
-        None
-    };
-
-    let vnc = if third_party_codec_config_valid && config.vnc.enabled {
-        tracing::info!(
-            "Initializing VNC service: {}:{} ({:?})",
-            config.vnc.bind,
-            config.vnc.port,
-            config.vnc.encoding
-        );
-        Some(Arc::new(VncService::new(
-            config.vnc.clone(),
-            stream_manager.clone(),
-            hid.clone(),
-        )))
-    } else {
-        tracing::info!("VNC disabled in configuration");
-        None
-    };
-
-    let update_service = Arc::new(UpdateService::new(data_dir.join("updates")));
-    let computer_use = ComputerUseManager::new(config_store.clone(), hid.clone());
-
-    let state = AppState::new(
-        db.clone(),
-        config_store.clone(),
-        session_store,
-        user_store,
-        two_factor,
-        #[cfg(unix)]
-        otg_service,
-        stream_manager,
-        webrtc_streamer.clone(),
-        hid,
-        computer_use,
-        #[cfg(unix)]
-        msd,
-        atx,
-        audio,
-        rustdesk.clone(),
-        vnc.clone(),
-        rtsp.clone(),
-        extensions.clone(),
-        events.clone(),
-        update_service,
-        shutdown_tx.clone(),
-        data_dir.clone(),
-    );
-
-    if config.watchdog.enabled {
-        if let Err(error) = state.watchdog.enable().await {
-            tracing::error!(
-                "Configured hardware watchdog failed to start; web service will continue: {}",
-                error
-            );
-        } else {
-            tracing::info!("Hardware watchdog started");
-        }
-    }
-
-    extensions.set_event_bus(events.clone()).await;
-
-    if let Some(ref service) = rustdesk {
-        if let Err(e) = service.start().await {
-            tracing::error!("Failed to start RustDesk service: {}", e);
-        } else {
-            if let Some(updated_config) = service.save_credentials() {
-                if let Err(e) = config_store
-                    .update(|cfg| {
-                        cfg.rustdesk.public_key = updated_config.public_key.clone();
-                        cfg.rustdesk.private_key = updated_config.private_key.clone();
-                        cfg.rustdesk.signing_public_key = updated_config.signing_public_key.clone();
-                        cfg.rustdesk.signing_private_key =
-                            updated_config.signing_private_key.clone();
-                        cfg.rustdesk.uuid = updated_config.uuid.clone();
-                    })
-                    .await
-                {
-                    tracing::warn!("Failed to save RustDesk credentials: {}", e);
-                }
-            }
-            tracing::info!("RustDesk service started");
-        }
-    }
-    if let Some(ref service) = vnc {
-        if let Err(e) = service.start().await {
-            tracing::error!("Failed to start VNC service: {}", e);
-        } else {
-            tracing::info!("VNC service started");
-        }
-    }
-
-    if let Some(ref service) = rtsp {
-        if let Err(e) = service.start().await {
-            tracing::error!("Failed to start RTSP service: {}", e);
-        } else {
-            tracing::info!("RTSP service started");
-        }
-    }
-
-    {
-        let runtime_config = state.runtime_third_party_config().await;
-        let constraints = StreamCodecConstraints::from_config(&runtime_config);
-        state
-            .stream_manager
-            .set_runtime_codec_constraints(constraints.clone())
-            .await;
-        match enforce_constraints_with_stream_manager(&state.stream_manager, &constraints).await {
-            Ok(result) if result.changed => {
-                if let Some(message) = result.message {
-                    tracing::info!("{}", message);
-                }
-            }
-            Ok(_) => {}
-            Err(e) => tracing::warn!("Failed to enforce startup codec constraints: {}", e),
-        }
-    }
-
-    {
-        let ext_config = config_store.get();
-        extensions.start_enabled(&ext_config.extensions).await;
-    }
-
-    {
-        let extensions_clone = extensions.clone();
-        let config_store_clone = config_store.clone();
-        tokio::spawn(async move {
-            let mut interval = tokio::time::interval(std::time::Duration::from_secs(30));
-            loop {
-                interval.tick().await;
-                let config = config_store_clone.get();
-                extensions_clone.health_check(&config.extensions).await;
-            }
-        });
-        tracing::info!("Extension health check task started");
-    }
-
-    state.publish_device_info().await;
-
-    spawn_device_info_broadcaster(state.clone(), events);
-
-    let app = web::create_router(state.clone());
+    let app = runtime.router();
 
     let listeners = bind_tcp_listeners(&bind_ips, bind_port)?;
 
     let shutdown_signal = {
+        let shutdown_tx = state.shutdown_tx.clone();
         let mut shutdown_rx = shutdown_tx.subscribe();
         async move {
             tokio::select! {
@@ -735,7 +216,7 @@ async fn main() -> anyhow::Result<()> {
             servers.push(server);
         }
 
-        run_servers_until_shutdown(servers, shutdown_signal, &state, "HTTPS").await
+        run_servers_until_shutdown(servers, shutdown_signal, "HTTPS").await
     } else {
         let servers = FuturesUnordered::new();
         for listener in listeners {
@@ -747,9 +228,10 @@ async fn main() -> anyhow::Result<()> {
             servers.push(async move { server.await });
         }
 
-        run_servers_until_shutdown(servers, shutdown_signal, &state, "HTTP").await
+        run_servers_until_shutdown(servers, shutdown_signal, "HTTP").await
     };
 
+    runtime.shutdown().await;
     tracing::info!("Server shutdown complete");
     if let ShutdownAction::Restart { exe_path } = shutdown_action {
         restart_current_process(exe_path)?;
@@ -757,25 +239,16 @@ async fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-fn init_logging(level: LogLevel, verbose_count: u8) {
-    let effective_level = match verbose_count {
-        0 => level,
-        1 => LogLevel::Verbose,
-        2 => LogLevel::Debug,
-        _ => LogLevel::Trace,
+fn init_logging(level: LogLevel) {
+    let app_level = match level {
+        LogLevel::Error => "error",
+        LogLevel::Warn => "warn",
+        LogLevel::Info => "info",
+        LogLevel::Debug => "debug",
+        LogLevel::Trace => "trace",
     };
-
-    let filter = match effective_level {
-        LogLevel::Error => "one_kvm=error,tower_http=error,webrtc_sctp=warn",
-        LogLevel::Warn => "one_kvm=warn,tower_http=warn,webrtc_sctp=warn",
-        LogLevel::Info => "one_kvm=info,tower_http=info,webrtc_sctp=warn",
-        LogLevel::Verbose => "one_kvm=debug,tower_http=info,webrtc_sctp=warn",
-        LogLevel::Debug => "one_kvm=debug,tower_http=debug,webrtc_sctp=warn",
-        LogLevel::Trace => "one_kvm=trace,tower_http=debug,webrtc_sctp=warn",
-    };
-
     let env_filter =
-        tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| filter.into());
+        tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| app_level.into());
 
     if let Err(err) = tracing_subscriber::registry()
         .with(env_filter)
@@ -825,24 +298,16 @@ async fn shutdown_signal() -> anyhow::Result<()> {
     Ok(())
 }
 
-async fn open_database_pool(data_dir: &Path) -> anyhow::Result<DatabasePool> {
-    let db_path = data_dir.join("one-kvm.db");
-    let db = DatabasePool::new(&db_path).await?;
-    db.init_schema().await?;
-    Ok(db)
-}
-
 async fn run_servers_until_shutdown<F, E>(
     mut servers: FuturesUnordered<F>,
     shutdown_signal: impl Future<Output = ShutdownAction>,
-    state: &Arc<AppState>,
     protocol: &'static str,
 ) -> ShutdownAction
 where
     F: Future<Output = Result<(), E>> + Send,
     E: std::fmt::Display,
 {
-    let action = tokio::select! {
+    tokio::select! {
         action = shutdown_signal => {
             action
         }
@@ -852,9 +317,7 @@ where
             }
             ShutdownAction::Exit
         }
-    };
-    cleanup(state).await;
-    action
+    }
 }
 
 fn restart_current_process(exe_path: Option<PathBuf>) -> anyhow::Result<()> {
@@ -878,7 +341,6 @@ fn restart_current_process(exe_path: Option<PathBuf>) -> anyhow::Result<()> {
 }
 
 async fn run_cli_command(command: CliCommand, data_dir: PathBuf) -> anyhow::Result<()> {
-    tokio::fs::create_dir_all(&data_dir).await?;
     let db = open_database_pool(&data_dir).await?;
     let users = UserStore::new(db.clone_pool());
     let two_factor = TwoFactorService::new(db.clone_pool());
@@ -891,64 +353,6 @@ async fn run_cli_command(command: CliCommand, data_dir: PathBuf) -> anyhow::Resu
     }
 }
 
-async fn load_runtime_config(
-    data_dir: &Path,
-) -> anyhow::Result<(DatabasePool, ConfigStore, AppConfig)> {
-    tokio::fs::create_dir_all(data_dir).await?;
-
-    let db = open_database_pool(data_dir).await?;
-    let config_store = ConfigStore::new(db.clone_pool())?;
-    config_store.load().await?;
-    let mut config = (*config_store.get()).clone();
-    config.apply_platform_defaults();
-
-    prepare_linux_runtime_dirs(data_dir, &config_store, &mut config).await?;
-
-    Ok((db, config_store, config))
-}
-
-#[cfg(unix)]
-async fn prepare_linux_runtime_dirs(
-    data_dir: &Path,
-    config_store: &ConfigStore,
-    config: &mut AppConfig,
-) -> anyhow::Result<()> {
-    let mut msd_dir_updated = false;
-    if config.msd.msd_dir.trim().is_empty() {
-        let msd_dir = data_dir.join("msd");
-        config.msd.msd_dir = msd_dir.to_string_lossy().to_string();
-        msd_dir_updated = true;
-    } else if !PathBuf::from(&config.msd.msd_dir).is_absolute() {
-        let msd_dir = data_dir.join(&config.msd.msd_dir);
-        tracing::warn!(
-            "MSD directory is relative, rebasing to {}",
-            msd_dir.display()
-        );
-        config.msd.msd_dir = msd_dir.to_string_lossy().to_string();
-        msd_dir_updated = true;
-    }
-    if msd_dir_updated {
-        config_store.set(config.clone()).await?;
-    }
-    let msd_dir = PathBuf::from(&config.msd.msd_dir);
-    if let Err(e) = tokio::fs::create_dir_all(msd_dir.join("images")).await {
-        tracing::warn!("Failed to create MSD images directory: {}", e);
-    }
-    if let Err(e) = tokio::fs::create_dir_all(msd_dir.join("ventoy")).await {
-        tracing::warn!("Failed to create MSD ventoy directory: {}", e);
-    }
-    Ok(())
-}
-
-#[cfg(not(unix))]
-async fn prepare_linux_runtime_dirs(
-    _data_dir: &Path,
-    _config_store: &ConfigStore,
-    _config: &mut AppConfig,
-) -> anyhow::Result<()> {
-    Ok(())
-}
-
 async fn run_user_action(
     action: UserAction,
     users: &UserStore,
@@ -1060,17 +464,6 @@ fn bind_tcp_listeners(addrs: &[IpAddr], port: u16) -> anyhow::Result<Vec<std::ne
     Ok(listeners)
 }
 
-fn parse_video_config(config: &AppConfig) -> (PixelFormat, Resolution) {
-    let format = config
-        .video
-        .format
-        .as_ref()
-        .and_then(|f: &String| f.parse::<PixelFormat>().ok())
-        .unwrap_or(PixelFormat::Mjpeg);
-    let resolution = Resolution::new(config.video.width, config.video.height);
-    (format, resolution)
-}
-
 fn generate_self_signed_cert() -> anyhow::Result<rcgen::CertifiedKey<rcgen::KeyPair>> {
     use rcgen::generate_simple_self_signed;
 
@@ -1083,197 +476,3 @@ fn generate_self_signed_cert() -> anyhow::Result<rcgen::CertifiedKey<rcgen::KeyP
     let certified_key = generate_simple_self_signed(subject_alt_names)?;
     Ok(certified_key)
 }
-
-fn spawn_device_info_broadcaster(state: Arc<AppState>, events: Arc<EventBus>) {
-    use std::time::{Duration, Instant};
-
-    enum DeviceInfoTrigger {
-        Event,
-        Lagged { topic: &'static str, count: u64 },
-    }
-
-    const DEVICE_INFO_TOPICS: &[&str] = &[
-        "stream.state_changed",
-        "stream.config_applied",
-        "stream.mode_ready",
-    ];
-    const DEBOUNCE_MS: u64 = 100;
-
-    let (trigger_tx, mut trigger_rx) = mpsc::unbounded_channel();
-
-    for topic in DEVICE_INFO_TOPICS {
-        let Some(mut rx) = events.subscribe_topic(topic) else {
-            tracing::warn!(
-                "DeviceInfo broadcaster missing topic subscription: {}",
-                topic
-            );
-            continue;
-        };
-
-        let trigger_tx = trigger_tx.clone();
-        let topic_name = *topic;
-        tokio::spawn(async move {
-            loop {
-                match rx.recv().await {
-                    Ok(_) => {
-                        if trigger_tx.send(DeviceInfoTrigger::Event).is_err() {
-                            break;
-                        }
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Lagged(count)) => {
-                        if trigger_tx
-                            .send(DeviceInfoTrigger::Lagged {
-                                topic: topic_name,
-                                count,
-                            })
-                            .is_err()
-                        {
-                            break;
-                        }
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                }
-            }
-        });
-    }
-
-    {
-        let mut dirty_rx = events.subscribe_device_info_dirty();
-        let trigger_tx = trigger_tx.clone();
-        tokio::spawn(async move {
-            loop {
-                match dirty_rx.recv().await {
-                    Ok(()) => {
-                        if trigger_tx.send(DeviceInfoTrigger::Event).is_err() {
-                            break;
-                        }
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Lagged(count)) => {
-                        if trigger_tx
-                            .send(DeviceInfoTrigger::Lagged {
-                                topic: "device_info_dirty",
-                                count,
-                            })
-                            .is_err()
-                        {
-                            break;
-                        }
-                    }
-                    Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
-                }
-            }
-        });
-    }
-
-    tokio::spawn(async move {
-        let mut last_broadcast = Instant::now() - Duration::from_millis(DEBOUNCE_MS);
-        let mut pending_broadcast = false;
-
-        loop {
-            let recv_result = if pending_broadcast {
-                let remaining =
-                    DEBOUNCE_MS.saturating_sub(last_broadcast.elapsed().as_millis() as u64);
-                tokio::time::timeout(Duration::from_millis(remaining), trigger_rx.recv()).await
-            } else {
-                Ok(trigger_rx.recv().await)
-            };
-
-            match recv_result {
-                Ok(Some(DeviceInfoTrigger::Event)) => {
-                    pending_broadcast = true;
-                }
-                Ok(Some(DeviceInfoTrigger::Lagged { topic, count })) => {
-                    tracing::warn!(
-                        "DeviceInfo broadcaster lagged by {} events on topic {}",
-                        count,
-                        topic
-                    );
-                    pending_broadcast = true;
-                }
-                Ok(None) => {
-                    tracing::info!("Event bus closed, stopping DeviceInfo broadcaster");
-                    break;
-                }
-                Err(_timeout) => {}
-            }
-
-            if pending_broadcast && last_broadcast.elapsed() >= Duration::from_millis(DEBOUNCE_MS) {
-                state.publish_device_info().await;
-                tracing::trace!("Broadcasted DeviceInfo (debounced)");
-                last_broadcast = Instant::now();
-                pending_broadcast = false;
-            }
-        }
-    });
-
-    tracing::info!(
-        "DeviceInfo broadcaster task started (debounce: {}ms)",
-        DEBOUNCE_MS
-    );
-}
-
-async fn cleanup(state: &Arc<AppState>) {
-    state.extensions.stop_all().await;
-    tracing::info!("Extensions stopped");
-
-    if let Some(ref service) = *state.rustdesk.read().await {
-        if let Err(e) = service.stop().await {
-            tracing::warn!("Failed to stop RustDesk service: {}", e);
-        } else {
-            tracing::info!("RustDesk service stopped");
-        }
-    }
-
-    if let Some(ref service) = *state.vnc.read().await {
-        if let Err(e) = service.stop().await {
-            tracing::warn!("Failed to stop VNC service: {}", e);
-        } else {
-            tracing::info!("VNC service stopped");
-        }
-    }
-
-    if let Some(ref service) = *state.rtsp.read().await {
-        if let Err(e) = service.stop().await {
-            tracing::warn!("Failed to stop RTSP service: {}", e);
-        } else {
-            tracing::info!("RTSP service stopped");
-        }
-    }
-
-    if let Err(e) = state.stream_manager.stop().await {
-        tracing::warn!("Failed to stop streamer: {}", e);
-    }
-
-    if let Err(e) = state.hid.shutdown().await {
-        tracing::warn!("Failed to shutdown HID: {}", e);
-    }
-
-    #[cfg(unix)]
-    if let Some(msd) = state.msd.write().await.as_mut() {
-        if let Err(e) = msd.shutdown().await {
-            tracing::warn!("Failed to shutdown MSD: {}", e);
-        }
-    }
-
-    #[cfg(unix)]
-    if let Err(e) = state.otg_service.shutdown().await {
-        tracing::warn!("Failed to shutdown OTG: {}", e);
-    }
-
-    if let Some(atx) = state.atx.write().await.as_mut() {
-        if let Err(e) = atx.shutdown().await {
-            tracing::warn!("Failed to shutdown ATX: {}", e);
-        }
-    }
-
-    if let Err(e) = state.audio.shutdown().await {
-        tracing::warn!("Failed to shutdown audio: {}", e);
-    }
-
-    if let Err(error) = state.watchdog.disable().await {
-        tracing::error!(
-            "CRITICAL: failed to disable hardware watchdog during shutdown: {}",
-            error
-        );
-    }
-}

src/msd/controller.rs

@@ -8,10 +8,11 @@ use tracing::{debug, info, warn};
 use super::image::ImageManager;
 use super::monitor::MsdHealthMonitor;
 use super::types::{
-    DiskMode, DownloadProgress, DownloadStatus, DriveInfo, ImageInfo, MountedMedia,
-    MountedMediaKind, MsdState,
+    DiskMode, DownloadProgress, DownloadStatus, DriveFileAccess, DriveInfo, ImageInfo,
+    MountedMedia, MountedMediaKind, MsdState,
 };
-use crate::error::{AppError, Result};
+use super::ventoy_drive::VentoyDrive;
+use crate::error::{AppError, MsdErrorCode, Result};
 use crate::otg::{MsdFunction, MsdLunConfig, OtgService};
 
 pub struct MsdController {
@@ -62,17 +63,15 @@ impl MsdController {
             ),
         }
 
-        if let Err(e) = std::fs::create_dir_all(&self.images_path) {
-            warn!("Failed to create images directory: {}", e);
-        }
-        if let Err(e) = std::fs::create_dir_all(&self.ventoy_dir) {
-            warn!("Failed to create ventoy directory: {}", e);
-        }
+        tokio::fs::create_dir_all(&self.images_path).await?;
+        tokio::fs::create_dir_all(&self.ventoy_dir).await?;
 
         info!("Fetching MSD function from OtgService");
-        let msd_func = self.otg_service.msd_function().await.ok_or_else(|| {
-            AppError::Internal("MSD function is not active in OtgService".to_string())
-        })?;
+        let msd_func = self
+            .otg_service
+            .msd_function()
+            .await
+            .ok_or_else(|| AppError::from(MsdErrorCode::MsdUnavailable))?;
 
         *self.msd_function.write().await = Some(msd_func);
 
@@ -85,14 +84,9 @@ impl MsdController {
         state.available = true;
 
         if self.drive_path.exists() {
-            if let Ok(metadata) = std::fs::metadata(&self.drive_path) {
-                let drive_info = DriveInfo {
-                    size: metadata.len(),
-                    used: 0,
-                    free: metadata.len(),
-                    initialized: true,
-                    path: self.drive_path.clone(),
-                };
+            if let Ok(drive_info) =
+                VentoyDrive::new(self.drive_path.clone()).raw_info(DriveFileAccess::Unknown)
+            {
                 state.drive_info = Some(drive_info.clone());
                 debug!(
                     "Found existing virtual drive: {}",
@@ -148,7 +142,7 @@ impl MsdController {
         read_only: bool,
         requested_lun: Option<u8>,
     ) -> Result<()> {
-        let _op_guard = self.operation_lock.write().await;
+        let _op_guard = self.try_operation()?;
         let mut state = self.state.write().await;
         let previous_state = state.clone();
 
@@ -159,7 +153,7 @@ impl MsdController {
             self.monitor
                 .report_error(&error_msg, "image_not_found")
                 .await;
-            return Err(AppError::Internal(error_msg));
+            return Err(MsdErrorCode::MsdResourceNotFound.into());
         }
 
         if state
@@ -167,7 +161,7 @@ impl MsdController {
             .iter()
             .any(|media| media.kind == MountedMediaKind::Image && media.id == image.id)
         {
-            return Err(AppError::BadRequest("Image is already mounted".to_string()));
+            return Err(MsdErrorCode::MsdMediaAlreadyMounted.into());
         }
 
         let lun = Self::select_lun(&state, requested_lun)?;
@@ -195,50 +189,38 @@ impl MsdController {
     }
 
     pub async fn mount_drive(&self) -> Result<()> {
-        let _op_guard = self.operation_lock.write().await;
+        let _op_guard = self.try_operation()?;
         let mut state = self.state.write().await;
         let previous_state = state.clone();
 
         self.assert_available(&state).await?;
 
-        if !self.drive_path.exists() {
-            let err =
-                AppError::Internal("Virtual drive not initialized. Call init first.".to_string());
-            self.monitor
-                .report_error("Virtual drive not initialized", "drive_not_found")
-                .await;
-            return Err(err);
-        }
-
-        let drive_info = state.drive_info.clone().or_else(|| {
-            std::fs::metadata(&self.drive_path)
-                .ok()
-                .map(|metadata| DriveInfo {
-                    size: metadata.len(),
-                    used: 0,
-                    free: metadata.len(),
-                    initialized: true,
-                    path: self.drive_path.clone(),
-                })
-        });
-        if state.drive_info.is_none() {
-            state.drive_info = drive_info.clone();
-        }
-
         if state
             .mounted_media
             .iter()
             .any(|media| media.kind == MountedMediaKind::Drive)
         {
-            return Err(AppError::BadRequest(
-                "Virtual drive is already mounted".to_string(),
-            ));
+            return Err(MsdErrorCode::MsdMediaAlreadyMounted.into());
         }
 
-        let drive_info = drive_info
-            .ok_or_else(|| AppError::Internal("Virtual drive info is unavailable".to_string()))?;
+        let drive_info = match self.drive_mount_info() {
+            Ok(info) => info,
+            Err(error) => {
+                if matches!(
+                    &error,
+                    AppError::Msd(msd) if msd.code() == MsdErrorCode::MsdDriveNotInitialized
+                ) {
+                    self.monitor
+                        .report_error("Virtual drive not initialized", "drive_not_found")
+                        .await;
+                }
+                return Err(error);
+            }
+        };
+        state.drive_info = Some(drive_info.clone());
+
         let lun = Self::lowest_free_lun(&state)
-            .ok_or_else(|| AppError::BadRequest("Media slots are full".to_string()))?;
+            .ok_or_else(|| AppError::from(MsdErrorCode::MsdMediaSlotsFull))?;
 
         let media = MountedMedia::drive(lun, &drive_info);
         if let Err(e) = self.configure_media(&media).await {
@@ -246,6 +228,8 @@ impl MsdController {
             return Err(e);
         }
         state.mounted_media.push(media);
+        state.drive_info =
+            Some(drive_info.with_file_access(DriveFileAccess::BlockedWhileConnected));
 
         info!(
             "Mounted virtual drive on LUN {}: {}",
@@ -260,12 +244,21 @@ impl MsdController {
         Ok(())
     }
 
+    fn drive_mount_info(&self) -> Result<DriveInfo> {
+        VentoyDrive::new(self.drive_path.clone()).raw_info(DriveFileAccess::Unknown)
+    }
+
+    pub async fn set_drive_info(&self, drive_info: Option<DriveInfo>) {
+        self.state.write().await.drive_info = drive_info;
+        self.mark_device_info_dirty().await;
+    }
+
     async fn assert_available(&self, state: &MsdState) -> Result<()> {
         if !state.available {
             self.monitor
                 .report_error("MSD not available", "not_available")
                 .await;
-            return Err(AppError::Internal("MSD not available".to_string()));
+            return Err(MsdErrorCode::MsdUnavailable.into());
         }
         Ok(())
     }
@@ -286,31 +279,35 @@ impl MsdController {
     fn select_lun(state: &MsdState, requested_lun: Option<u8>) -> Result<u8> {
         let Some(lun) = requested_lun else {
             return Self::lowest_free_lun(state)
-                .ok_or_else(|| AppError::BadRequest("Media slots are full".to_string()));
+                .ok_or_else(|| AppError::from(MsdErrorCode::MsdMediaSlotsFull));
         };
 
         if lun >= state.disk_mode.capacity() {
-            return Err(AppError::BadRequest(format!(
-                "Media slot {} is outside the current disk mode capacity",
-                lun + 1
-            )));
+            return Err(MsdErrorCode::MsdInvalidRequest.into());
         }
         if state.mounted_media.iter().any(|media| media.lun == lun) {
-            return Err(AppError::BadRequest(format!(
-                "Media slot {} is already occupied",
-                lun + 1
-            )));
+            return Err(MsdErrorCode::MsdMediaSlotsFull.into());
         }
         Ok(lun)
     }
 
     fn reset_mounts_for_mode(state: &mut MsdState, disk_mode: DiskMode) {
+        if state
+            .mounted_media
+            .iter()
+            .any(|media| media.kind == MountedMediaKind::Drive)
+        {
+            state.drive_info = state
+                .drive_info
+                .take()
+                .map(|info| info.with_file_access(DriveFileAccess::Unknown));
+        }
         state.disk_mode = disk_mode;
         state.mounted_media.clear();
     }
 
     pub async fn set_disk_mode(&self, disk_mode: DiskMode) -> Result<bool> {
-        let _op_guard = self.operation_lock.write().await;
+        let _op_guard = self.try_operation()?;
         let previous_state = {
             let mut state = self.state.write().await;
             self.assert_available(&state).await?;
@@ -327,9 +324,10 @@ impl MsdController {
             self.otg_service
                 .set_msd_lun_capacity(disk_mode.capacity())
                 .await?;
-            self.otg_service.msd_function().await.ok_or_else(|| {
-                AppError::Internal("MSD function missing after OTG rebuild".to_string())
-            })
+            self.otg_service
+                .msd_function()
+                .await
+                .ok_or_else(|| AppError::from(MsdErrorCode::MsdOperationFailed))
         }
         .await;
 
@@ -349,7 +347,7 @@ impl MsdController {
                         .report_error(&error_msg, "disk_mode_rollback_failed")
                         .await;
                     self.mark_device_info_dirty().await;
-                    return Err(AppError::Internal(error_msg));
+                    return Err(MsdErrorCode::MsdOperationFailed.into());
                 }
 
                 let mut state = self.state.write().await;
@@ -360,7 +358,7 @@ impl MsdController {
                     .report_error(&error_msg, "disk_mode_switch_failed")
                     .await;
                 self.mark_device_info_dirty().await;
-                return Err(AppError::Internal(error_msg));
+                return Err(MsdErrorCode::MsdOperationFailed.into());
             }
         };
         *self.msd_function.write().await = Some(msd_function);
@@ -397,7 +395,7 @@ impl MsdController {
     where
         F: Fn(&MountedMedia) -> bool,
     {
-        let _op_guard = self.operation_lock.write().await;
+        let _op_guard = self.try_operation()?;
 
         let mut state = self.state.write().await;
         let Some(index) = state.mounted_media.iter().position(predicate) else {
@@ -408,6 +406,12 @@ impl MsdController {
 
         self.disconnect_lun(media.lun).await?;
         state.mounted_media.remove(index);
+        if media.kind == MountedMediaKind::Drive {
+            state.drive_info = state
+                .drive_info
+                .take()
+                .map(|info| info.with_file_access(DriveFileAccess::Unknown));
+        }
         info!("Unmounted media");
 
         drop(state);
@@ -419,25 +423,22 @@ impl MsdController {
     }
 
     async fn configure_media(&self, media: &MountedMedia) -> Result<()> {
-        let gadget_path = self.active_gadget_path().await?;
-        let msd_hold = self.msd_function.read().await;
-        let Some(ref msd) = *msd_hold else {
-            self.monitor
-                .report_error("MSD function not initialized", "not_initialized")
-                .await;
-            return Err(AppError::Internal(
-                "MSD function not initialized".to_string(),
-            ));
-        };
-        if let Err(e) = msd
-            .configure_lun_async(&gadget_path, media.lun, &Self::media_config(media))
+        if let Err(e) = self
+            .otg_service
+            .configure_msd_lun(media.lun, &Self::media_config(media))
             .await
         {
             let error_msg = format!("Failed to configure LUN {}: {}", media.lun, e);
             self.monitor
                 .report_error(&error_msg, "configfs_error")
                 .await;
-            return Err(e);
+            return Err(match e {
+                AppError::Msd(error) => AppError::Msd(error),
+                error => {
+                    warn!(%error, "Unclassified MSD media configuration failure");
+                    MsdErrorCode::MsdOperationFailed.into()
+                }
+            });
         }
         Ok(())
     }
@@ -447,7 +448,7 @@ impl MsdController {
         let msd_hold = self.msd_function.read().await;
         let msd = msd_hold
             .as_ref()
-            .ok_or_else(|| AppError::Internal("MSD function not initialized".to_string()))?;
+            .ok_or_else(|| AppError::from(MsdErrorCode::MsdUnavailable))?;
         msd.disconnect_lun_async(&gadget_path, lun).await
     }
 
@@ -455,9 +456,11 @@ impl MsdController {
         self.otg_service
             .set_msd_lun_capacity(previous_state.disk_mode.capacity())
             .await?;
-        let msd_function = self.otg_service.msd_function().await.ok_or_else(|| {
-            AppError::Internal("MSD function missing after OTG rollback".to_string())
-        })?;
+        let msd_function = self
+            .otg_service
+            .msd_function()
+            .await
+            .ok_or_else(|| AppError::from(MsdErrorCode::MsdOperationFailed))?;
         *self.msd_function.write().await = Some(msd_function);
         for media in &previous_state.mounted_media {
             self.configure_media(media).await?;
@@ -473,7 +476,7 @@ impl MsdController {
     }
 
     pub async fn disconnect(&self) -> Result<()> {
-        let _op_guard = self.operation_lock.write().await;
+        let _op_guard = self.try_operation()?;
 
         let mut state = self.state.write().await;
         if state.mounted_media.is_empty() {
@@ -488,10 +491,13 @@ impl MsdController {
                 for prior in &disconnected {
                     if let Err(restore_error) = self.configure_media(prior).await {
                         state.available = false;
-                        return Err(AppError::Internal(format!(
-                            "Failed to disconnect LUN {}: {error}; restore failed: {restore_error}",
-                            media.lun
-                        )));
+                        warn!(
+                            lun = media.lun,
+                            disconnect_error = %error,
+                            %restore_error,
+                            "Failed to restore MSD media after disconnect failure"
+                        );
+                        return Err(MsdErrorCode::MsdDisconnectFailed.into());
                     }
                 }
                 return Err(error);
@@ -499,6 +505,16 @@ impl MsdController {
             disconnected.push(media.clone());
         }
 
+        if state
+            .mounted_media
+            .iter()
+            .any(|media| media.kind == MountedMediaKind::Drive)
+        {
+            state.drive_info = state
+                .drive_info
+                .take()
+                .map(|info| info.with_file_access(DriveFileAccess::Unknown));
+        }
         state.mounted_media.clear();
         info!("Disconnected all mounted media");
 
@@ -520,16 +536,14 @@ impl MsdController {
     }
 
     pub async fn delete_image(&self, image_id: &str) -> Result<()> {
-        let _op_guard = self.operation_lock.write().await;
+        let _op_guard = self.try_operation()?;
         let state = self.state.read().await;
         if state
             .mounted_media
             .iter()
             .any(|media| media.kind == MountedMediaKind::Image && media.id == image_id)
         {
-            return Err(AppError::BadRequest(
-                "Cannot delete image while it is mounted".to_string(),
-            ));
+            return Err(MsdErrorCode::MsdMediaInUse.into());
         }
 
         ImageManager::new(self.images_path.clone()).delete(image_id)
@@ -540,6 +554,12 @@ impl MsdController {
         url: String,
         filename: Option<String>,
     ) -> Result<DownloadProgress> {
+        let parsed_url =
+            reqwest::Url::parse(&url).map_err(|_| AppError::from(MsdErrorCode::MsdInvalidUrl))?;
+        if !matches!(parsed_url.scheme(), "http" | "https") {
+            return Err(MsdErrorCode::MsdInvalidUrl.into());
+        }
+
         let download_id = uuid::Uuid::new_v4().to_string();
         let cancel_token = CancellationToken::new();
 
@@ -560,7 +580,7 @@ impl MsdController {
             total_bytes: None,
             progress_pct: None,
             status: DownloadStatus::Started,
-            error: None,
+            error_code: None,
         };
 
         self.publish_event(crate::events::SystemEvent::MsdDownloadProgress {
@@ -571,6 +591,7 @@ impl MsdController {
             total_bytes: None,
             progress_pct: None,
             status: "started".to_string(),
+            error_code: None,
         })
         .await;
 
@@ -600,6 +621,7 @@ impl MsdController {
                         total_bytes: total,
                         progress_pct,
                         status: "in_progress".to_string(),
+                        error_code: None,
                     });
                 }
             };
@@ -624,11 +646,16 @@ impl MsdController {
                             total_bytes: Some(image_info.size),
                             progress_pct: Some(100.0),
                             status: "completed".to_string(),
+                            error_code: None,
                         });
                     }
                 }
                 Err(e) => {
-                    warn!("Download failed: {}", e);
+                    warn!(error = %e, "MSD image download failed");
+                    let code = match e {
+                        AppError::Msd(error) => error.code(),
+                        _ => MsdErrorCode::MsdOperationFailed,
+                    };
                     if let Some(ref bus) = events {
                         bus.publish(crate::events::SystemEvent::MsdDownloadProgress {
                             download_id: download_id_clone,
@@ -637,7 +664,8 @@ impl MsdController {
                             bytes_downloaded: 0,
                             total_bytes: None,
                             progress_pct: None,
-                            status: format!("failed: {}", e),
+                            status: "failed".to_string(),
+                            error_code: Some(code.as_str().to_string()),
                         });
                     }
                 }
@@ -655,10 +683,7 @@ impl MsdController {
             info!("Download cancelled: {}", download_id);
             Ok(())
         } else {
-            Err(AppError::NotFound(format!(
-                "Download not found: {}",
-                download_id
-            )))
+            Err(MsdErrorCode::MsdResourceNotFound.into())
         }
     }
 
@@ -666,7 +691,13 @@ impl MsdController {
         self.otg_service
             .gadget_path()
             .await
-            .ok_or_else(|| AppError::Internal("OTG gadget path is not available".to_string()))
+            .ok_or_else(|| AppError::from(MsdErrorCode::MsdUnavailable))
+    }
+
+    fn try_operation(&self) -> Result<tokio::sync::RwLockWriteGuard<'_, ()>> {
+        self.operation_lock
+            .try_write()
+            .map_err(|_| MsdErrorCode::MsdOperationInProgress.into())
     }
 
     pub async fn shutdown(&self) -> Result<()> {
@@ -712,6 +743,18 @@ mod tests {
         assert!(controller.drive_path.ends_with("ventoy.img"));
     }
 
+    #[tokio::test]
+    async fn concurrent_operations_have_a_stable_error_code() {
+        let temp_dir = TempDir::new().unwrap();
+        let controller = MsdController::new(Arc::new(OtgService::new()), temp_dir.path());
+        let _guard = controller.operation_lock.write().await;
+
+        assert!(matches!(
+            controller.try_operation().unwrap_err(),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdOperationInProgress
+        ));
+    }
+
     #[tokio::test]
     async fn test_state_default() {
         let temp_dir = TempDir::new().unwrap();
@@ -726,6 +769,29 @@ mod tests {
         assert!(state.mounted_media.is_empty());
     }
 
+    #[tokio::test]
+    async fn drive_mount_metadata_ignores_cached_drive_info() {
+        let temp_dir = TempDir::new().unwrap();
+        let controller = MsdController::new(Arc::new(OtgService::new()), temp_dir.path());
+        std::fs::create_dir_all(&controller.ventoy_dir).unwrap();
+        std::fs::write(&controller.drive_path, vec![0u8; 128]).unwrap();
+        controller.state.write().await.drive_info = Some(DriveInfo::from_raw(
+            controller.drive_path.clone(),
+            64,
+            DriveFileAccess::Available,
+        ));
+
+        std::fs::write(&controller.drive_path, vec![0u8; 256]).unwrap();
+        let info = controller.drive_mount_info().unwrap();
+
+        assert_eq!(info.size, 256);
+        assert_eq!(info.used, None);
+        assert_eq!(info.file_access, DriveFileAccess::Unknown);
+        let media = MountedMedia::drive(0, &info);
+        let config = MsdController::media_config(&media);
+        assert_eq!(config.file, controller.drive_path);
+    }
+
     #[test]
     fn single_disk_mode_only_exposes_lun_zero() {
         let mut state = MsdState::default();
@@ -783,14 +849,14 @@ mod tests {
             .push(MountedMedia::image(3, &image, false, true));
 
         assert_eq!(MsdController::select_lun(&state, Some(5)).unwrap(), 5);
-        assert!(MsdController::select_lun(&state, Some(3))
-            .unwrap_err()
-            .to_string()
-            .contains("already occupied"));
-        assert!(MsdController::select_lun(&state, Some(8))
-            .unwrap_err()
-            .to_string()
-            .contains("outside"));
+        assert!(matches!(
+            MsdController::select_lun(&state, Some(3)).unwrap_err(),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdMediaSlotsFull
+        ));
+        assert!(matches!(
+            MsdController::select_lun(&state, Some(8)).unwrap_err(),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdInvalidRequest
+        ));
     }
 
     #[test]
@@ -824,13 +890,7 @@ mod tests {
         let temp_dir = TempDir::new().unwrap();
         let drive_path = temp_dir.path().join("ventoy.img");
         std::fs::write(&drive_path, b"drive").unwrap();
-        let drive = DriveInfo {
-            size: 5,
-            used: 0,
-            free: 5,
-            initialized: true,
-            path: drive_path,
-        };
+        let drive = DriveInfo::from_raw(drive_path, 5, DriveFileAccess::Unknown);
         let mut state = MsdState::default();
         MsdController::reset_mounts_for_mode(&mut state, DiskMode::Multi);
         state.mounted_media.push(MountedMedia::drive(0, &drive));
@@ -882,13 +942,11 @@ mod tests {
         let image_path = temp_dir.path().join("test.img");
         std::fs::write(&image_path, b"img").unwrap();
         let image = ImageInfo::new("test".into(), "test.img".into(), image_path, 3);
-        let drive = DriveInfo {
-            size: 5,
-            used: 0,
-            free: 5,
-            initialized: true,
-            path: temp_dir.path().join("ventoy.img"),
-        };
+        let drive = DriveInfo::from_raw(
+            temp_dir.path().join("ventoy.img"),
+            5,
+            DriveFileAccess::Unknown,
+        );
         let mut state = MsdState::default();
         state
             .mounted_media

src/msd/image.rs

@@ -6,10 +6,10 @@ use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
 use time::OffsetDateTime;
 use tokio::io::AsyncWriteExt;
-use tracing::info;
+use tracing::{info, warn};
 
 use super::types::ImageInfo;
-use crate::error::{AppError, Result};
+use crate::error::{AppError, MsdErrorCode, Result};
 
 const MAX_IMAGE_SIZE: u64 = 32 * 1024 * 1024 * 1024;
 
@@ -28,7 +28,7 @@ impl ImageManager {
 
     pub fn ensure_dir(&self) -> Result<()> {
         fs::create_dir_all(&self.images_path)
-            .map_err(|e| AppError::Internal(format!("Failed to create images directory: {}", e)))?;
+            .map_err(|error| storage_io_error("create images directory", error))?;
         Ok(())
     }
 
@@ -38,11 +38,9 @@ impl ImageManager {
         let mut images = Vec::new();
 
         for entry in fs::read_dir(&self.images_path)
-            .map_err(|e| AppError::Internal(format!("Failed to read images directory: {}", e)))?
+            .map_err(|error| storage_io_error("read images directory", error))?
         {
-            let entry = entry.map_err(|e| {
-                AppError::Internal(format!("Failed to read directory entry: {}", e))
-            })?;
+            let entry = entry.map_err(|error| storage_io_error("read image entry", error))?;
 
             let path = entry.path();
             if path.is_file() {
@@ -88,13 +86,13 @@ impl ImageManager {
                 return Ok(image);
             }
         }
-        Err(AppError::NotFound(format!("Image not found: {}", id)))
+        Err(MsdErrorCode::MsdResourceNotFound.into())
     }
 
     pub fn get_by_name(&self, name: &str) -> Result<ImageInfo> {
         let path = self.images_path.join(name);
         self.get_image_info(&path)
-            .ok_or_else(|| AppError::NotFound(format!("Image not found: {}", name)))
+            .ok_or_else(|| MsdErrorCode::MsdResourceNotFound.into())
     }
 
     #[cfg(test)]
@@ -103,30 +101,24 @@ impl ImageManager {
 
         let name = sanitize_filename(name);
         if name.is_empty() {
-            return Err(AppError::Internal("Invalid filename".to_string()));
+            return Err(MsdErrorCode::MsdInvalidRequest.into());
         }
 
         if data.len() as u64 > MAX_IMAGE_SIZE {
-            return Err(AppError::Internal(format!(
-                "Image too large. Maximum size: {} GB",
-                MAX_IMAGE_SIZE / 1024 / 1024 / 1024
-            )));
+            return Err(MsdErrorCode::MsdImageTooLarge.into());
         }
 
         let path = self.images_path.join(&name);
         if path.exists() {
-            return Err(AppError::Internal(format!(
-                "Image already exists: {}",
-                name
-            )));
+            return Err(MsdErrorCode::MsdResourceAlreadyExists.into());
         }
 
-        let mut file = fs::File::create(&path)
-            .map_err(|e| AppError::Internal(format!("Failed to create image file: {}", e)))?;
+        let mut file =
+            fs::File::create(&path).map_err(|error| storage_io_error("create image", error))?;
 
-        file.write_all(data).map_err(|e| {
+        file.write_all(data).map_err(|error| {
             let _ = fs::remove_file(&path);
-            AppError::Internal(format!("Failed to write image data: {}", e))
+            storage_io_error("write image", error)
         })?;
 
         info!("Created image: {} ({} bytes)", name, data.len());
@@ -143,7 +135,7 @@ impl ImageManager {
 
         let name = sanitize_filename(name);
         if name.is_empty() {
-            return Err(AppError::Internal("Invalid filename".to_string()));
+            return Err(MsdErrorCode::MsdInvalidRequest.into());
         }
 
         let temp_name = format!(".upload_{}", uuid::Uuid::new_v4());
@@ -151,48 +143,41 @@ impl ImageManager {
         let final_path = self.images_path.join(&name);
 
         if final_path.exists() {
-            return Err(AppError::Internal(format!(
-                "Image already exists: {}",
-                name
-            )));
+            return Err(MsdErrorCode::MsdResourceAlreadyExists.into());
         }
 
         let mut file = tokio::fs::File::create(&temp_path)
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to create temp file: {}", e)))?;
+            .map_err(|error| storage_io_error("create image upload", error))?;
 
         let mut bytes_written: u64 = 0;
 
-        while let Some(chunk) = field
-            .chunk()
-            .await
-            .map_err(|e| AppError::Internal(format!("Failed to read upload chunk: {}", e)))?
-        {
+        while let Some(chunk) = field.chunk().await.map_err(|error| {
+            warn!(%error, "Failed to read MSD image upload chunk");
+            AppError::from(MsdErrorCode::MsdOperationFailed)
+        })? {
             bytes_written += chunk.len() as u64;
             if bytes_written > MAX_IMAGE_SIZE {
                 drop(file);
                 let _ = tokio::fs::remove_file(&temp_path).await;
-                return Err(AppError::Internal(format!(
-                    "Image too large. Maximum size: {} GB",
-                    MAX_IMAGE_SIZE / 1024 / 1024 / 1024
-                )));
+                return Err(MsdErrorCode::MsdImageTooLarge.into());
             }
 
             file.write_all(&chunk)
                 .await
-                .map_err(|e| AppError::Internal(format!("Failed to write chunk: {}", e)))?;
+                .map_err(|error| storage_io_error("write image upload", error))?;
         }
 
         file.flush()
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to flush file: {}", e)))?;
+            .map_err(|error| storage_io_error("flush image upload", error))?;
         drop(file);
 
         tokio::fs::rename(&temp_path, &final_path)
             .await
-            .map_err(|e| {
+            .map_err(|error| {
                 let _ = std::fs::remove_file(&temp_path);
-                AppError::Internal(format!("Failed to rename temp file: {}", e))
+                storage_io_error("commit image upload", error)
             })?;
 
         info!(
@@ -206,8 +191,7 @@ impl ImageManager {
     pub fn delete(&self, id: &str) -> Result<()> {
         let image = self.get(id)?;
 
-        fs::remove_file(&image.path)
-            .map_err(|e| AppError::Internal(format!("Failed to delete image: {}", e)))?;
+        fs::remove_file(&image.path).map_err(|error| storage_io_error("delete image", error))?;
 
         info!("Deleted image: {}", image.name);
         Ok(())
@@ -224,8 +208,11 @@ impl ImageManager {
     {
         self.ensure_dir()?;
 
-        let parsed_url = reqwest::Url::parse(url)
-            .map_err(|e| AppError::BadRequest(format!("Invalid URL: {}", e)))?;
+        let parsed_url =
+            reqwest::Url::parse(url).map_err(|_| AppError::from(MsdErrorCode::MsdInvalidUrl))?;
+        if !matches!(parsed_url.scheme(), "http" | "https") {
+            return Err(MsdErrorCode::MsdInvalidUrl.into());
+        }
 
         info!("Starting download from: {}", url);
 
@@ -233,19 +220,17 @@ impl ImageManager {
             .timeout(std::time::Duration::from_secs(3600))
             .connect_timeout(std::time::Duration::from_secs(30))
             .build()
-            .map_err(|e| AppError::Internal(format!("Failed to create HTTP client: {}", e)))?;
+            .map_err(|error| remote_download_error("create HTTP client", error))?;
 
         let head_response = client
             .head(url)
             .send()
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to connect: {}", e)))?;
+            .map_err(|error| remote_download_error("send HEAD request", error))?;
 
         if !head_response.status().is_success() {
-            return Err(AppError::Internal(format!(
-                "Server returned error: {}",
-                head_response.status()
-            )));
+            warn!(status = %head_response.status(), "MSD image HEAD request failed");
+            return Err(MsdErrorCode::MsdRemoteDownloadFailed.into());
         }
 
         let total_size = head_response
@@ -256,11 +241,7 @@ impl ImageManager {
 
         if let Some(size) = total_size {
             if size > MAX_IMAGE_SIZE {
-                return Err(AppError::BadRequest(format!(
-                    "File too large: {} bytes (max {} GB)",
-                    size,
-                    MAX_IMAGE_SIZE / 1024 / 1024 / 1024
-                )));
+                return Err(MsdErrorCode::MsdImageTooLarge.into());
             }
         }
 
@@ -284,17 +265,12 @@ impl ImageManager {
         };
 
         if final_filename.is_empty() {
-            return Err(AppError::BadRequest(
-                "Could not determine filename".to_string(),
-            ));
+            return Err(MsdErrorCode::MsdInvalidRequest.into());
         }
 
         let final_path = self.images_path.join(&final_filename);
         if final_path.exists() {
-            return Err(AppError::BadRequest(format!(
-                "Image already exists: {}",
-                final_filename
-            )));
+            return Err(MsdErrorCode::MsdResourceAlreadyExists.into());
         }
 
         let temp_filename = format!(".download_{}", uuid::Uuid::new_v4());
@@ -304,13 +280,11 @@ impl ImageManager {
             .get(url)
             .send()
             .await
-            .map_err(|e| AppError::Internal(format!("Download failed: {}", e)))?;
+            .map_err(|error| remote_download_error("send GET request", error))?;
 
         if !response.status().is_success() {
-            return Err(AppError::Internal(format!(
-                "Download failed: HTTP {}",
-                response.status()
-            )));
+            warn!(status = %response.status(), "MSD image GET request failed");
+            return Err(MsdErrorCode::MsdRemoteDownloadFailed.into());
         }
 
         let content_length = response
@@ -322,7 +296,7 @@ impl ImageManager {
 
         let mut file = tokio::fs::File::create(&temp_path)
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to create temp file: {}", e)))?;
+            .map_err(|error| storage_io_error("create image download", error))?;
 
         let mut stream = response.bytes_stream();
         let mut downloaded: u64 = 0;
@@ -334,11 +308,11 @@ impl ImageManager {
 
         while let Some(chunk_result) = stream.next().await {
             let chunk =
-                chunk_result.map_err(|e| AppError::Internal(format!("Download error: {}", e)))?;
+                chunk_result.map_err(|error| remote_download_error("read response body", error))?;
 
-            file.write_all(&chunk).await.map_err(|e| {
+            file.write_all(&chunk).await.map_err(|error| {
                 let _ = std::fs::remove_file(&temp_path);
-                AppError::Internal(format!("Failed to write data: {}", e))
+                storage_io_error("write image download", error)
             })?;
 
             downloaded += chunk.len() as u64;
@@ -360,29 +334,29 @@ impl ImageManager {
 
         file.flush()
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to flush file: {}", e)))?;
+            .map_err(|error| storage_io_error("flush image download", error))?;
         drop(file);
 
         let metadata = tokio::fs::metadata(&temp_path)
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to read file metadata: {}", e)))?;
+            .map_err(|error| storage_io_error("read downloaded image metadata", error))?;
 
         if let Some(expected) = content_length {
             if metadata.len() != expected {
                 let _ = tokio::fs::remove_file(&temp_path).await;
-                return Err(AppError::Internal(format!(
-                    "Download incomplete: got {} bytes, expected {}",
-                    metadata.len(),
-                    expected
-                )));
+                warn!(
+                    actual = metadata.len(),
+                    expected, "MSD image download was incomplete"
+                );
+                return Err(MsdErrorCode::MsdDownloadIncomplete.into());
             }
         }
 
         tokio::fs::rename(&temp_path, &final_path)
             .await
-            .map_err(|e| {
+            .map_err(|error| {
                 let _ = std::fs::remove_file(&temp_path);
-                AppError::Internal(format!("Failed to move file: {}", e))
+                storage_io_error("commit image download", error)
             })?;
 
         info!(
@@ -395,6 +369,26 @@ impl ImageManager {
     }
 }
 
+fn storage_io_error(operation: &'static str, error: std::io::Error) -> AppError {
+    warn!(operation, %error, "MSD storage operation failed");
+    #[cfg(unix)]
+    let code = match error.raw_os_error() {
+        Some(libc::EFBIG) => MsdErrorCode::MsdImageTooLarge,
+        Some(libc::ENOSPC) => MsdErrorCode::MsdStorageFull,
+        Some(libc::EROFS) => MsdErrorCode::MsdStorageReadOnly,
+        Some(libc::EACCES | libc::EPERM) => MsdErrorCode::MsdStoragePermissionDenied,
+        _ => MsdErrorCode::MsdOperationFailed,
+    };
+    #[cfg(not(unix))]
+    let code = MsdErrorCode::MsdOperationFailed;
+    code.into()
+}
+
+fn remote_download_error(operation: &'static str, error: reqwest::Error) -> AppError {
+    warn!(operation, %error, "MSD remote download failed");
+    MsdErrorCode::MsdRemoteDownloadFailed.into()
+}
+
 fn stable_image_id_from_filename(name: &str) -> String {
     let mut hash: u64 = 0;
     for (i, byte) in name.bytes().enumerate() {
@@ -490,4 +484,18 @@ mod tests {
 
         assert!(manager.list().unwrap().is_empty());
     }
+
+    #[test]
+    fn classifies_storage_io_errors() {
+        for (errno, expected) in [
+            (libc::EFBIG, MsdErrorCode::MsdImageTooLarge),
+            (libc::ENOSPC, MsdErrorCode::MsdStorageFull),
+            (libc::EROFS, MsdErrorCode::MsdStorageReadOnly),
+            (libc::EACCES, MsdErrorCode::MsdStoragePermissionDenied),
+            (libc::EPERM, MsdErrorCode::MsdStoragePermissionDenied),
+        ] {
+            let error = storage_io_error("test", std::io::Error::from_raw_os_error(errno));
+            assert!(matches!(error, AppError::Msd(error) if error.code() == expected));
+        }
+    }
 }

src/msd/mod.rs

@@ -8,10 +8,11 @@ pub use controller::MsdController;
 pub use image::ImageManager;
 pub use monitor::MsdHealthMonitor;
 pub use types::{
-    DiskMode, DiskModeRequest, DownloadProgress, DownloadStatus, DriveFile, DriveInfo,
-    DriveInitRequest, ImageDownloadRequest, ImageInfo, ImageMountRequest, MountedMedia,
+    DiskMode, DiskModeRequest, DownloadProgress, DownloadStatus, DriveFile, DriveFileAccess,
+    DriveInfo, DriveInitRequest, ImageDownloadRequest, ImageInfo, ImageMountRequest, MountedMedia,
     MountedMediaKind, MsdState, MsdStateResponse, MULTI_DISK_MSD_LUNS, SINGLE_DISK_MSD_LUNS,
 };
 pub use ventoy_drive::{VentoyDrive, MIN_DRIVE_SIZE_MB};
 
+pub use crate::error::{MsdError, MsdErrorCode};
 pub use crate::otg::{MsdFunction, MsdLunConfig};

src/msd/types.rs

@@ -156,26 +156,44 @@ impl DiskMode {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DriveFileAccess {
+    Available,
+    Unsupported,
+    BlockedWhileConnected,
+    Unknown,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DriveInfo {
     pub size: u64,
-    pub used: u64,
-    pub free: u64,
+    pub used: Option<u64>,
+    pub free: Option<u64>,
     pub initialized: bool,
+    pub file_access: DriveFileAccess,
     #[serde(skip_serializing)]
     pub path: PathBuf,
 }
 
 impl DriveInfo {
-    pub fn new(path: PathBuf, size: u64) -> Self {
+    pub fn from_raw(path: PathBuf, size: u64, file_access: DriveFileAccess) -> Self {
         Self {
             size,
-            used: 0,
-            free: size,
-            initialized: false,
+            used: None,
+            free: None,
+            initialized: true,
+            file_access,
             path,
         }
     }
+
+    pub fn with_file_access(mut self, file_access: DriveFileAccess) -> Self {
+        self.used = None;
+        self.free = None;
+        self.file_access = file_access;
+        self
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -235,7 +253,7 @@ pub struct DownloadProgress {
     pub total_bytes: Option<u64>,
     pub progress_pct: Option<f32>,
     pub status: DownloadStatus,
-    pub error: Option<String>,
+    pub error_code: Option<String>,
 }
 
 #[cfg(test)]
@@ -267,4 +285,36 @@ mod tests {
         assert!(json.get("current_image").is_none());
         assert!(json.get("slots").is_none());
     }
+
+    #[test]
+    fn drive_info_json_has_stable_nullable_space_and_file_access() {
+        let info = DriveInfo::from_raw(
+            PathBuf::from("/tmp/drive.img"),
+            4096,
+            DriveFileAccess::Unsupported,
+        );
+
+        let value = serde_json::to_value(info).unwrap();
+        assert_eq!(value["size"], 4096);
+        assert_eq!(value["used"], serde_json::Value::Null);
+        assert_eq!(value["free"], serde_json::Value::Null);
+        assert_eq!(value["initialized"], true);
+        assert_eq!(value["file_access"], "unsupported");
+        assert!(value.get("path").is_none());
+    }
+
+    #[test]
+    fn drive_file_access_serializes_all_public_states() {
+        for (access, expected) in [
+            (DriveFileAccess::Available, "available"),
+            (DriveFileAccess::Unsupported, "unsupported"),
+            (
+                DriveFileAccess::BlockedWhileConnected,
+                "blocked_while_connected",
+            ),
+            (DriveFileAccess::Unknown, "unknown"),
+        ] {
+            assert_eq!(serde_json::to_value(access).unwrap(), expected);
+        }
+    }
 }

src/msd/ventoy_drive.rs

@@ -1,12 +1,12 @@
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use tokio::sync::RwLock;
-use tracing::info;
+use tracing::{info, warn};
 
 use ventoy_img::{FileInfo as VentoyFileInfo, VentoyError, VentoyImage};
 
-use super::types::{DriveFile, DriveInfo};
-use crate::error::{AppError, Result};
+use super::types::{DriveFile, DriveFileAccess, DriveInfo};
+use crate::error::{AppError, MsdErrorCode, Result};
 
 const STREAM_CHUNK_SIZE: usize = 64 * 1024;
 
@@ -35,19 +35,15 @@ impl VentoyDrive {
         &self.path
     }
 
-    /// Returns just the raw file size without attempting to parse the filesystem.
-    /// Used as a fallback when the image has been reformatted to an unsupported
-    /// filesystem (e.g. NTFS/exFAT) that VentoyImage cannot open.
-    pub fn raw_size(&self) -> Option<u64> {
-        std::fs::metadata(&self.path).ok().map(|m| m.len())
+    /// Read and validate only the backing file metadata, without parsing its
+    /// partition table or filesystem.
+    pub fn raw_info(&self, file_access: DriveFileAccess) -> Result<DriveInfo> {
+        raw_drive_info(&self.path, file_access)
     }
 
     pub async fn init(&self, size_mb: u32) -> Result<DriveInfo> {
         if size_mb < MIN_DRIVE_SIZE_MB {
-            return Err(AppError::BadRequest(format!(
-                "Drive size must be at least {} MB",
-                MIN_DRIVE_SIZE_MB
-            )));
+            return Err(MsdErrorCode::MsdDriveSizeInvalid.into());
         }
         let size_str = format!("{}M", size_mb);
         let path = self.path.clone();
@@ -59,38 +55,42 @@ impl VentoyDrive {
             VentoyImage::create(&path, &size_str, DEFAULT_LABEL).map_err(drive_init_error)?;
 
             let metadata = std::fs::metadata(&path)
-                .map_err(|e| AppError::Internal(format!("Failed to read drive metadata: {}", e)))?;
+                .map_err(|error| drive_io_error("read initialized drive metadata", error))?;
 
             Ok::<DriveInfo, AppError>(DriveInfo {
                 size: metadata.len(),
-                used: 0,
-                free: metadata.len(),
+                used: Some(0),
+                free: Some(metadata.len()),
                 initialized: true,
+                file_access: DriveFileAccess::Available,
                 path,
             })
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))??;
+        .map_err(|error| task_error("initialize virtual drive", error))??;
 
         info!("Ventoy drive created successfully");
         Ok(info)
     }
 
     pub async fn info(&self) -> Result<DriveInfo> {
-        if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
-        }
-
         let path = self.path.clone();
         let _lock = self.lock.read().await;
 
         tokio::task::spawn_blocking(move || {
-            let metadata = std::fs::metadata(&path)
-                .map_err(|e| AppError::Internal(format!("Failed to read drive metadata: {}", e)))?;
+            let raw = raw_drive_info(&path, DriveFileAccess::Unsupported)?;
 
-            let image = VentoyImage::open(&path).map_err(ventoy_to_app_error)?;
+            let image = match VentoyImage::open(&path) {
+                Ok(image) => image,
+                Err(error) if is_unsupported_filesystem_error(&error) => return Ok(raw),
+                Err(error) => return Err(ventoy_to_app_error(error)),
+            };
 
-            let files = image.list_files_recursive().map_err(ventoy_to_app_error)?;
+            let files = match image.list_files_recursive() {
+                Ok(files) => files,
+                Err(error) if is_unsupported_filesystem_error(&error) => return Ok(raw),
+                Err(error) => return Err(ventoy_to_app_error(error)),
+            };
 
             let used: u64 = files
                 .iter()
@@ -98,24 +98,25 @@ impl VentoyDrive {
                 .map(|f| f.size)
                 .sum();
 
-            let size = metadata.len();
+            let size = raw.size;
             let free = size.saturating_sub(used);
 
             Ok(DriveInfo {
                 size,
-                used,
-                free,
+                used: Some(used),
+                free: Some(free),
                 initialized: true,
+                file_access: DriveFileAccess::Available,
                 path,
             })
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))?
+        .map_err(|error| task_error("read virtual drive info", error))?
     }
 
     pub async fn list_files(&self, dir_path: &str) -> Result<Vec<DriveFile>> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let path = self.path.clone();
@@ -138,7 +139,7 @@ impl VentoyDrive {
                 .collect())
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))?
+        .map_err(|error| task_error("list virtual drive files", error))?
     }
 
     pub async fn write_file_from_multipart_field(
@@ -147,7 +148,7 @@ impl VentoyDrive {
         mut field: axum::extract::multipart::Field<'_>,
     ) -> Result<u64> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let temp_dir = self.path.parent().unwrap_or(Path::new("/tmp"));
@@ -156,24 +157,23 @@ impl VentoyDrive {
 
         let mut temp_file = tokio::fs::File::create(&temp_path)
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to create temp file: {}", e)))?;
+            .map_err(|error| drive_io_error("create virtual drive upload", error))?;
 
         let mut bytes_written: u64 = 0;
 
-        while let Some(chunk) = field
-            .chunk()
-            .await
-            .map_err(|e| AppError::Internal(format!("Failed to read upload chunk: {}", e)))?
-        {
+        while let Some(chunk) = field.chunk().await.map_err(|error| {
+            warn!(%error, "Failed to read virtual drive upload chunk");
+            AppError::from(MsdErrorCode::MsdOperationFailed)
+        })? {
             bytes_written += chunk.len() as u64;
             tokio::io::AsyncWriteExt::write_all(&mut temp_file, &chunk)
                 .await
-                .map_err(|e| AppError::Internal(format!("Failed to write chunk: {}", e)))?;
+                .map_err(|error| drive_io_error("write virtual drive upload", error))?;
         }
 
         tokio::io::AsyncWriteExt::flush(&mut temp_file)
             .await
-            .map_err(|e| AppError::Internal(format!("Failed to flush temp file: {}", e)))?;
+            .map_err(|error| drive_io_error("flush virtual drive upload", error))?;
         drop(temp_file);
 
         let path = self.path.clone();
@@ -191,7 +191,7 @@ impl VentoyDrive {
             Ok::<(), AppError>(())
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))?;
+        .map_err(|error| task_error("write virtual drive file", error))?;
 
         let _ = tokio::fs::remove_file(&temp_path).await;
 
@@ -202,7 +202,7 @@ impl VentoyDrive {
     #[cfg(test)]
     pub async fn read_file(&self, file_path: &str) -> Result<Vec<u8>> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let path = self.path.clone();
@@ -215,12 +215,12 @@ impl VentoyDrive {
             image.read_file(&file_path).map_err(ventoy_to_app_error)
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))?
+        .map_err(|error| task_error("read virtual drive file", error))?
     }
 
     pub async fn get_file_info(&self, file_path: &str) -> Result<Option<DriveFile>> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let path = self.path.clone();
@@ -234,7 +234,7 @@ impl VentoyDrive {
                 .map_err(ventoy_to_app_error)
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))??;
+        .map_err(|error| task_error("read virtual drive file information", error))??;
 
         Ok(info.map(|f| DriveFile {
             name: f.name,
@@ -253,19 +253,16 @@ impl VentoyDrive {
         tokio::sync::mpsc::Receiver<std::result::Result<bytes::Bytes, std::io::Error>>,
     )> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let file_info = self
             .get_file_info(file_path)
             .await?
-            .ok_or_else(|| AppError::NotFound(format!("File not found: {}", file_path)))?;
+            .ok_or_else(|| AppError::from(MsdErrorCode::MsdResourceNotFound))?;
 
         if file_info.is_dir {
-            return Err(AppError::BadRequest(format!(
-                "'{}' is a directory",
-                file_path
-            )));
+            return Err(MsdErrorCode::MsdInvalidRequest.into());
         }
 
         let file_size = file_info.size;
@@ -300,7 +297,7 @@ impl VentoyDrive {
 
     pub async fn mkdir(&self, dir_path: &str) -> Result<()> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let path = self.path.clone();
@@ -315,12 +312,12 @@ impl VentoyDrive {
                 .map_err(ventoy_to_app_error)
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))?
+        .map_err(|error| task_error("create virtual drive directory", error))?
     }
 
     pub async fn delete(&self, path_to_delete: &str) -> Result<()> {
         if !self.exists() {
-            return Err(AppError::Internal("Drive not initialized".to_string()));
+            return Err(MsdErrorCode::MsdDriveNotInitialized.into());
         }
 
         let path = self.path.clone();
@@ -335,22 +332,52 @@ impl VentoyDrive {
                 .map_err(ventoy_to_app_error)
         })
         .await
-        .map_err(|e| AppError::Internal(format!("Task join error: {}", e)))?
+        .map_err(|error| task_error("delete virtual drive resource", error))?
     }
 }
 
-fn ventoy_to_app_error(err: VentoyError) -> AppError {
-    match err {
-        VentoyError::Io(e) => AppError::Io(e),
-        VentoyError::InvalidSize(s) => AppError::BadRequest(format!("Invalid size: {}", s)),
-        VentoyError::SizeParseError(s) => AppError::BadRequest(format!("Size parse error: {}", s)),
-        VentoyError::FilesystemError(s) => AppError::Internal(format!("Filesystem error: {}", s)),
-        VentoyError::ImageError(s) => AppError::Internal(format!("Image error: {}", s)),
-        VentoyError::FileNotFound(s) => AppError::NotFound(format!("File not found: {}", s)),
-        VentoyError::ResourceNotFound(s) => {
-            AppError::Internal(format!("Resource not found: {}", s))
+fn raw_drive_info(path: &Path, file_access: DriveFileAccess) -> Result<DriveInfo> {
+    let metadata = std::fs::metadata(path).map_err(|error| {
+        if error.kind() == std::io::ErrorKind::NotFound {
+            AppError::from(MsdErrorCode::MsdDriveNotInitialized)
+        } else {
+            drive_io_error("read drive metadata", error)
+        }
+    })?;
+
+    if !metadata.is_file() || metadata.len() == 0 {
+        return Err(MsdErrorCode::MsdDriveSizeInvalid.into());
+    }
+
+    Ok(DriveInfo::from_raw(
+        path.to_path_buf(),
+        metadata.len(),
+        file_access,
+    ))
+}
+
+fn is_unsupported_filesystem_error(error: &VentoyError) -> bool {
+    matches!(
+        error,
+        VentoyError::FilesystemError(_)
+            | VentoyError::ImageError(_)
+            | VentoyError::PartitionError(_)
+    )
+}
+
+fn ventoy_to_app_error(err: VentoyError) -> AppError {
+    warn!(%err, "Virtual drive filesystem operation failed");
+    match err {
+        VentoyError::Io(error) => drive_io_error("access virtual drive", error),
+        VentoyError::InvalidSize(_) | VentoyError::SizeParseError(_) => {
+            MsdErrorCode::MsdDriveSizeInvalid.into()
+        }
+        VentoyError::FilesystemError(_)
+        | VentoyError::ImageError(_)
+        | VentoyError::PartitionError(_) => MsdErrorCode::MsdDriveFilesystemUnsupported.into(),
+        VentoyError::FileNotFound(_) | VentoyError::ResourceNotFound(_) => {
+            MsdErrorCode::MsdResourceNotFound.into()
         }
-        VentoyError::PartitionError(s) => AppError::Internal(format!("Partition error: {}", s)),
     }
 }
 
@@ -361,21 +388,35 @@ fn drive_init_error(err: VentoyError) -> AppError {
 
     #[cfg(unix)]
     match error.raw_os_error() {
-        Some(libc::EFBIG) => AppError::BadRequest(
-            "MSD directory filesystem does not support a virtual drive file of this size".into(),
-        ),
-        Some(libc::ENOSPC) => AppError::BadRequest(
-            "MSD directory does not have enough free space for the virtual drive".into(),
-        ),
-        Some(libc::EROFS) => AppError::BadRequest("MSD directory filesystem is read-only".into()),
-        Some(libc::EACCES | libc::EPERM) => AppError::BadRequest(
-            "One-KVM does not have permission to write to the MSD directory".into(),
-        ),
-        _ => AppError::Io(error),
+        Some(libc::EFBIG) => MsdErrorCode::MsdDriveSizeInvalid.into(),
+        Some(libc::ENOSPC) => MsdErrorCode::MsdStorageFull.into(),
+        Some(libc::EROFS) => MsdErrorCode::MsdStorageReadOnly.into(),
+        Some(libc::EACCES | libc::EPERM) => MsdErrorCode::MsdStoragePermissionDenied.into(),
+        _ => drive_io_error("initialize virtual drive", error),
     }
 
     #[cfg(not(unix))]
-    AppError::Io(error)
+    drive_io_error("initialize virtual drive", error)
+}
+
+fn drive_io_error(operation: &'static str, error: std::io::Error) -> AppError {
+    warn!(operation, %error, "Virtual drive storage operation failed");
+    #[cfg(unix)]
+    let code = match error.raw_os_error() {
+        Some(libc::EFBIG) => MsdErrorCode::MsdImageTooLarge,
+        Some(libc::ENOSPC) => MsdErrorCode::MsdStorageFull,
+        Some(libc::EROFS) => MsdErrorCode::MsdStorageReadOnly,
+        Some(libc::EACCES | libc::EPERM) => MsdErrorCode::MsdStoragePermissionDenied,
+        _ => MsdErrorCode::MsdOperationFailed,
+    };
+    #[cfg(not(unix))]
+    let code = MsdErrorCode::MsdOperationFailed;
+    code.into()
+}
+
+fn task_error(operation: &'static str, error: tokio::task::JoinError) -> AppError {
+    warn!(operation, %error, "Virtual drive task failed");
+    MsdErrorCode::MsdOperationFailed.into()
 }
 
 fn ventoy_file_to_drive_file(info: VentoyFileInfo, parent_path: &str) -> DriveFile {
@@ -470,16 +511,35 @@ mod tests {
     #[test]
     fn classifies_drive_creation_io_errors() {
         for (errno, expected) in [
-            (libc::EFBIG, "does not support"),
-            (libc::ENOSPC, "enough free space"),
-            (libc::EROFS, "read-only"),
-            (libc::EACCES, "permission"),
+            (libc::EFBIG, MsdErrorCode::MsdDriveSizeInvalid),
+            (libc::ENOSPC, MsdErrorCode::MsdStorageFull),
+            (libc::EROFS, MsdErrorCode::MsdStorageReadOnly),
+            (libc::EACCES, MsdErrorCode::MsdStoragePermissionDenied),
+            (libc::EPERM, MsdErrorCode::MsdStoragePermissionDenied),
         ] {
             let error = drive_init_error(VentoyError::Io(std::io::Error::from_raw_os_error(errno)));
-            assert!(matches!(error, AppError::BadRequest(message) if message.contains(expected)));
+            assert!(matches!(error, AppError::Msd(error) if error.code() == expected));
         }
     }
 
+    #[test]
+    fn classifies_ventoy_filesystem_and_resource_errors() {
+        for error in [
+            VentoyError::FilesystemError("details".into()),
+            VentoyError::ImageError("details".into()),
+            VentoyError::PartitionError("details".into()),
+        ] {
+            assert!(matches!(
+                ventoy_to_app_error(error),
+                AppError::Msd(error) if error.code() == MsdErrorCode::MsdDriveFilesystemUnsupported
+            ));
+        }
+        assert!(matches!(
+            ventoy_to_app_error(VentoyError::FileNotFound("details".into())),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdResourceNotFound
+        ));
+    }
+
     fn init_ventoy_resources() -> bool {
         static INIT: OnceLock<bool> = OnceLock::new();
         *INIT.get_or_init(|| {
@@ -548,9 +608,71 @@ mod tests {
 
         let info = drive.init(MIN_DRIVE_SIZE_MB).await.unwrap();
         assert!(info.initialized);
+        assert_eq!(info.file_access, DriveFileAccess::Available);
+        assert_eq!(info.used, Some(0));
+        assert!(info.free.is_some());
         assert!(drive.exists());
     }
 
+    #[tokio::test]
+    async fn raw_bytes_are_reported_as_unsupported_with_capacity() {
+        let temp_dir = TempDir::new().unwrap();
+        let drive_path = temp_dir.path().join("custom.img");
+        std::fs::write(&drive_path, vec![0x5a; 1024 * 1024]).unwrap();
+        let drive = VentoyDrive::new(drive_path);
+
+        let info = drive.info().await.unwrap();
+        assert_eq!(info.size, 1024 * 1024);
+        assert_eq!(info.used, None);
+        assert_eq!(info.free, None);
+        assert_eq!(info.file_access, DriveFileAccess::Unsupported);
+
+        assert!(matches!(
+            drive.list_files("/").await.unwrap_err(),
+            AppError::Msd(error)
+                if error.code() == MsdErrorCode::MsdDriveFilesystemUnsupported
+        ));
+    }
+
+    #[test]
+    fn raw_metadata_rejects_missing_empty_and_non_file_paths() {
+        let temp_dir = TempDir::new().unwrap();
+        let missing = VentoyDrive::new(temp_dir.path().join("missing.img"));
+        assert!(matches!(
+            missing.raw_info(DriveFileAccess::Unknown).unwrap_err(),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdDriveNotInitialized
+        ));
+
+        let empty_path = temp_dir.path().join("empty.img");
+        std::fs::write(&empty_path, []).unwrap();
+        let empty = VentoyDrive::new(empty_path);
+        assert!(matches!(
+            empty.raw_info(DriveFileAccess::Unknown).unwrap_err(),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdDriveSizeInvalid
+        ));
+
+        let directory = VentoyDrive::new(temp_dir.path().to_path_buf());
+        assert!(matches!(
+            directory.raw_info(DriveFileAccess::Unknown).unwrap_err(),
+            AppError::Msd(error) if error.code() == MsdErrorCode::MsdDriveSizeInvalid
+        ));
+    }
+
+    #[tokio::test]
+    async fn supported_drive_info_has_space_values() {
+        if !ensure_resources() {
+            return;
+        }
+        let temp_dir = TempDir::new().unwrap();
+        let drive = VentoyDrive::new(temp_dir.path().join("supported.img"));
+        drive.init(MIN_DRIVE_SIZE_MB).await.unwrap();
+
+        let info = drive.info().await.unwrap();
+        assert_eq!(info.file_access, DriveFileAccess::Available);
+        assert!(info.used.is_some());
+        assert!(info.free.is_some());
+    }
+
     #[tokio::test]
     async fn test_drive_mkdir() {
         if !ensure_resources() {