textus 0.26.0 → 0.30.0

data/lib/textus/write/authority_gate.rb

@@ -0,0 +1,24 @@
+module Textus
+  module Write
+    # Shared gate for write verbs that require the caller to hold the
+    # manifest's accept_authority role. Provides one method, expressed
+    # as two early-returns rather than a ternary, so each failure mode
+    # reads on its own line.
+    module AuthorityGate
+      def assert_accept_authority!(verb)
+        return if @manifest.policy.role_kind(@call.role) == :accept_authority
+
+        authority = @manifest.policy.roles_with_kind(:accept_authority).first
+        if authority.nil?
+          raise ProposalError.new(
+            "no role with accept_authority kind is declared in this manifest; #{verb} is disabled",
+          )
+        end
+
+        raise ProposalError.new(
+          "only #{authority} role can #{verb} proposals; got '#{@call.role}'",
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/delete.rb

@@ -0,0 +1,40 @@
+module Textus
+  module Write
+    class Delete
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @authorizer   = container.authorizer
+        @events       = container.events
+      end
+
+      def call(key, if_etag: nil, suppress_events: false)
+        Textus::Manifest::Data.validate_key!(key)
+        mentry = @manifest.resolver.resolve(key).entry
+
+        @authorizer.authorize_write!(mentry, role: @call.role)
+
+        writer.delete(key, mentry: mentry, if_etag: if_etag)
+
+        unless suppress_events
+          @events.publish(:entry_deleted,
+                          ctx: hook_context,
+                          key: key)
+        end
+
+        { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/write/intake_fetch.rb

@@ -0,0 +1,23 @@
+require "timeout"
+
+module Textus
+  module Write
+    # Invokes a :resolve_intake hook handler by name under a timeout.
+    # The transport-side fetch kernel shared by `textus put --fetch` and
+    # `textus hook run`. Maps Timeout::Error to a UsageError; leaves any
+    # other error to the caller (call sites differ in how they wrap those).
+    module IntakeFetch
+      FETCH_TIMEOUT_SECONDS = 30
+
+      module_function
+
+      def invoke(rpc:, handler:, config:, args:, label:, timeout: FETCH_TIMEOUT_SECONDS)
+        Timeout.timeout(timeout) do
+          rpc.invoke(:resolve_intake, handler, caps: nil, config: config, args: args)
+        end
+      rescue Timeout::Error
+        raise Textus::UsageError.new("#{label} '#{handler}' exceeded #{timeout}s timeout")
+      end
+    end
+  end
+end

data/lib/textus/write/materializer.rb

@@ -0,0 +1,48 @@
+require "fileutils"
+
+module Textus
+  module Write
+    # Materializes a single Derived manifest entry onto disk by running
+    # the builder pipeline (template + projection + external runner).
+    # Extracted from Write::Build so that Publish can reuse
+    # it without creating a Build dependency.
+    class Materializer
+      def initialize(container:, call:)
+        @container  = container
+        @call       = call
+        @manifest   = container.manifest
+        @file_store = container.file_store
+        @rpc        = container.rpc
+        @root       = container.root
+      end
+
+      # Runs the builder pipeline for `mentry` and returns the on-disk
+      # target_path string.
+      def run(mentry)
+        reader = Textus::Read::Get.new(container: @container, call: @call)
+        lister = Textus::Read::List.new(container: @container)
+        Builder::Pipeline.run(
+          mentry: mentry,
+          deps: Builder::Pipeline::Deps.new(
+            manifest: @manifest,
+            reader: reader.method(:call),
+            lister: lister.method(:call),
+            rpc: @rpc,
+            template_loader: ->(name) { read_template(name) },
+            transform_context: @container,
+            inject_boot: -> { Textus::Boot.build(container: @container) },
+          ),
+        )
+      end
+
+      private
+
+      def read_template(name)
+        tpl_path = File.join(@root, "templates", name)
+        raise TemplateError.new("template not found: #{tpl_path}", template_name: name) unless File.exist?(tpl_path)
+
+        File.read(tpl_path)
+      end
+    end
+  end
+end

data/lib/textus/write/mv.rb

@@ -0,0 +1,113 @@
+module Textus
+  module Write
+    class Mv
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @events       = container.events
+        @authorizer   = container.authorizer
+      end
+
+      def call(old_key, new_key, dry_run: false)
+        old_res, new_res = prepare(old_key, new_key)
+        return dry_run_result(old_key, new_key, old_res, new_res) if dry_run
+
+        ensure_uid!(old_key, old_res.entry)
+        envelope = writer.move(
+          from_key: old_key, to_key: new_key,
+          new_mentry: new_res.entry
+        )
+        publish_renamed(old_key, new_key, envelope)
+        success_result(old_key, new_key, old_res, new_res, envelope)
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def prepare(old_key, new_key)
+        Textus::Manifest::Data.validate_key!(old_key)
+        Textus::Manifest::Data.validate_key!(new_key)
+        raise UsageError.new("mv: old and new keys are identical") if old_key == new_key
+
+        old_res = @manifest.resolver.resolve(old_key)
+        new_res = @manifest.resolver.resolve(new_key)
+        raise UnknownKey.new(old_key) unless reader.exists?(old_key)
+
+        validate_zone_and_format!(old_res.entry, new_res.entry)
+        @authorizer.authorize_write!(old_res.entry, role: @call.role)
+        @authorizer.authorize_write!(new_res.entry, role: @call.role)
+        raise UsageError.new("mv: target '#{new_key}' already exists at #{new_res.path}") if reader.exists?(new_key)
+
+        [old_res, new_res]
+      end
+
+      def validate_zone_and_format!(old_mentry, new_mentry)
+        if old_mentry.zone != new_mentry.zone
+          raise UsageError.new(
+            "mv: cross-zone move refused (#{old_mentry.zone} → #{new_mentry.zone}). " \
+            "Use put+delete for cross-zone moves.",
+          )
+        end
+        return if old_mentry.format == new_mentry.format
+
+        raise UsageError.new("mv: format mismatch (#{old_mentry.format} → #{new_mentry.format}); refusing.")
+      end
+
+      # If the source file lacks a UID, rewrite it in-place via the writer
+      # so a UID gets injected before the move. This produces one "put"
+      # audit row, then the "mv" row from Writer#move.
+      def ensure_uid!(old_key, old_mentry)
+        pre_env = reader.read(old_key)
+        return if pre_env.uid
+
+        writer.put(
+          old_key, mentry: old_mentry,
+                   payload: Textus::Envelope::IO::Writer::Payload.new(
+                     meta: pre_env.meta, body: pre_env.body, content: pre_env.content,
+                   )
+        )
+      end
+
+      def publish_renamed(old_key, new_key, envelope)
+        @events.publish(:entry_renamed,
+                        ctx: hook_context,
+                        key: new_key,
+                        from_key: old_key,
+                        to_key: new_key,
+                        envelope: envelope)
+      end
+
+      def dry_run_result(old_key, new_key, old_res, new_res)
+        pre_env = reader.read(old_key)
+        {
+          "protocol" => PROTOCOL, "ok" => true, "dry_run" => true,
+          "from_key" => old_key, "to_key" => new_key,
+          "from_path" => old_res.path, "to_path" => new_res.path,
+          "uid" => pre_env.uid
+        }
+      end
+
+      def success_result(old_key, new_key, old_res, new_res, envelope)
+        {
+          "protocol" => PROTOCOL, "ok" => true,
+          "from_key" => old_key, "to_key" => new_key,
+          "from_path" => old_res.path, "to_path" => new_res.path,
+          "uid" => envelope.uid,
+          "envelope" => envelope.to_h_for_wire
+        }
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
+      end
+
+      def reader
+        @reader ||= Textus::Envelope::IO::Reader.from(container: @container)
+      end
+    end
+  end
+end

data/lib/textus/write/publish.rb

@@ -0,0 +1,66 @@
+module Textus
+  module Write
+    # Single-pass publish use case: dispatches polymorphically to each
+    # entry's `publish_via` method. Derived entries materialize their body
+    # via Materializer; Nested entries fan out via publish_each; Leaf and
+    # Intake entries copy their stored body to publish_to targets. The
+    # Publish layer owns wiring (context, accumulation) but not per-kind
+    # logic.
+    #
+    # Return shape: { "protocol", "built", "published_leaves" }
+    class Publish
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+      end
+
+      def call(prefix: nil)
+        built  = []
+        leaves = []
+        context = build_context
+
+        @manifest.data.entries.each do |mentry|
+          next if prefix && !entry_matches_prefix?(mentry, prefix)
+
+          result = mentry.publish_via(context, prefix: prefix)
+          next if result.nil?
+
+          case result[:kind]
+          when :built  then built << result[:value]
+          when :leaves then leaves.concat(result[:value])
+          end
+        end
+
+        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves }
+      end
+
+      private
+
+      def build_context
+        Textus::Manifest::Entry::Base::PublishContext.new(
+          container: @container,
+          call: @call,
+          reader: reader,
+        )
+      end
+
+      # Whether the entry should be processed for the given prefix filter.
+      def entry_matches_prefix?(mentry, prefix)
+        return true unless prefix
+
+        case mentry
+        when Textus::Manifest::Entry::Nested
+          mentry.key.start_with?(prefix) ||
+            prefix.start_with?("#{mentry.key}.")
+        else
+          mentry.key.start_with?(prefix)
+        end
+      end
+
+      def reader
+        @reader ||= Textus::Read::Get.new(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/write/put.rb

@@ -0,0 +1,45 @@
+module Textus
+  module Write
+    class Put
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @authorizer   = container.authorizer
+        @events       = container.events
+      end
+
+      def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
+        Textus::Manifest::Data.validate_key!(key)
+        mentry = @manifest.resolver.resolve(key).entry
+        @authorizer.authorize_write!(mentry, role: @call.role)
+
+        envelope = writer.put(
+          key,
+          mentry: mentry,
+          payload: Textus::Envelope::IO::Writer::Payload.new(
+            meta: meta, body: body, content: content,
+          ),
+          if_etag: if_etag,
+        )
+
+        @events.publish(:entry_put,
+                        ctx: hook_context,
+                        key: key,
+                        envelope: envelope)
+
+        envelope
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/write/refresh_all.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Write
+    class RefreshAll
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+      end
+
+      def call(prefix: nil, zone: nil)
+        worker = Textus::Write::RefreshWorker.new(
+          container: @container, call: @call,
+        )
+
+        stale_rows = Textus::Read::Stale.new(container: @container, call: @call).call(prefix: prefix, zone: zone)
+        refreshed = []
+        failed = []
+        skipped = []
+
+        stale_rows.each do |row|
+          key = row["key"] || row[:key]
+          reason = row["reason"] || row[:reason]
+          if reason.to_s.match?(/ttl exceeded|never refreshed/)
+            begin
+              worker.run(key)
+              refreshed << key
+            rescue Textus::Error => e
+              failed << { "key" => key, "error" => e.message }
+            end
+          else
+            skipped << { "key" => key, "reason" => reason }
+          end
+        end
+
+        {
+          "protocol" => Textus::PROTOCOL,
+          "ok" => failed.empty?,
+          "refreshed" => refreshed,
+          "failed" => failed,
+          "skipped" => skipped,
+        }
+      end
+    end
+  end
+end

data/lib/textus/write/refresh_orchestrator.rb

@@ -0,0 +1,102 @@
+module Textus
+  module Write
+    class RefreshOrchestrator
+      # Collaborator (not a Dispatcher verb): constructed directly by RefreshWorker /
+      # GetOrRefresh, which pass their derived hook_context in. That's why this takes
+      # hook_context: explicitly while verb use cases derive their own.
+      def initialize(worker:, store_root:, events:, hook_context: nil, detached_spawner: nil)
+        @worker       = worker
+        @store_root   = store_root
+        @events       = events
+        @hook_context = hook_context
+        @detached_spawner = detached_spawner || default_spawner
+      end
+
+      def execute(action, key:)
+        case action
+        when Textus::Domain::Action::Return       then Textus::Domain::Outcome::Skipped.new
+        when Textus::Domain::Action::RefreshSync  then run_sync(key)
+        when Textus::Domain::Action::RefreshTimed then run_timed(action.budget_ms, key)
+        else raise ArgumentError.new("unknown action: #{action.inspect}")
+        end
+      end
+
+      private
+
+      def run_sync(key)
+        envelope = @worker.run(key)
+        Textus::Domain::Outcome::Refreshed.new(envelope: envelope)
+      rescue Textus::Error => e
+        Textus::Domain::Outcome::Failed.new(error: e)
+      end
+
+      def run_timed(budget_ms, key)
+        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Refresh::Detached.supported?
+
+        run_timed_cooperative(budget_ms, key)
+      end
+
+      def run_timed_cooperative(budget_ms, key)
+        result = nil
+        thread = Thread.new do
+          result = @worker.run(key)
+        rescue Textus::Error => e
+          result = e
+        end
+
+        thread.join(budget_ms / 1000.0)
+        if thread.alive?
+          thread.kill
+          return Textus::Domain::Outcome::Failed.new(
+            error: Textus::UsageError.new(
+              "refresh exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
+            ),
+          )
+        end
+
+        if result.is_a?(Textus::Error)
+          Textus::Domain::Outcome::Failed.new(error: result)
+        else
+          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+        end
+      end
+
+      def run_timed_with_fork(budget_ms, key)
+        result = nil
+        thread = Thread.new do
+          result = @worker.run(key)
+        rescue Textus::Error => e
+          result = e
+        end
+
+        thread.join(budget_ms / 1000.0)
+
+        if thread.alive?
+          thread.kill
+
+          # Single-flight: if a sibling process / earlier fork holds the
+          # per-leaf lock, don't fork another worker — they're already
+          # doing this work.
+          probe = Textus::Ports::Refresh::Lock.new(root: @store_root, key: key)
+          return Textus::Domain::Outcome::Detached.new unless probe.try_acquire
+
+          probe.release
+
+          payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
+          payload[:ctx] = @hook_context if @hook_context
+          @events.publish(:refresh_backgrounded, **payload)
+          @detached_spawner.call(store_root: @store_root, key: key)
+          Textus::Domain::Outcome::Detached.new
+        elsif result.is_a?(Textus::Error)
+          Textus::Domain::Outcome::Failed.new(error: result)
+        else
+          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+        end
+      end
+
+      def default_spawner
+        Textus::Ports::Refresh::Detached.method(:spawn)
+      end
+    end
+  end
+end

data/lib/textus/write/refresh_worker.rb

@@ -0,0 +1,124 @@
+require "timeout"
+
+module Textus
+  module Write
+    class RefreshWorker
+      FETCH_TIMEOUT_SECONDS = IntakeFetch::FETCH_TIMEOUT_SECONDS
+
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @events       = container.events
+        @rpc          = container.rpc
+        @authorizer   = container.authorizer
+      end
+
+      # call(key) is the primary entry; run is kept as an alias for
+      # Orchestrator and RefreshAll which call worker.run(key).
+      def call(key)
+        run(key)
+      end
+
+      def run(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        remaining = res.remaining
+        raise UsageError.new("no intake declared for '#{key}'") unless mentry.is_a?(Textus::Manifest::Entry::Intake)
+
+        before_etag = File.exist?(path) ? Etag.for_file(path) : nil
+        result = fetch_with_events(key, mentry, remaining)
+        persist_and_notify(key, mentry, result, before_etag)
+      end
+
+      def self.normalize_action_result(res, format:)
+        res = res.transform_keys(&:to_s) if res.is_a?(Hash)
+        res ||= {}
+        meta_val = res["_meta"]
+        body     = res["body"]
+        content  = res["content"]
+
+        case format
+        when "markdown" then { meta: meta_val || {}, body: body.to_s, content: nil }
+        when "text"     then { meta: {}, body: body.to_s, content: nil }
+        when "json", "yaml"
+          if !content.nil?
+            { meta: meta_val || {}, body: nil, content: content }
+          elsif !body.nil?
+            { meta: {}, body: body.to_s, content: nil }
+          else
+            raise Textus::UsageError.new("intake for #{format} returned neither content nor body")
+          end
+        else
+          raise Textus::UsageError.new("unknown format #{format.inspect}")
+        end
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def fetch_timeout_for(key)
+        rule = @manifest.rules.for(key)
+        rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
+      end
+
+      def fetch_with_events(key, mentry, remaining)
+        @events.publish(:refresh_started, ctx: hook_context, key: key, mode: :sync)
+        call_intake(key, mentry, remaining)
+      end
+
+      def call_intake(key, mentry, remaining)
+        timeout = fetch_timeout_for(key)
+        Timeout.timeout(timeout) do
+          @rpc.invoke(:resolve_intake, mentry.handler,
+                      caps: @container,
+                      config: mentry.config,
+                      args: { trigger_key: key, leaf_segments: remaining || [] })
+        end
+      rescue Timeout::Error
+        @events.publish(:refresh_failed, ctx: hook_context, key: key,
+                                         error_class: "Timeout::Error",
+                                         error_message: "intake '#{mentry.handler}' exceeded #{timeout}s")
+        raise UsageError.new("intake '#{mentry.handler}' exceeded #{timeout}s timeout")
+      rescue Textus::Error => e
+        @events.publish(:refresh_failed, ctx: hook_context, key: key, error_class: e.class.name,
+                                         error_message: e.message)
+        raise
+      rescue StandardError => e
+        @events.publish(:refresh_failed, ctx: hook_context, key: key, error_class: e.class.name,
+                                         error_message: e.message)
+        raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
+      end
+
+      def persist_and_notify(key, mentry, result, before_etag)
+        normalized = self.class.normalize_action_result(result, format: mentry.format)
+        @authorizer.authorize_write!(mentry, role: @call.role)
+        envelope = writer.put(
+          key,
+          mentry: mentry,
+          payload: Textus::Envelope::IO::Writer::Payload.new(
+            meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
+          ),
+        )
+        change = detect_change(before_etag, envelope)
+        @events.publish(:entry_refreshed, ctx: hook_context, key: key, envelope: envelope, change: change) unless change == :unchanged
+        envelope
+      end
+
+      def detect_change(before_etag, envelope)
+        if before_etag.nil? then :created
+        elsif envelope.etag == before_etag then :unchanged
+        else :updated
+        end
+      end
+
+      def writer
+        @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/write/reject.rb

@@ -0,0 +1,54 @@
+require_relative "authority_gate"
+
+module Textus
+  module Write
+    class Reject
+      include AuthorityGate
+
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @events       = container.events
+      end
+
+      def call(pending_key)
+        assert_accept_authority!("reject")
+
+        mentry = @manifest.resolver.resolve(pending_key).entry
+        unless mentry.in_proposal_zone?(@manifest.policy)
+          raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})")
+        end
+
+        env = Textus::Read::Get.new(
+          container: @container, call: @call,
+        ).call(pending_key)
+        proposal = env.meta&.dig("proposal") or
+          raise ProposalError.new("entry has no proposal block: #{pending_key}")
+        target_key = proposal["target_key"] or
+          raise ProposalError.new("proposal missing target_key")
+
+        delete_op.call(pending_key, suppress_events: true)
+
+        @events.publish(:proposal_rejected,
+                        ctx: hook_context,
+                        key: pending_key,
+                        target_key: target_key)
+
+        { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def delete_op
+        @delete_op ||= Textus::Write::Delete.new(
+          container: @container, call: @call,
+        )
+      end
+    end
+  end
+end