copy_tuner_client 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a9a2fe07a403679fa3bf6d10c72c13fadcd31536af653a79b3e6d84e80c10ab
-  data.tar.gz: b3300594e38799ec7004f4c4fb0e35b051a447c6dd8b66ffb512bb59d7b851b2
+  metadata.gz: 3b141908e7fa8f6702cf9fccc712b88440af9aa96cc25c8b7875b3269d199825
+  data.tar.gz: c7b3f527ba59c387f721364fe0e2689fd849b99b33f4e53557611f23af828794
 SHA512:
-  metadata.gz: 5af9d06699d0361e360ea31dd4bb67ba04d2e711e0324ee9d85ee59914404ef905e173e7b6fd6ef81ede67773784fd4788ccb45fac7399ce57ad1b67d6d094ce
-  data.tar.gz: 2143f94b230219cae83f8d317f52ba338b282894178edce8129eac5382be76836209fbb29b8dd9e25ac96d3a91a6b93fa326fed4c426f9b2304b9b12d9233482
+  metadata.gz: cae2e31ecad418c08b1143f57bd5acf83b574ae5ca4aac1526e594ce911e7d37c98b7098a5a4d1bcaa4cacc133368764712525d80ef63b7dac4390bed5858093
+  data.tar.gz: 06e3b11bb99dc6162a0a1110999e1fe2ab4bc3dde42cecfa8ecbe0656a0861b7ea17f659c0ef1791f4df1601cd10e7b465eac755d2ae5305d22e78e0ffe260c4

data/CLAUDE.md

@@ -34,6 +34,16 @@ Rails 統合は engine.rb のイニシャライザ経由（ヘルパー/SimpleFo
   （vite.config.ts が `src/main.ts` → `app/assets/javascripts/copytuner.js` を出力）。
 - `local_first_key_regexp` — locale を除いたキー対象・lookup 時に作用（ローカル YAML 優先）。
   local_first キーのアップロード抑止は `Cache#[]=` に集約されている。
+- **poller スレッドの fork 対応は `ForkHook`（`Process._fork` に prepend）に集約する**
+  （fork の直前に `Poller#stop` で協調的に停止し、fork 後に親子の両方で張り直す。理由: fork 後の子に残る
+  Thread オブジェクトの見え方（`alive?` / `join` の結果）はドキュメント化されていない CRuby の実装依存なので、
+  pid を記録して差分を見るような後始末には寄せない。子でも張り直すので、Puma の `fork_worker` のように
+  worker が worker を fork する構成でもサーバ固有のフックなしで poller が立つ。
+  アプリケーションサーバごとのフック（`ProcessGuard#register_*_hook`）を増やす前にここで足りるか確認する）。
+  起動方法・モードごとにどのプロセスで poller が起動するかは `docs/poller-startup.md` に実測結果がある。
+- **`Poller#poll` は例外をスレッドの外へ漏らさない**
+  （`Poller#stop` は fork 経路から呼ばれ、`Thread#join` はスレッドの例外を再送出するため、漏らすと
+  poller の失敗がアプリ側の `fork` を壊す）。
 - **アップロード抑止の新ルールは `Cache#[]=` に足す。`I18nBackend` の書き込み経路（`lookup` / `default` / `store_item`）ごとに個別ガードを足さない**
   （理由: cache への書き込みは全経路が最終的に `Cache#[]=` を通る単一の関門。経路ごとにガードを足すと付け忘れの穴が生まれ、同じチェックが分散して保守負担になる。実際 local_first の抑止は当初 `default` 個別に足したが穴が残り、`Cache#[]=` への集約に作り直した）。
 

data/docs/poller-startup.md

@@ -0,0 +1,108 @@
+# poller がどのプロセスで起動するか
+
+`Poller` はバックグラウンドスレッドで CopyTuner サーバと同期する。**リクエストを処理するプロセスで
+このスレッドが動いていないと翻訳が更新されない**が、動いていなくてもエラーにはならず、翻訳が古いまま
+になるだけなので気づきにくい。アプリケーションサーバの起動方法とモードによって「どのプロセスがアプリを
+ロードするか」が変わるため、ここに実測結果を残す。
+
+Puma 以外（Unicorn / Passenger / delayed_job / good_job）については `ProcessGuard` のフック登録
+メソッドを参照。
+
+## 前提: アプリをロードしたプロセスで initializer が走る
+
+`CopyTunerClient.configure`（＝ `Configuration#apply` ＝ `ProcessGuard#start`）は、Rails の
+initializer として **アプリをロードしたプロセスで 1 回だけ**走る。したがって「どのプロセスがアプリを
+ロードするか」が起点になる。
+
+## 実測結果
+
+検証環境: puma 8.0.2 / Rails 8.1.3.1 / Ruby 4.0.2（2026-09-03 実測）
+
+| 起動方法 | モード | アプリをロードするプロセス | poller の起動経路 | master に poller |
+| --- | --- | --- | --- | --- |
+| `rails server` | single | そのプロセス | 非 spawner 経路（`start_polling`） | （単一プロセス） |
+| `rails server` | cluster（preload の有無を問わず） | **master のみ** | master で `start_polling` → `ForkHook` が fork 後に worker で張り直す | 立つ |
+| `puma -C` | single | そのプロセス（`Runner#load_and_bind`） | `Puma::Runner#start_server` への prepend | （単一プロセス） |
+| `puma -C` | cluster + preload | master のみ | 各 worker の `start_server` で prepend したフックが発火 | 立たない |
+| `puma -C` | cluster + preload なし | **各 worker** | `$0` の `'cluster worker'` 判定による分岐 | 立たない（master はアプリをロードしない） |
+
+### 判定に使っている値
+
+`ProcessGuard#puma_spawner?` は `defined?(Puma::Runner) && $PROGRAM_NAME.include?('puma')` で判定する。
+実測値は次のとおり。
+
+| 起動方法 | `$PROGRAM_NAME` | `defined?(Puma)` | `defined?(Puma::Runner)` | `puma_spawner?` |
+| --- | --- | --- | --- | --- |
+| `rails server` | `"bin/rails"` | yes | **no** | false |
+| `puma -C`（master / single） | `".../bin/puma"` | yes | yes | true |
+| `puma -C`（preload なしの worker） | `"puma: cluster worker 0: <master pid> [app]"` | yes | yes | true |
+
+`$PROGRAM_NAME` が master と worker で違うのは Puma 側の実装差による。master は
+`launcher.rb` の `Process.setproctitle`（`$0` を変えない）、worker は `cluster/worker.rb` の
+`$0 = title`（変える）を使っている。
+
+## 各行の背景
+
+### `rails server` は preload 設定に関係なく master でアプリをロードする
+
+Rails は Puma を起動する**前に** Rack アプリを組み立てて（`Rails::Server#log_to_stdout` →
+`wrapped_app`）、オブジェクトとして Puma に渡す。そのため `preload_app!` を明示的に切っても worker が
+アプリをロードし直すことはなく、必ず master でロードされる。
+
+この構成では `Puma::Runner` が initializer の時点でまだ未定義なので `puma_spawner?` は false になり、
+master で poller が起動する。fork 後の worker には `ForkHook`（`Process._fork` に prepend）が
+引き継ぐ。master にも poller が 1 本残るが、`puma_spawner?` を無理に真にしようとすると起動方法ごとの
+判定を増やすことになるため、余分な 1 本を許容している。
+
+### Puma 8 は `workers > 1` のとき preload が既定で有効
+
+`Puma::Configuration#set_conditional_default_options` が `preload_app` の既定値を
+`!prune_bundler && workers > 1 && Puma.forkable?` で決めている。非 preload を試すには
+`preload_app!(false)` を明示する必要がある。
+
+### 非 preload では `start_server` の中でアプリがロードされる
+
+`Runner#start_server` は `Puma::Server.new(app, ...)` を呼び、`Runner#app` が
+`@app ||= @config.app` で遅延ロードする。つまり非 preload の worker では、initializer が走る時点で
+既に `start_server` が実行中であり、**そこで `Puma::Runner` に prepend しても間に合わない**。
+
+このため `$0` の `'cluster worker'` 判定は最適化ではなく、この構成で poller を起動する唯一の経路になっている。
+
+## 表のとおりにならない例外
+
+上の表は「poller のスレッドが起動する経路」であって、起動した poller が動き続けることまでは
+保証しない。`Poller` はスレッドの生死とは別にライフサイクルの意図を持っており、次の場合は
+表の経路を通っても poller が居なくなる。
+
+- **`InvalidApiKey`** — API キーが不正だと `poll` が自ら終了し、以後は fork をまたいでも張り直さない
+  （張り直しても同じ理由で死ぬだけなので）。ログに `Invalid API key` が出る
+- **起動時に CopyTuner サーバへ到達できない** — `Configuration#apply` の `cache.download` が
+  `ConnectionError` を再送出するため、そもそもプロセスが起動に失敗する。Puma の worker では
+  `! Unable to start worker` になる
+
+再検証の際は、まずこの 2 つに当たっていないかをログで確かめる。
+
+## 再検証のしかた
+
+Puma や Rails を上げたときにこの表が変わっていないか確かめるには、次の観測点を見るのが早い。
+
+1. 最小の Rails アプリを用意し、`config/initializers` で `Process.pid` / `Process.ppid` /
+   `$PROGRAM_NAME` / `defined?(Puma::Runner)` を出力する。これで**どのプロセスがアプリをロードしたか**が分かる
+2. 任意のエンドポイントで `CopyTunerClient.poller` の `@thread` を覗き、`alive?` を返す。
+   fork 後の worker が親から継承した dead な Thread を持っていると、ここが `false` になる
+3. 翻訳を返すだけの偽 CopyTuner サーバを立て（`draft_blurbs.json` を返し、`draft_blurbs` /
+   `deploys` の POST を受ける）、`polling_delay` を数秒にする。起動後にサーバ側の翻訳を書き換え、
+   worker が拾うかどうかで実際の同期を確認する
+4. 上の表の 5 構成（`rails server` / `puma -C` × single / cluster+preload / cluster+非 preload）で回す
+
+`ProcessGuard` のログ（`Register Puma fork hook` / `Puma would be clustered mode without preload_app` /
+`start poller thread`）をプロセス ID 付きで集計すると、どの経路を通ったかが分かる。
+
+## 関連
+
+- `CopyTunerClient::ForkHook` — fork をまたいで poller を引き継ぐ。判定が外れて master で poller が
+  起動してしまった場合の安全網でもある
+- `CopyTunerClient::Poller` — スレッドの生死とは別に `@running`（ポーリングを継続する意図）と
+  `@aborted`（張り直しても同じ理由で死ぬ終わり方をしたか）を持つ。`ForkHook` が fork 後に張り直すか
+  どうかは `Poller#stop` の戻り値、すなわちこの意図で決まる（スレッドが生きているかではない）
+- [Ruby における fork と Thread の挙動の調査](https://gist.github.com/shunichi/c236b6a85a46a16c60262047ca299608)

data/lib/copy_tuner_client/fork_hook.rb

@@ -0,0 +1,53 @@
+module CopyTunerClient
+  # fork をまたいで poller スレッドを引き継ぐためのフック。
+  # Process._fork に prepend し、fork の直前に poller を協調的に停止して、
+  # fork のあと親子それぞれで張り直す。
+  module ForkHook
+    # Module#prepend は同じモジュールを二重に挿さないので、呼び出し側で登録済みかを見なくてよい
+    def self.install
+      ::Process.singleton_class.prepend(self)
+    end
+
+    def _fork
+      # fork はアプリの任意のタイミングで起きる。Process._fork への prepend は外せないので、
+      # configure 前や configuration 差し替え中に NoMethodError でアプリの fork を
+      # 壊さないよう nil を許容する
+      poller = CopyTunerClient.configuration&.poller
+      # スレッドは子プロセスに引き継がれない。fork 後に子へ残る Thread オブジェクトの見え方
+      # （alive? / join の結果）はドキュメント化されていない CRuby の実装依存なので、
+      # そこに依存した後始末はせず、fork 前に協調的に停止しておく。
+      # ここは rescue しない。停止の失敗を握り潰すと、動いている poller ごと fork することになり
+      # このフックの目的そのものを裏切る
+      restart = poller ? poller.stop : false
+
+      begin
+        super
+      ensure
+        # ensure は親（super の戻り値 = 子の pid）と子（同 0）の両方を通り、super が失敗した
+        # ときも親で復元する。「fork 前に動いていたプロセスは fork 後も動いている」状態を保つ。
+        # 子でも張り直すのは、Puma の fork_worker のように worker が worker を fork する
+        # 構成でもサーバ固有のフックに頼らず poller を立てるため
+        ForkHook.restart_poller(poller) if restart
+      end
+    end
+
+    # Process.singleton_class に prepend されるため、インスタンスメソッドとして定義すると
+    # Process 自身にメソッドが生えてしまう。フックの補助はモジュール側の特異メソッドに置く
+    #
+    # fork 後に例外を漏らすと「子プロセスは生成済みなのに親の fork が例外を投げる」状態になり、
+    # 呼び出し側が子の pid を受け取れなくなる。起動の失敗はログに落として fork は成立させる
+    def self.restart_poller(poller)
+      poller.start
+    rescue StandardError => e
+      log_error("CopyTuner: fork 後の poller 起動に失敗しました: #{e.class}: #{e.message}")
+    end
+
+    # ログ出力自体が失敗しても fork は成立させる。ここで例外を漏らすと、失敗を握るために
+    # 置いた rescue が逆に fork を壊す
+    def self.log_error(message)
+      CopyTunerClient.configuration&.logger&.error(message)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/copy_tuner_client/poller.rb

@@ -9,28 +9,60 @@ module CopyTunerClient
     # @option options [Logger] :logger where errors should be logged
     # @option options [Fixnum] :polling_delay how long to wait in between requests
     def initialize(cache, options)
-      @cache         = cache
-      @polling_delay = options[:polling_delay]
-      @logger        = options[:logger]
-      @command_queue = CopyTunerClient::QueueWithTimeout.new
-      @mutex         = Mutex.new
-      @thread        = nil
+      @cache          = cache
+      @polling_delay  = options[:polling_delay]
+      @logger         = options[:logger]
+      @command_queue  = CopyTunerClient::QueueWithTimeout.new
+      @mutex          = Mutex.new
+      @thread         = nil
+      @last_synced_at = nil
+      # スレッドの生死とは別に、ライフサイクルの意図を持つ。
+      # @running: ポーリングを継続する意図があるか（start で true / stop で false）
+      # @aborted: 張り直しても同じ理由で死ぬと分かっている終わり方をしたか
+      @running        = false
+      @aborted        = false
     end
 
     def start
       @mutex.synchronize do
-        if @thread.nil?
-          @logger.info 'start poller thread'
-          @thread = Thread.new { poll } or logger.error("Couldn't start poller thread")
-        end
+        @running = true
+        # 回復の見込みがない理由で終了しているなら張り直さない。fork のたびに同じ例外で
+        # 死ぬスレッドを作り直してログを埋めるだけになる
+        next if @aborted
+        # fork 後の子は親から dead な Thread オブジェクトを継承するため、nil かどうかだけでは
+        # 「動いていない」を判定できない。死んでいるスレッドは張り直す
+        next if @thread&.alive?
+
+        # コマンドキューは世代ごとに作り直し、スレッドに自分のキューを渡す。前の世代宛に
+        # 積まれたまま未消費で残った :stop を次の世代が 1 周目で拾って自殺するのを、
+        # 「1 つのキューは 1 本のスレッドだけのもの」という不変条件で構造的に防ぐ
+        queue = CopyTunerClient::QueueWithTimeout.new
+        @command_queue = queue
+        @logger.info 'start poller thread'
+        @thread = Thread.new { poll(queue) } or logger.error("Couldn't start poller thread")
       end
     end
 
+    # 戻り値は ForkHook が「fork 後に張り直すか」を決めるのに使う。スレッドの生死ではなく
+    # ポーリングを継続する意図があったかを返す。想定外の例外で死んだだけのスレッドは
+    # fork 後に張り直したいが、生死で判定すると張り直せなくなる
+    #
+    # @return [Boolean] ポーリング継続の意図があった（＝ fork 後に張り直すべき）なら +true+
     def stop
       @mutex.synchronize do
-        @command_queue.uniq_push(:stop)
-        @thread&.join
+        resumable = @running && !@aborted
+        @running = false
+
+        thread = @thread
         @thread = nil
+        # 例外で終わったスレッドは非 nil のまま dead で残る。それに :stop を積んでも誰も
+        # pop しないので、生きているときだけ積んで待つ
+        if thread&.alive?
+          @command_queue.uniq_push(:stop)
+          thread.join
+        end
+
+        resumable
       end
     end
 
@@ -46,20 +78,52 @@ module CopyTunerClient
 
     attr_reader :cache, :logger, :polling_delay
 
-    def poll
-      loop do
-        cache.sync
-        logger.flush if logger.respond_to?(:flush)
-        begin
-          command = @command_queue.pop_with_timeout(polling_delay)
-          break if command == :stop
-        rescue ThreadError
-          # timeout
-        end
+    def poll(queue)
+      timeout = remaining_delay
+      until wait_for_command(queue, timeout) == :stop
+        sync
+        timeout = polling_delay
       end
-      @logger.info 'stop poller thread'
+      logger.info 'stop poller thread'
     rescue InvalidApiKey => e
+      # キーが不正なら張り直しても同じ結果になるので、以後の再開を止める
+      @aborted = true
       logger.error(e.message)
+    rescue StandardError => e
+      # 例外はスレッドの外へ漏らさない。stop の join は fork の直前にも呼ばれるため、
+      # 漏らすと poller の失敗がアプリ側の fork まで巻き添えにする。
+      # ここで握ると report_on_exception による stderr 出力も消えるので backtrace を残す
+      logger.error("poller thread aborted: #{e.class}: #{e.message}\n#{e.backtrace&.first(5)&.join("\n")}")
+    end
+
+    def sync
+      cache.sync
+      @last_synced_at = monotonic_now
+      logger.flush if logger.respond_to?(:flush)
+    end
+
+    # 最初の待ち時間を「前回 sync からの残り」にすることで、stop / start を繰り返しても
+    # sync の間隔を保つ。fork のたびに stop / start されるので、これが無いと worker を
+    # fork する数だけ親プロセスで sync（HTTP 往復）が走り直し、その分 join も待たされる。
+    # 基点には NTP や手動の時刻変更で巻き戻らない CLOCK_MONOTONIC を使う
+    # （Time.now だと時計が後ろに飛んだぶんだけ待ち時間が伸びて同期が止まる）
+    def remaining_delay
+      return 0 if @last_synced_at.nil?
+
+      remaining = polling_delay - (monotonic_now - @last_synced_at)
+      remaining.negative? ? 0 : remaining
+    end
+
+    # 自分の世代のキューを受け取る。@command_queue は start のたびに差し替わるため、
+    # 終了処理中の古いスレッドが新しい世代のキューを覗いてしまわないようにする
+    def wait_for_command(queue, timeout)
+      queue.pop_with_timeout(timeout)
+    rescue ThreadError
+      nil # timeout
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end
 end

data/lib/copy_tuner_client/process_guard.rb

@@ -1,3 +1,5 @@
+require 'copy_tuner_client/fork_hook'
+
 module CopyTunerClient
   # Starts the poller from a worker process, or register hooks for a spawner
   # process (such as in Unicorn or Passenger). Also registers hooks for exiting
@@ -14,6 +16,9 @@ module CopyTunerClient
 
     # Starts the poller or registers hooks
     def start
+      # fork の前後で poller を張り直すフックは、どのプロセスでも必ず登録する
+      ForkHook.install
+
       if spawner?
         register_spawn_hooks
       else
@@ -115,9 +120,12 @@ module CopyTunerClient
       ::Process.singleton_class.prepend(hook_module)
     end
 
+    # 起動方法（rails server / puma -C）とモード（single / cluster / preload の有無）ごとに
+    # どのプロセスで poller が起動するかは docs/poller-startup.md にまとめてある
     def register_puma_hook
-      # If Puma is clustered mode without preload_app, this method is called on worker process.
-      # Just start poller and return.
+      # 非 preload の cluster worker はここに来る。この構成ではアプリのロードが
+      # Puma::Runner#start_server の中で起きるため、今から prepend しても実行中の呼び出しには
+      # 間に合わない。つまりこの分岐が poller を起動する唯一の経路で、最適化ではなく必須
       if $PROGRAM_NAME.include?('cluster worker')
         @logger.info('Puma would be clustered mode without preload_app')
         @poller.start
@@ -125,8 +133,9 @@ module CopyTunerClient
       end
 
       @logger.info('Register Puma fork hook')
-      # If Puma is clustered mode with preload_app, this method is called before fork.
-      # Delay poller start until Puma::Runner#start_server which is called on worker process.
+      # preload ありの cluster ではこのメソッドが fork 前の master で走る。master は
+      # リクエストを捌かないのでここでは起動せず、worker 側で呼ばれる
+      # Puma::Runner#start_server まで遅らせる
       poller = @poller
       hook_module =
         Module.new do

data/lib/copy_tuner_client/queue_with_timeout.rb

@@ -51,10 +51,16 @@ module CopyTunerClient
 
     def wait_with_timeout(timeout)
       # wait for element or timeout
-      timeout_time = timeout + Time.now.to_f
-      while @queue.empty? && (remaining_time = timeout_time - Time.now.to_f).positive?
+      # NTP の step 補正や手動の時刻変更で巻き戻らない CLOCK_MONOTONIC で締め切りを測る。
+      # ウォールクロックだと時計が後ろへ飛んだぶんだけ待ち時間が伸びる
+      deadline = monotonic_now + timeout
+      while @queue.empty? && (remaining_time = deadline - monotonic_now).positive?
         @received.wait(@mutex, remaining_time)
       end
     end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
   end
 end

data/lib/copy_tuner_client/version.rb

@@ -1,6 +1,6 @@
 module CopyTunerClient
   # Client version
-  VERSION = '2.2.1'.freeze
+  VERSION = '2.3.0'.freeze
 
   # API version being used to communicate with the server
   API_VERSION = '2.0'.freeze

data/spec/copy_tuner_client/fork_hook_spec.rb

@@ -0,0 +1,171 @@
+require 'spec_helper'
+
+describe CopyTunerClient::ForkHook do
+  let(:client) { FakeClient.new }
+  let(:cache) { CopyTunerClient::Cache.new(client, logger: FakeLogger.new) }
+  let(:poller) do
+    config = CopyTunerClient::Configuration.new.to_hash
+    CopyTunerClient::Poller.new(cache, config.update(logger: FakeLogger.new, polling_delay:))
+  end
+
+  def polling_delay
+    0.5
+  end
+
+  before do
+    described_class.install
+    # フックは CopyTunerClient.configuration&.poller を見るので、実際の設定に載せる
+    CopyTunerClient.configuration.poller = poller
+  end
+
+  after do
+    poller.stop
+  end
+
+  describe '停止と再開の順序' do
+    # 実際に fork してしまうと「fork の瞬間にスレッドが止まっているか」を観測できないため、
+    # _fork の代わりに記録だけするオブジェクトに prepend して順序を見る
+    def build_forkable(events, &fork_body)
+      forkable = Object.new
+      forkable.define_singleton_method(:_fork) do
+        events << :fork
+        fork_body ? fork_body.call : 0
+      end
+      forkable.singleton_class.prepend(described_class)
+      forkable
+    end
+
+    def stub_poller(events, stopped:)
+      allow(poller).to receive(:stop) do
+        events << :stop
+        stopped
+      end
+      allow(poller).to receive(:start) { events << :start }
+    end
+
+    it 'fork の前に poller を停止し、fork の後に再開する' do
+      events = []
+      stub_poller(events, stopped: true)
+
+      build_forkable(events)._fork
+
+      expect(events).to eq(%i[stop fork start])
+    end
+
+    it 'fork 前に poller が動いていなければ再開しない' do
+      events = []
+      stub_poller(events, stopped: false)
+
+      build_forkable(events)._fork
+
+      expect(events).to eq(%i[stop fork])
+    end
+
+    it 'fork が失敗しても poller を再開する' do
+      events = []
+      stub_poller(events, stopped: true)
+
+      forkable = build_forkable(events) { raise Errno::EAGAIN }
+
+      expect { forkable._fork }.to raise_error(Errno::EAGAIN)
+      expect(events).to eq(%i[stop fork start])
+    end
+  end
+
+  describe 'poller を取得できないとき' do
+    it 'configuration が nil でも fork を壊さない' do
+      # Process._fork への prepend は外せないので、ここで例外を漏らすとアプリの
+      # すべての fork が失敗する
+      CopyTunerClient.configuration = nil
+
+      expect { Process.waitpid(fork { exit!(0) }) }.not_to raise_error
+    end
+
+    it 'ログ出力自体が失敗しても fork は成立する' do
+      allow(poller).to receive(:stop).and_return(true)
+      allow(poller).to receive(:start).and_raise(ThreadError, 'cannot create thread')
+      allow(CopyTunerClient.configuration.logger).to receive(:error).and_raise('logger is broken')
+
+      expect { Process.waitpid(fork { exit!(0) }) }.not_to raise_error
+    end
+
+    it 'fork 後の poller 起動に失敗しても fork 自体は成立する' do
+      allow(poller).to receive(:stop).and_return(true)
+      allow(poller).to receive(:start).and_raise(ThreadError, 'cannot create thread')
+
+      expect { Process.waitpid(fork { exit!(0) }) }.not_to raise_error
+    end
+  end
+
+  describe '実際に fork したとき' do
+    it 'fork 前に poller が例外で死んでいても親子とも張り直す' do
+      # rails server の cluster では ForkHook が唯一の再開経路なので、ここで張り直さないと
+      # 親子とも poller を失う
+      fail_once = true
+      allow(cache).to receive(:sync).and_wrap_original do |original, *args|
+        if fail_once
+          fail_once = false
+          raise 'boom'
+        end
+        original.call(*args)
+      end
+
+      poller.start
+      sleep(polling_delay * 0.4) # スレッドが例外で終わる
+
+      reader, writer = IO.pipe
+      pid =
+        fork do
+          reader.close
+          client['child.key'] = 'value'
+          sleep(polling_delay * 3)
+          writer.write(cache['child.key'].to_s)
+          writer.close
+          exit!(0)
+        end
+
+      writer.close
+      child_result = reader.read
+      Process.waitpid(pid)
+
+      client['parent.key'] = 'value'
+      sleep(polling_delay * 3)
+
+      expect(child_result).to eq('value')
+      expect(cache['parent.key']).to eq('value')
+    end
+
+    it '子プロセスでも poller がポーリングを続ける' do
+      poller.start
+      reader, writer = IO.pipe
+
+      pid =
+        fork do
+          reader.close
+          client['test.key'] = 'value'
+          sleep(polling_delay * 3)
+          writer.write(cache['test.key'].to_s)
+          writer.close
+          exit!(0)
+        end
+
+      writer.close
+      result = reader.read
+      Process.waitpid(pid)
+
+      expect(result).to eq('value')
+    end
+
+    it '親プロセスでも poller がポーリングを続ける' do
+      poller.start
+      sleep(polling_delay * 0.2)
+
+      Process.waitpid(fork { exit!(0) })
+
+      client['test.key'] = 'value'
+      sleep(polling_delay * 3)
+
+      expect(cache['test.key']).to eq('value')
+    end
+  end
+end

data/spec/copy_tuner_client/poller_spec.rb

@@ -11,7 +11,7 @@ describe CopyTunerClient::Poller do
 
   def build_poller(config = {})
     config[:logger] ||= FakeLogger.new
-    config[:polling_delay] = polling_delay
+    config[:polling_delay] ||= polling_delay
     default_config = CopyTunerClient::Configuration.new.to_hash
     poller = CopyTunerClient::Poller.new(cache, default_config.update(config))
     pollers << poller
@@ -95,4 +95,151 @@ describe CopyTunerClient::Poller do
 
     expect(logger).to have_received(:flush).at_least(:once)
   end
+
+  describe '#stop' do
+    it 'スレッドを停止したときは true を返す' do
+      poller = build_poller
+      poller.start
+
+      expect(poller.stop).to be true
+    end
+
+    it 'スレッドが動いていないときは false を返す' do
+      poller = build_poller
+
+      expect(poller.stop).to be false
+    end
+
+    it 'スレッドが例外で終わっていても例外を再送出しない' do
+      # stop は fork の直前にも呼ばれる。ここで join が poller の例外を再送出すると
+      # アプリ側の fork まで巻き添えになる
+      logger = FakeLogger.new
+      allow(cache).to receive(:sync).and_raise('boom')
+      poller = build_poller(logger:)
+      poller.start
+      sleep(polling_delay * 0.2)
+
+      expect { poller.stop }.not_to raise_error
+      expect(logger).to have_entry(:error, 'boom')
+    end
+
+    it 'start していないときに stop してもキューに :stop を残さない' do
+      poller = build_poller
+      poller.stop
+
+      poller.start
+
+      # 1 周目の sync だけでは「:stop がキューに残っている」状態と区別できないため、
+      # 2 周目以降も同期が続くことを確かめる
+      wait_for_next_sync
+      client['test.key'] = 'value'
+      wait_for_next_sync
+
+      expect(cache['test.key']).to eq('value')
+    end
+  end
+
+  describe '世代をまたいだコマンドの混入' do
+    # :stop は pop されるまでキューに残る。前の世代のスレッド宛に積まれた :stop を
+    # 次の世代のスレッドが拾うと、起動直後に自分を止めてしまう
+    it 'スレッドが例外で死んだ後に stop → start してもポーリングが続く' do
+      poller = build_poller
+      allow(cache).to receive(:sync).and_raise('boom')
+      poller.start
+      sleep(polling_delay * 0.3) # スレッドが例外で終わるのを待つ
+
+      allow(cache).to receive(:sync).and_call_original
+      poller.stop
+      poller.start
+
+      wait_for_next_sync
+      client['test.key'] = 'value'
+      wait_for_next_sync
+
+      expect(cache['test.key']).to eq('value')
+    end
+
+    it 'stop の直後に sync が例外で終わっても、次の start でポーリングが続く' do
+      poller = build_poller
+      # stop が :stop を積んだ後にスレッドが例外で終わる順序を作る。
+      # sync に入ったところで stop を待たせ、:stop を積み終えてから例外にする
+      syncing = Queue.new
+      resume = Queue.new
+      allow(cache).to receive(:sync) do
+        syncing << true
+        resume.pop
+        raise 'boom'
+      end
+
+      poller.start
+      syncing.pop # スレッドが sync に入った
+
+      stopper = Thread.new { poller.stop }
+      sleep(0.1) # :stop がキューに積まれるのを待つ
+      resume << true # ここで sync が例外になり、:stop は消費されない
+      stopper.join
+
+      allow(cache).to receive(:sync).and_call_original
+      poller.start
+
+      wait_for_next_sync
+      client['test.key'] = 'value'
+      wait_for_next_sync
+
+      expect(cache['test.key']).to eq('value')
+    end
+
+    # stop の戻り値は ForkHook の「fork 後に張り直すか」の判断に使われる。スレッドの生死ではなく
+    # 「ポーリングを継続する意図があるか」を返す必要がある
+    it 'スレッドが例外で死んでいても、起動中だったなら stop は true を返す' do
+      poller = build_poller
+      allow(cache).to receive(:sync).and_raise('boom')
+      poller.start
+      sleep(polling_delay * 0.3)
+
+      expect(poller.stop).to be true
+    end
+
+    it '回復の見込みがない理由で終了した後の stop は false を返す' do
+      poller = build_poller
+      allow(cache).to receive(:sync).and_raise(CopyTunerClient::InvalidApiKey, 'Invalid API key')
+      poller.start
+      sleep(polling_delay * 0.3)
+
+      # API キーが不正なら fork のたびに張り直しても同じ理由で死ぬだけなので再開させない
+      expect(poller.stop).to be false
+    end
+  end
+
+  describe '再開時の sync 間隔' do
+    # 経過時間で判定するため、CI の負荷や GC で sleep が伸びても落ちないよう
+    # 他のテストより長い間隔を使ってマージンを稼ぐ
+    let(:slow_delay) { 2.0 }
+
+    it '初回の start では待たずに sync する' do
+      poller = build_poller(polling_delay: slow_delay)
+
+      poller.start
+      sleep(slow_delay * 0.2)
+
+      expect(client.downloads).to eq(1)
+    end
+
+    it '停止直後に再開したときは前回 sync からの残り時間を待ってから sync する' do
+      poller = build_poller(polling_delay: slow_delay)
+      poller.start
+      sleep(slow_delay * 0.2)
+      poller.stop
+
+      poller.start
+
+      # 前回 sync から polling_delay 経つまでは sync しない
+      sleep(slow_delay * 0.4)
+      expect(client.downloads).to eq(1)
+
+      # 残り時間が過ぎれば sync が再開する
+      sleep(slow_delay * 0.8)
+      expect(client.downloads).to eq(2)
+    end
+  end
 end

data/spec/copy_tuner_client/process_guard_spec.rb

@@ -20,6 +20,14 @@ describe CopyTunerClient::ProcessGuard do
     process_guard
   end
 
+  it 'fork の前後で poller を張り直すフックを登録する' do
+    allow(CopyTunerClient::ForkHook).to receive(:install)
+
+    build_process_guard.start
+
+    expect(CopyTunerClient::ForkHook).to have_received(:install)
+  end
+
   it 'starts polling from a worker process' do
     process_guard = build_process_guard
     process_guard.start

data/spec/copy_tuner_client/queue_with_timeout_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+require 'timeout'
+
+describe CopyTunerClient::QueueWithTimeout do
+  subject(:queue) { described_class.new }
+
+  describe '#pop_with_timeout' do
+    it 'キューに要素があれば取り出す' do
+      queue << :sync
+
+      expect(queue.pop_with_timeout(0)).to eq(:sync)
+    end
+
+    it '要素が無いままタイムアウトしたら ThreadError を投げる' do
+      expect { queue.pop_with_timeout(0.1) }.to raise_error(ThreadError)
+    end
+
+    it 'ウォールクロックが巻き戻ってもタイムアウトが伸びない' do
+      # 待っている最中に NTP の step 補正や手動の時刻変更で時計が後ろへ飛ぶ状況を模す。
+      # 経過時間をウォールクロックで測っていると、飛んだ幅がそのまま待ち時間に乗る
+      base = Time.now
+      allow(Time).to receive(:now).and_return(base, base - 3600)
+
+      expect { Timeout.timeout(2) { queue.pop_with_timeout(0.1) } }.to raise_error(ThreadError)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -26,4 +26,10 @@ RSpec.configure do |config|
     FakeCopyTunerApp.reset
     reset_config
   end
+
+  # apply を通す spec は本物の poller スレッドを起動するので、example ごとに止める。
+  # 放置するとスレッドがスイート終了まで積み上がり、実際に HTTP を叩き続ける
+  config.after do
+    CopyTunerClient.configuration&.poller&.stop
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: copy_tuner_client
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - SonicGarden
@@ -200,6 +200,7 @@ files:
 - app/assets/javascripts/copytuner.js
 - biome.json
 - copy_tuner_client.gemspec
+- docs/poller-startup.md
 - gemfiles/8.0.gemfile
 - gemfiles/8.1.gemfile
 - gemfiles/main.gemfile
@@ -215,6 +216,7 @@ files:
 - lib/copy_tuner_client/dotted_hash.rb
 - lib/copy_tuner_client/engine.rb
 - lib/copy_tuner_client/errors.rb
+- lib/copy_tuner_client/fork_hook.rb
 - lib/copy_tuner_client/helper_extension.rb
 - lib/copy_tuner_client/i18n_backend.rb
 - lib/copy_tuner_client/i18n_compat.rb
@@ -251,11 +253,13 @@ files:
 - spec/copy_tuner_client/copyray_middleware_spec.rb
 - spec/copy_tuner_client/copyray_spec.rb
 - spec/copy_tuner_client/dotted_hash_spec.rb
+- spec/copy_tuner_client/fork_hook_spec.rb
 - spec/copy_tuner_client/helper_extension_spec.rb
 - spec/copy_tuner_client/i18n_backend_spec.rb
 - spec/copy_tuner_client/poller_spec.rb
 - spec/copy_tuner_client/prefixed_logger_spec.rb
 - spec/copy_tuner_client/process_guard_spec.rb
+- spec/copy_tuner_client/queue_with_timeout_spec.rb
 - spec/copy_tuner_client/request_sync_spec.rb
 - spec/copy_tuner_client/translation_log_spec.rb
 - spec/copy_tuner_client/warden_integration_spec.rb