fix: Harden obs-websocket vendor request implementation

hanatyan128 · hanatyan128 · commit d22598e3e4dc · 2026-04-26T04:08:36.000+09:00
- Move FILTER_ID and PROC_OVERRIDE_* proc names to plugin-main.hpp as shared constants
- Normalize UUID input to lowercase before obs_get_source_by_uuid() lookup
- Move vendor.store() to after all request registrations complete
- Replace locale-dependent std::isxdigit/isalpha with explicit ASCII range checks
- Reorder obs_module_unload() to null statusDock before unregistering vendor requests
- Remove lib/ from CPACK_SOURCE_IGNORE_FILES to preserve obs-websocket-api.h in source tarballs
- Add SYSTEM keyword to obs-websocket include directory in CMakeLists.txt
- Add early exit in build.ps1 on submodule update failure
- Fix cmake-format glob pattern for lib/ submodule exclusion
- Add submodule init instructions to README / README_ja
- Correct error strings in API documentation
diff --git a/.gitignore b/.gitignore
@@ -30,6 +30,7 @@
 !screenshot2.jpg
 !build.ps1
 !/lib
+!.gitmodules
 !README_ja.md
 !API.md
 !API_ja.md
diff --git a/.gitmodules b/.gitmodules
@@ -1,6 +1,7 @@
 [submodule "lib/obs-websocket"]
 	path = lib/obs-websocket
 	url = https://github.com/obsproject/obs-websocket.git
+	# Pinned to tag: 5.7.3 (commit 1fcb95b)
 	# Tag-pinned: do NOT use `git submodule update --remote`.
 	# To update, fetch and checkout a specific release tag manually
 	# (see https://github.com/obsproject/obs-websocket/tags).
diff --git a/API.md b/API.md
@@ -294,9 +294,16 @@ Vendor requests require a client authenticated with obs-websocket. The obs-webso
 
 - `filter_uuid` must be a 36-character hyphenated UUID string. Other shapes are rejected with `"filter_uuid must be a UUID string"`.
 - `format` cannot exceed 1024 bytes. Longer strings are rejected with `"format too long"`.
-- `filter_uuid` must resolve to a Branch Output filter source. Any other source (including non-existent UUIDs) is rejected with `"Filter not found"`.
+- `format` must be a relative path expression. Absolute paths (POSIX `/...`, Windows `\...` or `X:\...`) and any `..` segment are rejected with `"format must not contain path traversal or absolute paths"`.
+- `filter_uuid` must resolve to a Branch Output filter source. Any other source (including non-existent UUIDs) is rejected with `"UUID does not refer to a Branch Output filter"`.
 - Do not send bursts of requests while a recording transition (file split, restart) is in progress — a request may block until the transition completes.
 
+### Client-side throttling
+
+The plugin does **not** rate-limit `override_recording_filename_format` or `override_replay_buffer_filename_format`. Each request that produces a different `format` while recording is active may trigger a file split or a recording restart, so a client that fires updates faster than the recording can settle will fragment files and stress the encoder pipeline.
+
+The bundled OBS scripts (see [Throttling](#recording-filename-from-text)) deduplicate by value and apply at most one update every 30 seconds per distinct `format`. Vendor requests do not pass through that script, so this guard is bypassed when driving the plugin over obs-websocket. **Implement equivalent throttling in your client** — at minimum, suppress duplicate `format` values and rate-limit distinct updates (≥ 30 s is a safe starting point; tune to match your file-split and restart tolerance).
+
 ### `get_filter_list`
 
 Enumerates every Branch Output filter currently loaded in OBS.
diff --git a/API_ja.md b/API_ja.md
@@ -294,9 +294,16 @@ vendor request は obs-websocket に認証済みのクライアントからの
 
 - `filter_uuid` は 36 文字のハイフン付き UUID 文字列である必要があります。それ以外の形式は `"filter_uuid must be a UUID string"` で拒否されます。
 - `format` は 1024 バイトを超えられません。超過した場合は `"format too long"` で拒否されます。
-- `filter_uuid` は Branch Output フィルターソースに解決される必要があります。他種別のソースや存在しない UUID は `"Filter not found"` で拒否されます。
+- `format` は相対パス表現である必要があります。絶対パス（POSIX の `/...`、Windows の `\...` や `X:\...`）および `..` セグメントは `"format must not contain path traversal or absolute paths"` で拒否されます。
+- `filter_uuid` は Branch Output フィルターソースに解決される必要があります。他種別のソースや存在しない UUID は `"UUID does not refer to a Branch Output filter"` で拒否されます。
 - 録画遷移中（ファイル分割、リスタート）にリクエストを連続送信すると、遷移完了までリクエストがブロックされることがあります。
 
+### クライアント側スロットリング
+
+プラグインは `override_recording_filename_format` および `override_replay_buffer_filename_format` に対して**レート制限を行いません**。録画中に `format` が異なるリクエストを受けるたびに、ファイル分割または録画リスタートが発生する可能性があるため、録画側が落ち着くより速く更新を投げ続けるクライアントはファイルを断片化させ、エンコーダパイプラインに負荷をかけます。
+
+同梱の OBS スクリプト（[スロットリング](#recording-filename-from-text)を参照）は同一値を重複排除し、異なる `format` ごとに 30 秒に最大 1 回までの更新に制限しています。vendor request はこのスクリプトを経由しないため、obs-websocket 経由で操作する場合はこのガードを迂回します。**クライアント側で同等のスロットリングを実装してください** — 最低限、同一の `format` 値を抑制し、異なる更新もレート制限してください（30 秒以上を出発点とし、ファイル分割・リスタートの許容度に合わせて調整してください）。
+
 ### `get_filter_list`
 
 現在 OBS にロードされている Branch Output フィルター一覧を列挙します。
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -38,7 +38,7 @@ if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/lib/obs-websocket/lib/obs-websocket-a
   message(FATAL_ERROR "lib/obs-websocket submodule not found. Run: git submodule update --init --recursive")
 endif()
 
-target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/lib/obs-websocket/lib)
+target_include_directories(${CMAKE_PROJECT_NAME} SYSTEM PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/lib/obs-websocket/lib)
 
 target_sources(
   ${CMAKE_PROJECT_NAME}
diff --git a/README.md b/README.md
@@ -125,3 +125,14 @@ See the [API reference](./API.md) for procedure signatures, sample code, and usa
 
 This plugin is developed under [obs-plugintemplate](https://github.com/obsproject/obs-plugintemplate)
 
+## Prerequisites
+
+This repository depends on the [obs-websocket](https://github.com/obsproject/obs-websocket) headers, which are included
+as a Git submodule under `lib/obs-websocket`. After cloning, initialize the submodule before configuring the build:
+
+```bash
+git submodule update --init --recursive
+```
+
+If you cloned with `--recurse-submodules`, this step is unnecessary.
+
diff --git a/README_ja.md b/README_ja.md
@@ -127,3 +127,13 @@ Branch Output は、外部スクリプトから実行時にストリーム録画
 
 This plugin is developed under [obs-plugintemplate](https://github.com/obsproject/obs-plugintemplate)
 
+## 事前準備
+
+本リポジトリは [obs-websocket](https://github.com/obsproject/obs-websocket) のヘッダに依存しており、`lib/obs-websocket` 配下に Git サブモジュールとして含まれています。クローン後、ビルド設定の前にサブモジュールを初期化してください。
+
+```bash
+git submodule update --init --recursive
+```
+
+`--recurse-submodules` 付きでクローンした場合は、この手順は不要です。
+
diff --git a/build-aux/.run-format.zsh b/build-aux/.run-format.zsh
@@ -70,7 +70,8 @@ invoke_formatter() {
 
       local -a source_files=(**/(CMakeLists.txt|*.cmake)(.N))
       source_files=(${source_files:#(build_*)/*})
-      source_files=(${source_files:#lib/*})
+      # Exclude vendored submodules under lib/ from cmake-format (nested paths included)
+      source_files=(${source_files:#lib/**/*})
 
       local -a format_args=()
       if (( _loglevel > 2 )) format_args+=(--log-level debug)
diff --git a/build.ps1 b/build.ps1
@@ -8,6 +8,11 @@ $ProductVersion = $BuildSpec.version
 
 $OutputName = "${ProductName}-${ProductVersion}-windows-x64"
 
+if (-not (Test-Path "lib/obs-websocket/lib/obs-websocket-api.h")) {
+    git submodule update --init --recursive lib/obs-websocket
+    if (-not $?) { exit 1 }
+}
+
 cmake --fresh -S . -B build_x64 -Wdev -Wdeprecated -DCMAKE_SYSTEM_VERSION="10.0.18363.657" -G "Visual Studio 17 2022" -A x64
 cmake --build build_x64 --config RelWithDebInfo --target ALL_BUILD --
 cmake --install build_x64 --prefix release/Package --config RelWithDebInfo
diff --git a/cmake/linux/defaults.cmake b/cmake/linux/defaults.cmake
@@ -34,6 +34,7 @@ set(CPACK_SOURCE_IGNORE_FILES
     \\.git/
     \\.github/
     \\.gitignore
+    \\.gitmodules
     build_.*
     cmake/\\.CMakeBuildNumber
     release/)
diff --git a/src/plugin-main.cpp b/src/plugin-main.cpp
@@ -25,6 +25,7 @@ with this program. If not, see <https://www.gnu.org/licenses/>
 #include <obs.hpp>
 
 #include <atomic>
+#include <string>
 
 #include <QRegularExpression>
 #include <QThread>
@@ -37,7 +38,6 @@ with this program. If not, see <https://www.gnu.org/licenses/>
 #include "utils.hpp"
 
 #define SETTINGS_JSON_NAME "recently.json"
-#define FILTER_ID "osi_branch_output"
 #define AVAILAVILITY_CHECK_INTERVAL_NS 1000000000ULL
 #define TASK_INTERVAL_MS 1000
 
@@ -147,12 +147,11 @@ BranchOutputFilter::BranchOutputFilter(obs_data_t *settings, obs_source_t *sourc
     // FIXME: libobs has no proc_handler_remove(). If it gains one, pair
     // unregistration with ~BranchOutputFilter().
     proc_handler_t *ph = obs_source_get_proc_handler(filterSource);
-    proc_handler_add(
-        ph, "void override_replay_buffer_filename_format(in string format)", onOverrideReplayBufferFilenameFormat, this
-    );
-    proc_handler_add(
-        ph, "void override_recording_filename_format(in string format)", onOverrideRecordingFilenameFormat, this
-    );
+    auto replayBufferProcDecl =
+        std::string("void ") + PROC_OVERRIDE_REPLAY_BUFFER_FILENAME_FORMAT + "(in string format)";
+    auto recordingProcDecl = std::string("void ") + PROC_OVERRIDE_RECORDING_FILENAME_FORMAT + "(in string format)";
+    proc_handler_add(ph, replayBufferProcDecl.c_str(), onOverrideReplayBufferFilenameFormat, this);
+    proc_handler_add(ph, recordingProcDecl.c_str(), onOverrideRecordingFilenameFormat, this);
 
     obs_log(LOG_INFO, "%s: BranchOutputFilter created", qUtf8Printable(name));
 }
@@ -1936,15 +1935,10 @@ void obs_module_post_load()
 
 void obs_module_unload()
 {
-    unregisterWebSocketVendorRequests();
-
-    // Publish nullptr before destroying the widget so subsequent loads in
-    // onGetFilterList() bail out. A worker that already holds a non-null
-    // pointer will either (a) take the cross-thread branch and be released
-    // by Qt 6's ~QObject() cleanup with invokeMethod() returning false
-    // (implementation detail, not a spec guarantee), or (b) take the
-    // same-thread branch, which is only reachable on the UI thread and
-    // therefore cannot race this unloader.
+    // Publish nullptr before unregistering vendor requests so that any
+    // vendor callback already in flight observes a null dock and bails out
+    // of the UI dispatch path. Doing this first shrinks (but does not
+    // close) the worker race window.
     //
     // FIXME: narrow worker race remains. Proper fixes are an in-flight
     // counter (wait for zero before remove_dock) or QPointer + deleteLater
@@ -1954,6 +1948,8 @@ void obs_module_unload()
         obs_frontend_remove_dock("BranchOutputStatusDock");
     }
 
+    unregisterWebSocketVendorRequests();
+
     pthread_mutex_destroy(&pluginMutex);
 
     obs_log(LOG_INFO, "Plugin unloaded");
diff --git a/src/plugin-main.hpp b/src/plugin-main.hpp
@@ -37,6 +37,17 @@ with this program. If not, see <https://www.gnu.org/licenses/>
 
 #define MAX_SERVICES 8
 
+// Source ID for the Branch Output filter. Used by createFilterInfo() to register the
+// source and by external lookups (e.g. obs-websocket vendor requests) to verify that
+// a given obs_source_t* is in fact a Branch Output filter.
+inline constexpr char FILTER_ID[] = "osi_branch_output";
+
+// Proc handler names exposed on each BranchOutputFilter source. Shared between
+// the registration site (plugin-main.cpp) and callers (plugin-websocket.cpp) so
+// that a rename on one side does not silently break the other.
+inline constexpr char PROC_OVERRIDE_RECORDING_FILENAME_FORMAT[] = "override_recording_filename_format";
+inline constexpr char PROC_OVERRIDE_REPLAY_BUFFER_FILENAME_FORMAT[] = "override_replay_buffer_filename_format";
+
 // Defined in plugin-main.cpp. Guards plugin-wide state shared across filter instances:
 // - Serializes OBS global API calls (obs_view, obs_encoder, obs_output creation/destruction)
 // - Protects BranchOutputFilter instance lists and cross-instance coordination
diff --git a/src/plugin-websocket.cpp b/src/plugin-websocket.cpp
