textus 0.14.1 → 0.14.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f46590895cb1b7dccf71efbb6cc7632ac1054e545323478e831875c7b7bf621
-  data.tar.gz: e84857018c0bf4e61e6e60a476191e04dd2fe470f476b27860deaf59611993ab
+  metadata.gz: 65cfe5f73a64dda44280d1dd58e418aecdc94b79e1abb68340e973d364da3465
+  data.tar.gz: c35f1428a0965c11c946395a8fb7dfeb60202e2fac2514b1bb04dfae1e426ed2
 SHA512:
-  metadata.gz: e21ff9e7d9a9cfe93ab3865646b53bbea4647f0c7ace9d329e7ccec13a2ce7343568df836bd25fccfa19c39d4384a2d522d827e5d01b7ebbdd0b2ab3098978be
-  data.tar.gz: 700e831af5ba5c13a9e66984e59ee4774def27e1c098b7dfd2d6e942b6cd064b7e3e3d1480faa110417ede67aa229d0b7bfea063f8f5f59e91bcaa0dce282355
+  metadata.gz: edeefd203bb0f4af807457cb96353affd3a21de846331481bb3d6e69e344fc1ea8054f8066ed278e7a7ced366704a65df00269d38b58a5b729d408477bc4f5a5
+  data.tar.gz: 4c30fa46409c381bfa8ef381c38314ce988786b9f2cf81c8b1c76f7508301587b9e5562ce1ced415f85484fe794fe3aeff5186203f733cedea34443d43a4eb57

data/CHANGELOG.md

@@ -9,6 +9,46 @@ 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.3 — 2026-05-26
+
+### Added
+
+- Top-level `flock(2)` mutex at `<root>/.build.lock` prevents concurrent
+  `textus build` invocations against the same store. A second build
+  while one is already running exits with code `75` (`EX_TEMPFAIL`) and
+  emits a `build_in_progress` error envelope, so wrappers like `rake
+  update` and CI can distinguish "another build is busy" from "this
+  build is broken". The lock is FD-bound and released by the kernel on
+  process death (including SIGKILL/OOM), so no stale-lock takeover
+  logic is needed. `close_on_exec` prevents the lock from leaking into
+  `bundle exec` and lefthook child processes. Per-key locks under
+  `.locks/` are unchanged. (#56)
+
+## 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/build.rb

@@ -5,12 +5,14 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          ops = Textus::Operations.for(store, role: "builder")
-          build_res   = ops.writes.build.call(prefix: prefix)
-          publish_res = ops.writes.publish.call(prefix: prefix)
-          emit({ "protocol" => Textus::PROTOCOL,
-                 "built" => build_res["built"],
-                 "published_leaves" => publish_res["published_leaves"] })
+          Textus::Infra::BuildLock.with(root: store.root) do
+            ops = Textus::Operations.for(store, role: "builder")
+            build_res   = ops.writes.build.call(prefix: prefix)
+            publish_res = ops.writes.publish.call(prefix: prefix)
+            emit({ "protocol" => Textus::PROTOCOL,
+                   "built" => build_res["built"],
+                   "published_leaves" => publish_res["published_leaves"] })
+          end
         end
       end
     end

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/errors.rb

@@ -122,6 +122,18 @@ module Textus
     def initialize(m) = super("io_error", m, exit_code: 64)
   end
 
+  class BuildInProgress < Error
+    def initialize(holder)
+      super(
+        "build_in_progress",
+        "textus build already running (#{holder})",
+        details: { "holder" => holder },
+        exit_code: 75,
+        hint: "wait for the running build to finish, or check for a recursive hook trigger"
+      )
+    end
+  end
+
   class UsageError < Error
     def initialize(m, hint: nil) = super("usage", m, exit_code: 2, hint: hint)
   end

data/lib/textus/infra/build_lock.rb

@@ -0,0 +1,59 @@
+require "fileutils"
+require "socket"
+require "time"
+
+module Textus
+  module Infra
+    class BuildLock
+      LOCK_FILENAME = ".build.lock"
+      MAX_HOLDER_BYTES = 512
+
+      def self.with(root:, &)
+        new(root: root).acquire_or_raise(&)
+      end
+
+      def initialize(root:)
+        @path = File.join(root, LOCK_FILENAME)
+        @file = nil
+      end
+
+      def acquire_or_raise
+        FileUtils.mkdir_p(File.dirname(@path))
+        @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
+        @file.close_on_exec = true
+
+        unless @file.flock(File::LOCK_EX | File::LOCK_NB)
+          holder = read_holder_safely
+          @file.close
+          @file = nil
+          raise Textus::BuildInProgress.new(holder)
+        end
+
+        @file.truncate(0)
+        @file.write("pid=#{Process.pid} started=#{Time.now.utc.iso8601} host=#{Socket.gethostname}\n")
+        @file.flush
+
+        yield
+      ensure
+        release
+      end
+
+      private
+
+      def release
+        return unless @file
+
+        @file.flock(File::LOCK_UN)
+        @file.close
+        @file = nil
+      end
+
+      def read_holder_safely
+        content = File.read(@path, MAX_HOLDER_BYTES)
+        content.gsub(/[^[:print:]\t ]/, "").strip
+      rescue StandardError
+        "unknown"
+      end
+    end
+  end
+end

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.3"
   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.3
 platform: ruby
 authors:
 - Patrick
@@ -223,6 +223,7 @@ files:
 - lib/textus/hooks/dsl.rb
 - lib/textus/hooks/loader.rb
 - lib/textus/hooks/registry.rb
+- lib/textus/infra/build_lock.rb
 - lib/textus/infra/clock.rb
 - lib/textus/infra/event_bus.rb
 - lib/textus/infra/publisher.rb