ci: add build deb

.clang-format

@@ -0,0 +1,90 @@
+Language:      Cpp
+BasedOnStyle:  LLVM
+AccessModifierOffset: -4
+# AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: true
+# AlignEscapedNewlinesLeft: false
+AlignOperands:   true
+AlignTrailingComments: true
+# AllowAllArgumentsOnNextLine: true    # Requires clang-format v9 and higher
+# AllowAllConstructorInitializersOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+# AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+# AllowShortIfStatementsOnASingleLine: false
+# AllowShortLoopsOnASingleLine: false
+# AlwaysBreakAfterDefinitionReturnType: None
+# AlwaysBreakAfterReturnType: None
+# AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: false
+BinPackParameters: false
+# BraceWrapping:   
+#   AfterClass:      false
+#   AfterControlStatement: false
+#   AfterEnum:       false
+#   AfterFunction:   false
+#   AfterNamespace:  false
+#   AfterObjCDeclaration: false
+#   AfterStruct:     false
+#   AfterUnion:      false
+#   BeforeCatch:     false
+#   BeforeElse:      false
+#   IndentBraces:    false
+# BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Allman
+# BreakInheritanceList: BeforeComma
+# BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeComma
+# BreakAfterJavaFieldAnnotations: false
+# BreakStringLiterals: true
+ColumnLimit:     120
+# CommentPragmas:  '^ IWYU pragma:'
+# ConstructorInitializerAllOnOneLineOrOnePerLine: false
+# ConstructorInitializerIndentWidth: 4
+# ContinuationIndentWidth: 4
+# Cpp11BracedListStyle: true
+# DerivePointerAlignment: false
+# DisableFormat:   false
+# ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+# ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
+# IncludeIsMainRegex: '$'
+# IndentCaseLabels: false
+IndentWidth:     4
+# IndentWrappedFunctionNames: false
+# JavaScriptQuotes: Leave
+# JavaScriptWrapImports: true
+# KeepEmptyLinesAtTheStartOfBlocks: true
+# MacroBlockBegin: ''
+# MacroBlockEnd:   ''
+# MaxEmptyLinesToKeep: 1
+# NamespaceIndentation: None
+# ObjCBlockIndentWidth: 2
+# ObjCSpaceAfterProperty: false
+# ObjCSpaceBeforeProtocolList: true
+# PenaltyBreakBeforeFirstCallParameter: 19
+# PenaltyBreakComment: 300
+# PenaltyBreakFirstLessLess: 120
+# PenaltyBreakString: 1000
+# PenaltyExcessCharacter: 1000000
+# PenaltyReturnTypeOnItsOwnLine: 60
+PointerAlignment: Left
+# ReflowComments:  true
+SortIncludes:    false
+# SpaceAfterCStyleCast: false
+# SpaceAfterTemplateKeyword: true
+# SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+# SpaceInEmptyParentheses: false
+# SpacesBeforeTrailingComments: 1
+# SpacesInAngles:  false
+# SpacesInContainerLiterals: true
+# SpacesInCStyleCastParentheses: false
+# SpacesInParentheses: false
+# SpacesInSquareBrackets: false
+Standard: Cpp03
+TabWidth:        4
+UseTab:          Never

.github/workflows/build-check.yml

@@ -0,0 +1,82 @@
+name: Build Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build ${{ matrix.config.arch }}
+    runs-on: ${{ matrix.config.runner }}
+    strategy:
+      matrix:
+        config:
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+          - arch: amd64
+            runner: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build with Docker
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          outputs: build
+          platforms: linux/${{ matrix.config.arch }}
+
+      - name: Verify plugin was built
+        run: |
+          ls -la build/usr/lib/*/gstreamer-1.0/
+
+      - name: Build Summary
+        run: |
+          echo "## ✅ Build Check Passed" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Architecture:** ${{ matrix.config.arch }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Runner:** ${{ matrix.config.runner }}" >> $GITHUB_STEP_SUMMARY
+
+  functional-test:
+    name: Functional suite + TSan/ASAN (ctest)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install build + GStreamer dev dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential \
+            cmake \
+            git \
+            patch \
+            pkg-config \
+            libgstreamer1.0-dev \
+            libgstreamer-plugins-base1.0-dev \
+            libjpeg-dev \
+            libusb-1.0-0-dev
+
+      # ENABLE_SANITIZERS is load-bearing: without it ctest runs only the plain
+      # variants, dropping all ASan (SPS/PPS overflow) and TSan (frame/PTS race)
+      # coverage. Keep it on so the full hardware-independent suite is gated.
+      - name: Configure and build (with sanitizers)
+        run: |
+          cmake -B build -DENABLE_SANITIZERS=ON
+          cmake --build build
+
+      - name: Run ctest (full suite incl. TSan/ASAN)
+        run: ctest --test-dir build --output-on-failure
+
+      - name: Functional Test Summary
+        if: always()
+        run: |
+          echo "## 🔌 Functional test suite (ctest + TSan/ASAN)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '`ctest --test-dir build` ran the full hardware-independent suite against the libuvc mock: plugin-load smoke, mock streaming, lifecycle, device selection, negotiate edges, SPS/PPS overflow (ASan), frame/PTS thread-safety (TSan), and the consolidated functional caps (H.264/H.265) + backpressure suite.' >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -0,0 +1,10 @@
+
+# OpenCode agent state (local only)
+.omo/
+
+# Build directories (Meson + CMake/ctest)
+/build/
+/build*/
+
+# Test artifacts (ctest output, coverage, traces)
+/test-results/

CHANGELOG.md

@@ -0,0 +1,83 @@
+# CHANGELOG for gstlibuvch264src
+
+## 2.0, Hardening release
+
+The bulk of this release (module split, mock-backed test suite, memory-safety and correctness fixes, PTZ properties, device selection, hardened control socket) was contributed by [CeraLive](https://github.com/CERALIVE/gstlibuvch264src) and merged here.
+
+### What
+
+A comprehensive hardening pass across the entire element. The monolithic source was split into cohesive modules, a hardware-independent mock-backed test suite was built from scratch, and 19 distinct correctness and security issues were fixed. New capabilities: hardware-stable device selection, native PTZ properties, an opt-in hardened control socket, and a V4L2 capability probe.
+
+### Why
+
+The original element had several latent memory-safety issues (heap overflow on oversized SPS/PPS NALs, USB handle double-close, caps negotiation leaks), correctness bugs (PTS monotonicity, restart state not reset, NAL start-code detection missing the 3-byte form), and security concerns (world-accessible control socket at a fixed `/tmp` path, no index validation). None of these were caught by the existing smoke test because it only checked plugin registration. No frames flowed, no device was opened, no PTZ was exercised.
+
+The hardening pass adds a full mock-backed ctest suite (TSan, ASAN, LSAN variants) that exercises all of these paths without requiring hardware.
+
+### Changes
+
+**Module split (behavior-preserving)**
+The ~1100-line monolithic `gstlibuvch264src.c` was split into five cohesive translation units: `gstlibuvch264src.c` (GObject boilerplate), `frame_pipeline.c` (NAL parsing and PTS), `spspps_cache.c` (SPS/PPS disk cache), `ptz_control.c` (PTZ and control socket), `uvc_device.c` (USB teardown and V4L2 probe). No behavior change.
+
+**Test infrastructure**
+A libuvc mock harness (`mock_libuvc.c`) covers ~16 libuvc functions. A libusb mock (`mock_libusb.c`) enables teardown double-close testing. TSan and ASAN ctest variants run the full suite under sanitizers. The Dockerfile and CMakeLists.txt now pin the base image (`ubuntu:24.04@sha256:786a8b55...`) and libuvc source (`68d07a00`, v0.0.7) by SHA. The arch matrix fails loudly on unknown `TARGETARCH` values.
+
+**Security and correctness fixes**
+- Heap overflow: SPS/PPS/VPS NAL copies now clamp to buffer size before `memcpy`
+- USB teardown UAF/double-close: `force_usb_release()` no longer calls `libusb_close()`, so `uvc_close()` owns the single close
+- Caps negotiation leaks: single `goto out` cleanup path, `GValue` (GST_TYPE_LIST) unset after `gst_structure_set_value()`
+- PTS monotonicity: clamp plus offset bound guard, first-frame underflow guard
+- Restart state: `had_idr`, `send_sps_pps`, `frame_count`, `prev_int_ts` reset on every `start()`
+- NAL parser: detects both 3-byte and 4-byte Annex-B start codes, dynamic unit array (no 10-unit cap), `size_t` lengths throughout
+- Device-list leak: `uvc_ref_device()` before `uvc_free_device_list()`, fatal error on zero devices
+- Index validation: strict `strtol` replaces silent `atoi()`, malformed index posts `RESOURCE/SETTINGS`
+- Mutex lifecycle: `control_mutex` cleared once in `finalize()`, not in `stop()`
+- `unlock()`/`unlock_stop()`: implemented with `FLUSH_SENTINEL` plus `g_async_queue_timeout_pop`, so `create()` never deadlocks on disconnect
+- Framerate guard: `framerate <= 0` check prevents SIGFPE, zero device interval skipped
+- PTS hot-path locking: clock ref plus PTS state under `GST_OBJECT_LOCK` in `frame_callback`
+- SPS/PPS cache: path traversal blocked, NULL guards, resolution key (`<idx>_<codec>_<WxH>`)
+- Error mapping: `uvc_error_t` to `GST_ELEMENT_ERROR` helper covers all libuvc error codes
+- Interface count: real `bNumInterfaces` from `libusb_get_active_config_descriptor` replaces hardcoded 8
+- SPS/PPS write-on-change: disk write suppressed when content is unchanged
+
+**New capabilities**
+- Device selection: `index` now accepts `"vid:pid"` (hex), `"serial:<sn>"`, `"bus:<bus>:<addr>"` in addition to the existing ordinal form. Backward-compatible, default `"0"` unchanged.
+- Native PTZ properties: `pan`, `tilt`, `zoom` (GObject properties, capability-gated). The `set-ptz` action signal drives all three axes in one call. Always available, no socket required.
+- Opt-in control socket: `control-socket=true` enables a Unix-domain PTZ socket. Default off. Per-instance path under `$XDG_RUNTIME_DIR` (mode 0600). The old world-accessible `/tmp/libuvc_control` is gone.
+- Control socket protocol: `PAN_TILT <pan> <tilt>` and `ZOOM <zoom>` accept normalized floats in `[-1.0, 1.0]`, mapped onto the device's probed absolute range. Callers stay decoupled from per-device UVC units while the `pan`/`tilt`/`zoom` properties keep absolute units.
+- Disconnect behavior: always posts `GST_ELEMENT_ERROR(RESOURCE, READ)` on device unplug.
+- Opt-in reconnect: default off, gated on a confirmed-safe libuvc teardown spike (`libuvch264src/docs/notes/reconnect-spike.md`).
+- LATENCY query: reports `live=TRUE`, `min=1/fps` instead of the GstBaseSrc default of zero.
+- Buffer OFFSET: monotonic per-frame counter set on every buffer.
+- V4L2 probe: one `VIDIOC_TRY_FMT` at open, logs H.264 availability, non-fatal.
+
+**Build**
+- Multiarch paths via `$(gcc -print-multiarch)`, no hardcoded `aarch64-linux-gnu`.
+- Pinned base image and libuvc SHA in both Dockerfile and CMakeLists.txt.
+- The Debian package CI (`publish-deb.yml`) is retained as the release path; the plugin version string is `2.0`.
+
+### How to verify
+
+```bash
+# Full test suite with sanitizers
+cmake -B build -DENABLE_SANITIZERS=ON && cmake --build build && ctest --test-dir build --output-on-failure
+
+# Spot-check key areas
+ctest --test-dir build -R "ptz_properties|ptz_capability_gate"
+ctest --test-dir build -R "socket_default_off|socket_hardened"
+ctest --test-dir build -R "device_selector"
+ctest --test-dir build -R "usb_teardown"
+ctest --test-dir build -R "negotiate_leak"
+ctest --test-dir build -R "pts_monotonic|restart_idr"
+ctest --test-dir build -R "nal_parse"
+ctest --test-dir build -R "v4l2_probe"
+```
+
+On hardware: `gst-inspect-1.0 libuvch264src` should list `pan`, `tilt`, `zoom`, `control-socket`, `control-socket-path`, and the `set-ptz` action signal alongside `index`.
+
+### Risks
+
+- **Module split:** Zero behavior change by design. All five translation units compile to the same symbols as before, the split is purely organizational. The full ctest suite (including TSan/ASAN) validates this.
+- **Control socket default off:** Any consumer that relied on the old `/tmp/libuvc_control` socket must now set `control-socket=true` and either read the resolved `control-socket-path` property or pass an explicit `control-socket-path`. Downstream consumers in this group standardize on `$XDG_RUNTIME_DIR/libuvc_control`.
+- **Index selector expansion:** The `index` property now rejects malformed values that `atoi()` would have silently mapped to 0. A pipeline that passed a non-numeric string as `index` now fails loudly at `start()` instead of silently selecting device 0. This is the correct behavior.
+- **TSan suppressions:** Two suppressions in `tsan_pts.suppressions` are permanent. `GST_OBJECT_LOCK` uses a raw futex in uninstrumented GLib, so TSan cannot see the happens-before relationship for PTS/clock fields. The behavioral tests (`pts_thread_safety`, `frame_throughput`) provide real coverage that the suppressions cannot mask.

CMakeLists.txt

@@ -0,0 +1,108 @@
+# =============================================================================
+# CMake build for the libuvch264src plugin-load smoke test (ctest target).
+#
+# SCOPE: This CMake project exists ONLY to compile the GStreamer plugin together
+# with a hardware-independent gst-check smoke test and expose it via ctest.
+#
+# The CANONICAL production build remains Meson (libuvch264src/meson.build) and
+# the Dockerfile. Device-image artifacts must NOT be produced from this build.
+# The plugin source is compiled verbatim - no runtime behavior is changed here.
+# =============================================================================
+
+cmake_minimum_required(VERSION 3.16)
+project(gstlibuvch264src C)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+enable_testing()
+
+find_package(PkgConfig REQUIRED)
+# Version floors. GStreamer 1.14 is the oldest series the plugin's pad/caps API
+# usage compiles against (Ubuntu 18.04 baseline); no known incompatibility on
+# the 1.x line, so no upper bound is imposed. libusb 1.0.20 is the floor for the
+# auto-detach-kernel-driver call the libuvc patches rely on.
+pkg_check_modules(GST REQUIRED IMPORTED_TARGET gstreamer-1.0>=1.14)
+pkg_check_modules(GST_BASE REQUIRED IMPORTED_TARGET gstreamer-base-1.0>=1.14)
+pkg_check_modules(GST_CHECK REQUIRED IMPORTED_TARGET gstreamer-check-1.0>=1.14)
+pkg_check_modules(LIBUSB REQUIRED IMPORTED_TARGET libusb-1.0>=1.0.20)
+
+# -----------------------------------------------------------------------------
+# libuvc dependency.
+#
+# Prefer a system/pkg-config libuvc; otherwise vendor it at build time exactly
+# like the Dockerfile does (upstream v0.0.7 + the UVC 1.5 and H.265 patches the
+# plugin relies on). LIBUVC_RUNTIME_DIR is exported to the test so the vendored
+# shared object is resolvable at dlopen() time.
+# -----------------------------------------------------------------------------
+pkg_check_modules(LIBUVC IMPORTED_TARGET libuvc)
+
+if(LIBUVC_FOUND)
+  set(LIBUVC_LINK_TARGET PkgConfig::LIBUVC)
+  set(LIBUVC_EXTRA_INCLUDES "")
+  set(LIBUVC_RUNTIME_DIR "")
+else()
+  message(STATUS "libuvc not found via pkg-config; vendoring upstream v0.0.7 + patches")
+  include(FetchContent)
+
+  # libuvc v0.0.7 ships pre-3.5 CMake policies; allow them under modern CMake.
+  set(CMAKE_POLICY_VERSION_MINIMUM 3.5 CACHE STRING "" FORCE)
+  set(BUILD_EXAMPLE OFF CACHE BOOL "" FORCE)
+  set(BUILD_TEST OFF CACHE BOOL "" FORCE)
+  set(BUILD_SHARED_LIBS ON CACHE BOOL "" FORCE)
+
+  FetchContent_Declare(libuvc
+    GIT_REPOSITORY https://github.com/libuvc/libuvc.git
+    # Pinned to the v0.0.7 commit SHA (tags are mutable). Keep in sync with the Dockerfile.
+    GIT_TAG 68d07a00e11d1944e27b7295ee69673239c00b4b
+    PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_SOURCE_DIR}/patches/uvc15-support.patch
+      && patch -p1 < ${CMAKE_CURRENT_SOURCE_DIR}/patches/libuvc-h265-support.patch
+    UPDATE_DISCONNECTED 1
+  )
+  FetchContent_MakeAvailable(libuvc)
+
+  set(LIBUVC_LINK_TARGET uvc)
+  # v0.0.7 uses directory-level include_directories, so expose them explicitly.
+  set(LIBUVC_EXTRA_INCLUDES
+    ${libuvc_SOURCE_DIR}/include
+    ${libuvc_BINARY_DIR}/include
+  )
+  set(LIBUVC_RUNTIME_DIR ${libuvc_BINARY_DIR})
+endif()
+
+# -----------------------------------------------------------------------------
+# GStreamer plugin module (compiled from the unmodified plugin source).
+# Output: <build>/gstreamer-1.0/libgstlibuvch264src.so
+# -----------------------------------------------------------------------------
+set(GST_PLUGIN_BUILD_DIR ${CMAKE_BINARY_DIR}/gstreamer-1.0)
+
+add_library(gstlibuvch264src MODULE
+  libuvch264src/src/gstlibuvch264src.c
+  libuvch264src/src/uvc_device.c
+  libuvch264src/src/frame_pipeline.c
+  libuvch264src/src/ptz_control.c
+  libuvch264src/src/spspps_cache.c
+  libuvch264src/src/gstlibuvch264src_error.c
+)
+set_target_properties(gstlibuvch264src PROPERTIES
+  PREFIX "lib"
+  LIBRARY_OUTPUT_DIRECTORY ${GST_PLUGIN_BUILD_DIR}
+)
+target_include_directories(gstlibuvch264src PRIVATE
+  ${CMAKE_CURRENT_SOURCE_DIR}/libuvch264src/src
+  ${LIBUVC_EXTRA_INCLUDES}
+)
+target_link_libraries(gstlibuvch264src PRIVATE
+  PkgConfig::GST
+  PkgConfig::GST_BASE
+  PkgConfig::LIBUSB
+  ${LIBUVC_LINK_TARGET}
+)
+if(LIBUVC_RUNTIME_DIR)
+  # Make the vendored libuvc resolvable for the test even outside ctest's env.
+  set_target_properties(gstlibuvch264src PROPERTIES
+    BUILD_RPATH ${LIBUVC_RUNTIME_DIR}
+  )
+endif()
+
+add_subdirectory(tests)