copy_tuner_client 2.2.1 → 2.4.0

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.4.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

data/src/copyray-overlay.ts

@@ -1,5 +1,4 @@
 import { OVERLAY_STYLES } from './styles'
-import { computeBoundingBox } from './util'
 
 type OpenCallback = (key: string) => void
 
@@ -15,13 +14,14 @@ const findBlurbs = (): Blurb[] =>
     element,
   }))
 
-// オーバーレイ背景・翻訳要素のハイライト枠（specimen）・トグルボタンをまとめて Shadow DOM 内に描画する。
+// オーバーレイ背景と翻訳要素のハイライト枠（specimen）を Shadow DOM 内に描画する。
 export class CopyrayOverlay extends HTMLElement {
   #onOpen: OpenCallback = () => {}
-  #onToggle: () => void = () => {}
+  #onClose: () => void = () => {}
   #backdrop: HTMLDivElement
   #specimens: HTMLDivElement
-  #toggleButton: HTMLAnchorElement
+  #boxes = new Map<Element, HTMLDivElement>()
+  #frame: number | null = null
 
   constructor() {
     super()
@@ -33,74 +33,81 @@ export class CopyrayOverlay extends HTMLElement {
 
     this.#backdrop = document.createElement('div')
     this.#backdrop.classList.add('backdrop')
-    this.#backdrop.addEventListener('click', () => this.hide())
+    this.#backdrop.addEventListener('click', () => this.#onClose())
 
-    // specimen をページ座標基準で absolute 配置するコンテナ
     this.#specimens = document.createElement('div')
-    this.#specimens.classList.add('specimens')
 
-    this.#toggleButton = document.createElement('a')
-    this.#toggleButton.classList.add('toggle-button')
-    this.#toggleButton.textContent = 'Open CopyTuner'
-    // 旧実装ではトグルボタンが overlay と bar の両方を表示していた。show() ではなく onToggle 経由で表示する。
-    this.#toggleButton.addEventListener('click', () => this.#onToggle())
-
-    shadow.append(this.#backdrop, this.#specimens, this.#toggleButton)
-
-    // 初期は非表示（背景と specimen を隠す）。トグルボタンは常時表示のため :host([hidden]) は使わず個別制御する。
-    this.hide()
+    shadow.append(this.#backdrop, this.#specimens)
   }
 
   set onOpen(callback: OpenCallback) {
     this.#onOpen = callback
   }
 
-  set onToggle(callback: () => void) {
-    this.#onToggle = callback
-  }
-
-  get isShowing(): boolean {
-    return !this.#backdrop.hidden
+  set onClose(callback: () => void) {
+    this.#onClose = callback
   }
 
   show() {
-    this.reset()
-    this.#backdrop.hidden = false
+    // 二重 show でもリスナーと boxes が重複しないよう、まず後始末を通す
+    this.hide()
 
     for (const { element, keys } of findBlurbs()) {
-      const box = this.makeBox(element, keys)
-      if (box) {
-        this.#specimens.append(box)
-      }
+      this.#boxes.set(element, this.makeBox(keys))
     }
+    // 初回は同期で配置する（rAF 経由だと開いた直後の 1 フレームだけ位置がずれる）
+    this.#reposition()
+    this.#specimens.append(...this.#boxes.values())
+
+    document.addEventListener('scroll', this.#requestReposition, { capture: true, passive: true })
+    window.addEventListener('resize', this.#requestReposition, { passive: true })
   }
 
   hide() {
-    this.reset()
-    this.#backdrop.hidden = true
-  }
+    // capture フラグはリスナーの同一性判定に含まれるため、省くと解除されない
+    document.removeEventListener('scroll', this.#requestReposition, { capture: true })
+    window.removeEventListener('resize', this.#requestReposition)
+
+    // 閉じた後に走っても boxes は空で no-op になるが、無駄なコールバックを残さない
+    if (this.#frame !== null) {
+      cancelAnimationFrame(this.#frame)
+      this.#frame = null
+    }
 
-  reset() {
+    // detached な box を握り続けると開くたびに肥大する
+    this.#boxes.clear()
     this.#specimens.replaceChildren()
   }
 
-  private makeBox(element: Element, keys: string[]): HTMLDivElement | null {
-    const bounds = computeBoundingBox(element)
-    if (bounds === null) return null
+  // scroll は慣性スクロール中に毎フレーム相当で発火するため、同一フレーム内の再計測は 1 回にまとめる
+  #requestReposition = () => {
+    if (this.#frame !== null) return
 
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null
+      this.#reposition()
+    })
+  }
+
+  #reposition() {
+    // 読みと書きを分けないと、要素数分の強制同期レイアウトが走る
+    const measured = Array.from(this.#boxes, ([element, box]) => [box, element.getBoundingClientRect()] as const)
+
+    for (const [box, rect] of measured) {
+      // display: none / DOM から外れた要素は rect が全て 0 になる。原点に枠だけ残さないよう隠す
+      box.hidden = rect.width === 0 && rect.height === 0
+      if (box.hidden) continue
+
+      box.style.left = `${rect.left}px`
+      box.style.top = `${rect.top}px`
+      box.style.width = `${rect.width}px`
+      box.style.height = `${rect.height}px`
+    }
+  }
+
+  private makeBox(keys: string[]): HTMLDivElement {
     const box = document.createElement('div')
     box.classList.add('specimen')
-    box.style.left = `${bounds.left}px`
-    box.style.top = `${bounds.top}px`
-    box.style.width = `${bounds.width}px`
-    box.style.height = `${bounds.height}px`
-
-    const { position, top, left } = getComputedStyle(element)
-    if (position === 'fixed') {
-      box.style.position = 'fixed'
-      box.style.top = top
-      box.style.left = left
-    }
 
     // box 全体のクリックは先頭キーを開く（広いクリック領域を維持）。複数キー時は各ラベルから個別に開ける
     box.addEventListener('click', () => this.#onOpen(keys[0]))

data/src/copytuner-bar.ts

@@ -21,12 +21,6 @@ export class CopytunerBar extends HTMLElement {
     this.attachShadow({ mode: 'open' })
   }
 
-  // custom element の constructor 内では属性・プロパティを変更できない（createElement が弾く）ため、
-  // hidden の初期化は DOM 挿入後に呼ばれる connectedCallback で行う。
-  connectedCallback() {
-    this.hidden = true
-  }
-
   // url/data/keysSkipped/onOpen はオブジェクトや関数を含むため属性ではなくメソッドで受け渡す。
   init({ url, data, keysSkipped, onOpen }: InitOptions) {
     this.#onOpen = onOpen
@@ -66,14 +60,9 @@ export class CopytunerBar extends HTMLElement {
   }
 
   show() {
-    this.hidden = false
     this.#searchBox.focus()
   }
 
-  hide() {
-    this.hidden = true
-  }
-
   private makeButton(label: string, href: string, target?: string): HTMLAnchorElement {
     const button = document.createElement('a')
     button.classList.add('button')

data/src/copytuner-root.ts

@@ -0,0 +1,31 @@
+import { ROOT_STYLES } from './styles'
+
+// dialog を showModal() で top layer の最上位に載せることで、アプリ側のモーダル dialog による
+// inert 化を受けずに操作できる。トグルボタンだけ dialog の外に置くのは、
+// 閉じている間 dialog のサブツリーが display: none になり、常時表示のボタンが消えてしまうため。
+export class CopytunerRoot extends HTMLElement {
+  readonly dialog: HTMLDialogElement
+  #onToggle: () => void = () => {}
+
+  constructor() {
+    super()
+    const shadow = this.attachShadow({ mode: 'open' })
+
+    const style = document.createElement('style')
+    style.textContent = ROOT_STYLES
+    shadow.append(style)
+
+    this.dialog = document.createElement('dialog')
+
+    const toggleButton = document.createElement('a')
+    toggleButton.classList.add('toggle-button')
+    toggleButton.textContent = 'Open CopyTuner'
+    toggleButton.addEventListener('click', () => this.#onToggle())
+
+    shadow.append(this.dialog, toggleButton)
+  }
+
+  set onToggle(callback: () => void) {
+    this.#onToggle = callback
+  }
+}