textus 0.14.1 → 0.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f46590895cb1b7dccf71efbb6cc7632ac1054e545323478e831875c7b7bf621
-  data.tar.gz: e84857018c0bf4e61e6e60a476191e04dd2fe470f476b27860deaf59611993ab
+  metadata.gz: 4a732844e2441328f7519ffd93571c3ff611fd0514c2b1f927b5c4ada499db16
+  data.tar.gz: 63a3e530439c37fbbff8c8b3864b1489cd34c88c88bd1c10f03ae980f4a66041
 SHA512:
-  metadata.gz: e21ff9e7d9a9cfe93ab3865646b53bbea4647f0c7ace9d329e7ccec13a2ce7343568df836bd25fccfa19c39d4384a2d522d827e5d01b7ebbdd0b2ab3098978be
-  data.tar.gz: 700e831af5ba5c13a9e66984e59ee4774def27e1c098b7dfd2d6e942b6cd064b7e3e3d1480faa110417ede67aa229d0b7bfea063f8f5f59e91bcaa0dce282355
+  metadata.gz: 5470a6aaf29f1b081144b2eca3b1e87e5b1d465977422c967366196d259041cdbb8e0993ce293d87d7903f9446649f80ea99e1e6367b9731f7b839bf18f9d67f
+  data.tar.gz: dcd3f57064d2f6753f049daf1315a937566e3b77a9ec130455a54410292f73ec55104bafe1e1b20431dc186a1c13735a7e6c6018ef8f54b77122f0eb2e267e8c

data/CHANGELOG.md

@@ -9,6 +9,31 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.14.2 — 2026-05-26
+
+### Added
+
+- Per-rule `fetch_timeout_seconds:` under `rules[].refresh` overrides the
+  hardcoded 30s worker timeout that applies to intake handlers invoked
+  via the refresh pipeline (`textus refresh <key>`, `textus refresh
+  stale`, and read-path `on_stale: sync` / `timed_sync`). Default stays
+  at 30s — opt-in only. Schema validates a positive integer ≤ 3600.
+  Mirrors `sync_budget_ms` plumbing: schema → rules → policy → worker
+  (#54).
+
+### Notes
+
+- `fetch_timeout_seconds` is the worker-side hard cap on the intake
+  call; `sync_budget_ms` is the caller-side wait budget for `timed_sync`
+  on the read path. Two separate concerns, two separate keys.
+- The CLI verbs `textus put --fetch` and `textus hook run` still use the
+  30s constant — only the refresh worker honors the per-rule override in
+  this release.
+- Long timeouts pair with `Timeout.timeout`, which raises in the Ruby
+  thread but does not kill spawned subprocesses. Intake handlers that
+  shell out (e.g. `git clone`) should write to a temp dir and atomically
+  rename so mid-flight aborts leave no observable partial state.
+
 ## 0.14.1 — 2026-05-26
 
 ### Changed

data/lib/textus/application/refresh/worker.rb

@@ -26,6 +26,11 @@ module Textus
           Application::Context.new(store: @ctx.store, role: @ctx.role)
         end
 
+        def fetch_timeout_for(key)
+          rule = @ctx.store.manifest.rules_for(key)
+          rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
+        end
+
         def fetch_with_bus(key, mentry)
           callable = @ctx.store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)
           @bus.publish(:refresh_started, store: read_view, key: key, mode: :sync,
@@ -34,14 +39,15 @@ module Textus
         end
 
         def call_intake(key, mentry, callable)
-          Timeout.timeout(FETCH_TIMEOUT_SECONDS) do
+          timeout = fetch_timeout_for(key)
+          Timeout.timeout(timeout) do
             callable.call(store: @ctx, config: mentry.intake_config, args: {})
           end
         rescue Timeout::Error
           @bus.publish(:refresh_failed, store: read_view, key: key, error_class: "Timeout::Error",
-                                        error_message: "intake '#{mentry.intake_handler}' exceeded #{FETCH_TIMEOUT_SECONDS}s",
+                                        error_message: "intake '#{mentry.intake_handler}' exceeded #{timeout}s",
                                         correlation_id: @ctx.correlation_id)
-          raise UsageError.new("intake '#{mentry.intake_handler}' exceeded #{FETCH_TIMEOUT_SECONDS}s timeout")
+          raise UsageError.new("intake '#{mentry.intake_handler}' exceeded #{timeout}s timeout")
         rescue Textus::Error => e
           @bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
                                         error_message: e.message, correlation_id: @ctx.correlation_id)

data/lib/textus/cli/verb/rule_list.rb

@@ -10,6 +10,7 @@ module Textus
                 "ttl_seconds" => b.refresh.ttl_seconds,
                 "on_stale" => b.refresh.on_stale,
                 "sync_budget_ms" => b.refresh.sync_budget_ms,
+                "fetch_timeout_seconds" => b.refresh.fetch_timeout_seconds,
               }
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist

data/lib/textus/domain/policy/refresh.rb

@@ -2,9 +2,9 @@ module Textus
   module Domain
     module Policy
       class Refresh
-        attr_reader :ttl, :on_stale, :sync_budget_ms
+        attr_reader :ttl, :on_stale, :sync_budget_ms, :fetch_timeout_seconds
 
-        def initialize(ttl:, on_stale:, sync_budget_ms:)
+        def initialize(ttl:, on_stale:, sync_budget_ms:, fetch_timeout_seconds: nil)
           on_stale_sym = on_stale.is_a?(Symbol) ? on_stale : on_stale.to_s.to_sym
           unless ALLOWED_ON_STALE.include?(on_stale_sym)
             raise Textus::UsageError.new(
@@ -12,9 +12,10 @@ module Textus
             )
           end
 
-          @ttl            = ttl
-          @on_stale       = on_stale_sym
-          @sync_budget_ms = sync_budget_ms
+          @ttl                   = ttl
+          @on_stale              = on_stale_sym
+          @sync_budget_ms        = sync_budget_ms
+          @fetch_timeout_seconds = fetch_timeout_seconds
         end
 
         def ttl_seconds

data/lib/textus/manifest/rules.rb

@@ -63,6 +63,7 @@ module Textus
             ttl: h["ttl"],
             on_stale: h["on_stale"] || "warn",
             sync_budget_ms: h["sync_budget_ms"],
+            fetch_timeout_seconds: h["fetch_timeout_seconds"],
           )
         end
 

data/lib/textus/manifest/schema.rb

@@ -11,7 +11,8 @@ module Textus
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
       RULE_KEYS    = %w[match refresh intake_handler_allowlist promotion retention].freeze
-      REFRESH_KEYS = %w[ttl on_stale sync_budget_ms].freeze
+      REFRESH_KEYS = %w[ttl on_stale sync_budget_ms fetch_timeout_seconds].freeze
+      FETCH_TIMEOUT_SECONDS_CEILING = 3600
       PROMOTION_KEYS = %w[requires].freeze
 
       def self.validate!(raw)
@@ -30,11 +31,23 @@ module Textus
         Array(raw["rules"]).each_with_index do |r, i|
           path = "$.rules[#{i}]"
           walk(r, RULE_KEYS, path)
-          walk(r["refresh"], REFRESH_KEYS, "#{path}.refresh") if r["refresh"].is_a?(Hash)
+          if r["refresh"].is_a?(Hash)
+            walk(r["refresh"], REFRESH_KEYS, "#{path}.refresh")
+            validate_fetch_timeout!(r["refresh"]["fetch_timeout_seconds"], "#{path}.refresh.fetch_timeout_seconds")
+          end
           walk(r["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
         end
       end
 
+      def self.validate_fetch_timeout!(value, path)
+        return if value.nil?
+        return if value.is_a?(Integer) && value.positive? && value <= FETCH_TIMEOUT_SECONDS_CEILING
+
+        raise BadManifest.new(
+          "fetch_timeout_seconds at '#{path}' must be a positive integer ≤ #{FETCH_TIMEOUT_SECONDS_CEILING} (got #{value.inspect})",
+        )
+      end
+
       def self.walk(hash, allowed, path)
         return unless hash.is_a?(Hash)
 

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.14.1"
+  VERSION = "0.14.2"
   PROTOCOL = "textus/3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.14.2
 platform: ruby
 authors:
 - Patrick