RubyGems - copy_tuner_client - Versions diffs - 2.2.0 → 2.3.0 - Mend

copy_tuner_client 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +2 -235
data/CLAUDE.md +10 -0
data/README.md +42 -5
data/docs/poller-startup.md +108 -0
data/lib/copy_tuner_client/configuration.rb +37 -12
data/lib/copy_tuner_client/fork_hook.rb +53 -0
data/lib/copy_tuner_client/poller.rb +87 -23
data/lib/copy_tuner_client/process_guard.rb +13 -4
data/lib/copy_tuner_client/queue_with_timeout.rb +8 -2
data/lib/copy_tuner_client/version.rb +1 -1
data/skills/copy-tuner-to-locales-cleanup/SKILL.md +5 -5
data/skills/copy-tuner-to-locales-migrate-prefix/SKILL.md +69 -37
data/skills/copy-tuner-to-locales-migrate-prefix/references/example-touchpoints.md +31 -10
data/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb +144 -6
data/spec/copy_tuner_client/configuration_spec.rb +173 -0
data/spec/copy_tuner_client/fork_hook_spec.rb +171 -0
data/spec/copy_tuner_client/poller_spec.rb +148 -1
data/spec/copy_tuner_client/process_guard_spec.rb +8 -0
data/spec/copy_tuner_client/queue_with_timeout_spec.rb +27 -0
data/spec/copy_tuner_client/warden_integration_spec.rb +95 -0
data/spec/spec_helper.rb +6 -0
data/spec/support/middleware_stack.rb +39 -5
metadata +6 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fb9ea1caf782db8dac7ded7d77803a61586b5369b221b62d34e9e0290c58b06
-  data.tar.gz: ad4723a7fe5af378f68af6f786644cc549a1ebbe2523c3424af8fdaba5381433
+  metadata.gz: 3b141908e7fa8f6702cf9fccc712b88440af9aa96cc25c8b7875b3269d199825
+  data.tar.gz: c7b3f527ba59c387f721364fe0e2689fd849b99b33f4e53557611f23af828794
 SHA512:
-  metadata.gz: 7a894e4afd8428064c4fef7dd34db7bdfaab23879b5fa3aaabc5921437a3a80b7cf036fac920f8bf76e7274141f5a522f8364a493797084e7fee879f435d7eb4
-  data.tar.gz: 34211866166e6491e7488a8f87aadc96810afcea2f3b5069ae2b29b4b9e5f0fe9a620556e3fd55d403ed419c9ab917c34f4fee0eafea90e889a7b6d5653b0540
+  metadata.gz: cae2e31ecad418c08b1143f57bd5acf83b574ae5ca4aac1526e594ce911e7d37c98b7098a5a4d1bcaa4cacc133368764712525d80ef63b7dac4390bed5858093
+  data.tar.gz: 06e3b11bb99dc6162a0a1110999e1fe2ab4bc3dde42cecfa8ecbe0656a0861b7ea17f659c0ef1791f4df1601cd10e7b465eac755d2ae5305d22e78e0ffe260c4

data/CHANGELOG.md CHANGED Viewed

@@ -1,235 +1,2 @@
-## Unreleased
-- **【後方互換性に影響】** `config.exclude_key_regexp` を削除しました。後継の `config.local_first_key_regexp`
-  を使ってください。両者は対象キーの形式が異なります（`exclude_key_regexp` は locale 付き `ja.views.foo`、
-  `local_first_key_regexp` は locale を除いた `views.foo`）。正規表現から locale プレフィックスを外して
-  移行してください。挙動も異なり、`local_first_key_regexp` は lookup 時に CopyTuner キャッシュをスキップして
-  ローカル YAML を優先します（完全分離）。
-- **【後方互換性に影響】** `config.project_id` を必須にしました。未設定のまま `configure`（`apply`）すると
-  `ArgumentError: project_id is required` で失敗します。これまで `project_id` 未設定時は `api_key` へ
-  フォールバックして deprecation 警告を出していましたが、このフォールバックは削除しました。initializer に
-  `config.project_id = <プロジェクト ID>` を設定してください。
-- Copyray オーバーレイのマーカー方式を刷新。訳文への HTML コメント `<!--COPYRAY key-->` 注入をやめ、
-  可視トークン `⟦CT:key⟧` を埋め込んだうえで `CopyrayMiddleware` が `data-copyray-key` 属性に変換し、
-  トークンを HTML から完全に除去するようになりました。最終配信 HTML にコメント・トークンは残りません。
-- **【後方互換性に影響】** `config.html_escape` 設定を削除しました。HTML の安全性判定は i18n 標準
-  （`.html` / `_html` で終わるキーのみ html_safe）に統一され、この設定は参照されなくなっていました（no-op）。
-  no-op だったため動作には影響しませんが、`config.html_escape = ...` を設定している initializer は
-  `NoMethodError` になるため、その行を削除してください。`html_escape = false`（全訳文を html_safe 扱いに
-  する旧互換挙動）に依存していたアプリは、`.html` / `_html` キー命名へ移行してください。
-- Copyray オーバーレイは平文・html_safe（`.html` / `_html` キー）どちらの訳文もハイライト対象です。マーカートークンの
-  区切り記号は HTML 特殊文字ではないため、平文訳文が ActionView でエスケープされてもトークンは無傷で残り、
-  `data-copyray-key` 属性へ正しく変換されます。`<head>` 内（title/meta）はトークンを除去するのみでオーバーレイ
-  非対象ですが、従来どおりリスト導線（CopyTuner バー）から編集できます。
-- **【後方互換性に影響】** `tt` ヘルパーを削除しました。マーカー方式の刷新で `t`（`translate`）が安全にマーカー
-  注入できるようになり、`tt` の存在理由は失われました。`tt` の呼び出しは `t` へ置き換えてください。`tt` を使い続けたい
-  アプリは、ビューヘルパーで `t` に委譲するだけの `tt` を自前で定義してください（gem 撤去後は `t` と実質同義）。
-## 0.16.1
-- Support for i18n@1.13.0
-- キーの相対パス指定とdefaultオプションを組み合わせた場合の不具合修正
-## 0.16.0
-- Railsエンジン内のviewではオリジナルのtヘルパが呼ばれるように修正
-## 0.15.1
-- tヘルパーにdefault引数が渡された場合に初期値として登録されない問題を修正
-## 0.15.0
-- Drop support for ruby 2.7
-## 0.14.1
-- Fix super call in define_method
-## 0.14.0
-- Add Support for good_job
-- Drop Support for Resque
-## 0.13.5
-- Rename assets
-## 0.13.4
-- Fix csp nonce
-## 0.13.3
-- Add `media="all"` attribute to stylesheet link tag
-## 0.13.2
-- Add `crossorigin="anonymous"` attribute to script tag
-## 0.13.1
-- Add `type="module"` attribute to script tag
-## 0.13.0
-- Drop support for ruby 2.6
-## 0.12.0
-- Add `config.ignored_keys` and `config.ignored_key_handler`
-## 0.11.0
-- Remove deprecated rescue_format option
-- Fix ruby@2.7 keyword warning
-## 0.10.0
-- Add copy_tuner:detect_html_incompatible_keys task
-## 0.9.0
-- Do not upload invalid type keys
-## 0.8.1
-- Fix bug in `CopyrayMiddleware`
-## 0.8.0
-- Change the default value of config.upload_disabled_environments
-## 0.7.0
-- Add config.upload_disabled_environments
-## 0.6.2
-- Add arguments to export task
-## 0.6.1
-- Fix ruby@2.7 keyword warning
-## 0.6.0
-- Drop support for ruby 2.4
-- Drop support for rails 5.1
-## 0.5.2
-- Do not upload invalid keys
-## 0.5.1
-- Do not upload downloaded keys
-## 0.5.0
-- Drop support for ruby 2.3
-- Add tt helper
-- Add copy_tuner:detect_conflict_keys task
-- Do not re-upload empty keys
-- Fix dual loading tasks
-- Remove config.copyray_js_injection_regexp_for_debug
-- Remove config.copyray_js_injection_regexp_for_precompiled
-- Download translation when initialization
-## 0.4.11
-- changes
-  - Fix hide toggle button on mobile device.
-## 0.4.10
-- changes
-  - Hide copyray bar on all media.
-## 0.4.9
-- changes
-  - Smaller toggle button.
-  - Hide toggle button on mobile device.
-## 0.4.8
-- changes
-  - Support passenger 5.3.x
-## 0.4.7
-- changes
-  - Compatibile with bullet gem (rewrap response with ActionDispatch::Response::RackBody)
-## 0.4.6
-- changes
-  - Performance imporovement (sync with server asynchronously)
-  - Add config.middleware_position
-## 0.4.5
-- changes
-  - Fix deprecated css.
-## 0.4.4
-- bug fix
-  - Don't upload resolved default values.
-## 0.4.3
-- bug fix
-  - Start poller thread regardless of puma mode. #39
-## 0.4.2
-- changes
-  - span tag is no longer added to translation text.
-## 0.4.1
-- bug fixes
-  - js injection failed if jquery is not used. #33
-  - Fix some js error. #34
-  - Wrong key is displayed if scoped option is used. #35
-- deprecation
-  - config.copyray_js_injection_regexp_for_debug is no longer needed.
-  - config.copyray_js_injection_regexp_for_precompiled is no longer needed.
-## 0.4.0
-- Remove jQuery dependency.
-## 0.3.5
-- Support Rails 5.1
-## 0.3.4
-- Use Logger to /dev/null as default when rails console
-## 0.3.3
-- Add config.locales. (#24)
-- Fix initialization order bug. (#25)
-## 0.3.2
-- Support I18n.t :scope option.
-- Update copyray_js_injection_regexp_for_debug.
-## 0.3.1
-- Add search box to copyray bar.
-- Add disable_copyray_comment_injection to configuration.
-## 0.3.0
-- Use https as default.
-- Download blurbs from S3.
-- Add toolbar.
-- "Translations in this page" menu.
+> [!NOTE]
+> 変更履歴は [GitHub Releases](https://github.com/SonicGarden/copy-tuner-ruby-client/releases) に移行済みです。

data/CLAUDE.md CHANGED Viewed

@@ -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/README.md CHANGED Viewed

@@ -62,20 +62,57 @@ CopyTuner で一元管理している翻訳を、`views.*` のような単位で
 アプリ独自の `number.*` キー（例 `number.gift_amount`）は対象外で、従来どおり CopyTuner で管理できます。
-## Claude Code スキル
+## Middleware の挿入位置
-`skills/copy-tuner/` に Claude Code 向けのスキルが含まれています。
+CopyTuner は開発環境で `RequestSync` / `CopyrayMiddleware` を Rack の middleware スタックに挿入します。`RequestSync` はリクエスト毎に CopyTuner サーバと同期し、`CopyrayMiddleware` はページ内のマーカー（`⟦CT:key⟧`）を除去・変換します。
-### copy-tuner スキル
+挿入位置は自動で決まるため、通常は設定不要です。Devise（Warden）を使っているアプリでは `Warden::Manager` の直前、それ以外の環境ではスタック末尾に挿入されます。
-i18n キーの操作を支援するスキルです。翻訳キーの検索・登録・確認などの依頼に自動的に使用されます。
+Devise 併用時に Warden の直前へ寄せるのは `throw :warden` の挙動に対応するためです。`throw :warden` は `Warden::Manager` の `catch(:warden)` までスタックを巻き戻すため、CopyTuner の middleware が Warden より内側にあると、認証エラー時のレスポンス（`Devise::FailureApp` が返す HTML）を受け取れず、Copyray のマーカーがページに残ってしまいます。
+位置を変えたい場合は `config.middleware_position` に `{ before: SomeMiddleware }` または `{ after: SomeMiddleware }` を指定すると、このデフォルトを上書きできます。
+```ruby
+CopyTunerClient.configure do |config|
+  # ...
+  config.middleware_position = { after: Rack::Runtime }
+end
+```
+指定した middleware がスタックに存在しない場合、Rails の起動時に例外（`No such middleware to insert before: ...` / `... insert after: ...`）が発生します。
+## Claude Code スキル
+`skills/` 以下に Claude Code 向けのスキルが含まれています。
 ```
-gh skill install SonicGarden/copy-tuner-ruby-client copy-tuner --scope project
+gh skill install SonicGarden/copy-tuner-ruby-client <スキル名> --scope project
 ```
+### copy-tuner スキル
+i18n キーの操作を支援するスキルです。翻訳キーの検索・登録・確認などの依頼に自動的に使用されます。
 詳細: [skills/copy-tuner/SKILL.md](skills/copy-tuner/SKILL.md)
+### copy-tuner-to-locales-migrate-prefix スキル
+copy_tuner が集中管理する i18n キーを、prefix（正規表現）単位で `config/locales` のローカル YAML 管理へ移行するスキルです。gem は残したまま特定 prefix だけをローカル化する「部分ローカル化」と、全 prefix を移して完全撤去する「全移行」の両方に使えます。明示的に呼び出したときのみ動作します。
+詳細: [skills/copy-tuner-to-locales-migrate-prefix/SKILL.md](skills/copy-tuner-to-locales-migrate-prefix/SKILL.md)
+### copy-tuner-to-locales-cleanup スキル
+`copy-tuner-to-locales-migrate-prefix` で全 prefix の移行が完了した後に、gem・初期化子・CI・deploy・ドキュメント・MCP 設定を一括撤去し、copy_tuner 依存を完全に取り除くスキルです。明示的に呼び出したときのみ動作します。
+詳細: [skills/copy-tuner-to-locales-cleanup/SKILL.md](skills/copy-tuner-to-locales-cleanup/SKILL.md)
+### copy-tuner-to-t-migrate スキル
+copy_tuner_client v2.0.0 で削除された独自ヘルパー `tt` の呼び出しを、Rails 標準の `t`（`translate`）へ置換するスキルです。機械的に安全な箇所は一括変換し、文字列加工や `label` の第一引数に渡している箇所は 1 件ずつ確認しながら置換します。破壊的な一括書き換えを含むため、明示的に呼び出したときのみ動作します。
+詳細: [skills/copy-tuner-to-t-migrate/SKILL.md](skills/copy-tuner-to-t-migrate/SKILL.md)
 Development
 =================

data/docs/poller-startup.md ADDED Viewed

@@ -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/configuration.rb CHANGED Viewed

@@ -184,6 +184,7 @@ module CopyTunerClient
       self.local_first_key_regexp = nil
       self.project_id = nil
       self.download_cache_dir = Pathname.new(Dir.pwd).join('tmp', 'cache', 'copy_tuner_client')
+      self.middleware_position = default_middleware_position
       @applied = false
     end
@@ -357,6 +358,20 @@ module CopyTunerClient
       end
     end
+    # throw :warden は Warden::Manager の catch(:warden) までスタックを巻き戻すため、
+    # Warden より内側の middleware は @app.call の戻り値を受け取れず、Devise::FailureApp の
+    # 応答がマーカー除去を経ずにブラウザへ届いてしまう。これを避けるため Warden の直前を既定位置にする。
+    #
+    # 判定に Devise の有無も見るのは、warden を require するだけで Warden::Manager を
+    # スタックに積まない gem（authtrail 等）が存在するため。定数の有無だけで決めると
+    # そうしたアプリで insert_before が対象を見つけられず起動時例外になる。
+    # スタックへ積むのは Devise の railtie（config.app_middleware.use）である。
+    def default_middleware_position
+      return nil unless defined?(::Warden::Manager) && defined?(::Devise)
+      { before: ::Warden::Manager }
+    end
     def setup_middleware
       if enable_middleware?
         logger.info 'Using copytuner sync middleware'
@@ -372,23 +387,33 @@ module CopyTunerClient
       logger.info "Available locales: #{locales.join(' ')}"
     end
-    def insert_middleware # rubocop:disable Metrics/AbcSize
-      request_sync_options = {
+    def insert_middleware
+      # NOTE: 値の nil を除外するのは、{ before: SomeClass if cond } のように条件次第で nil が入る
+      # 書き方で従来は末尾 use にフォールバックしていた挙動を保つため（キーの有無だけで分岐すると
+      # insert_before(nil) が対象を見つけられず例外になる）。
+      case middleware_position
+      in { before: target } if target
+        middleware.insert_before(target, RequestSync, request_sync_options)
+        middleware.insert_before(target, CopyTunerClient::CopyrayMiddleware)
+      in { after: target } if target
+        # NOTE: insert_after(index, *) は insert(index + 1, *) を呼ぶため、同じ対象へ 2 回挿入すると
+        # 後から挿入した方が対象に近い位置に来て順序が反転する。逆順で呼ぶことで
+        # 外側→内側が RequestSync → CopyrayMiddleware に揃う。
+        middleware.insert_after(target, CopyTunerClient::CopyrayMiddleware)
+        middleware.insert_after(target, RequestSync, request_sync_options)
+      else
+        middleware.use(RequestSync, request_sync_options)
+        middleware.use(CopyTunerClient::CopyrayMiddleware)
+      end
+    end
+    def request_sync_options
+      {
         poller: @poller,
         cache:,
         interval: sync_interval,
         ignore_regex: sync_ignore_path_regex,
       }
-      if middleware_position.is_a?(Hash) && middleware_position[:before]
-        middleware.insert_before(middleware_position[:before], RequestSync, request_sync_options)
-        middleware.insert_before(middleware_position[:before], CopyTunerClient::CopyrayMiddleware)
-      elsif middleware_position.is_a?(Hash) && middleware_position[:after]
-        middleware.insert_after(middleware_position[:after], RequestSync, request_sync_options)
-        middleware.insert_after(middleware_position[:after], CopyTunerClient::CopyrayMiddleware)
-      else
-        middleware.use(RequestSync, request_sync_options)
-        middleware.use(CopyTunerClient::CopyrayMiddleware)
-      end
     end
     # project_id は必須。未設定なら明示的に失敗させる。

data/lib/copy_tuner_client/fork_hook.rb ADDED Viewed

@@ -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