textus 0.8.1 → 0.9.2

data/lib/textus/application/writes/publish.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Application
+    module Writes
+      class Publish
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(source:, target:, key:)
+          Textus::Infra::Publisher.publish(
+            source: source,
+            target: target,
+            store_root: @ctx.store.root,
+          )
+          @bus.publish(:published,
+                       key: key,
+                       source: source,
+                       target: target,
+                       correlation_id: @ctx.correlation_id)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/put.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Application
+    module Writes
+      class Put
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(key, meta: nil, body: nil, content: nil, if_etag: nil, suppress_events: false)
+          @ctx.store.manifest.validate_key!(key)
+          mentry, = @ctx.store.manifest.resolve(key)
+
+          unless @ctx.can_write?(mentry.zone)
+            raise WriteForbidden.new(key, mentry.zone,
+                                     writers: @ctx.store.manifest.zone_writers(mentry.zone))
+          end
+
+          envelope = @ctx.store.writer.write_envelope_to_disk(
+            key,
+            mentry: mentry,
+            meta: meta,
+            body: body,
+            content: content,
+            if_etag: if_etag,
+            as: @ctx.role,
+            correlation_id: @ctx.correlation_id,
+          )
+
+          unless suppress_events
+            store_view = Store::View.new(@ctx.store)
+            @bus.publish(:put,
+                         store: store_view,
+                         key: key,
+                         envelope: envelope,
+                         correlation_id: @ctx.correlation_id)
+          end
+
+          envelope
+        end
+      end
+    end
+  end
+end

data/lib/textus/builder.rb

@@ -1,5 +1,8 @@
 require "fileutils"
 
+# As of 0.9.1, Textus::Application::Writes::Build is the preferred public
+# entry point. This class remains as the implementation home of materialization
+# and projection logic; full extraction is deferred to 0.10.0.
 module Textus
   class Builder
     def initialize(store)
@@ -35,21 +38,27 @@ module Textus
           next unless row[:manifest_entry].equal?(mentry)
           next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
 
-          target_rel = mentry.publish_target_for(row[:key])
-          target_abs = File.expand_path(File.join(repo_root, target_rel))
-          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
-            raise PublishError.new(
-              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-            )
-          end
-
-          Publisher.publish(source: row[:path], target: target_abs, store_root: @root)
-          out << { "key" => row[:key], "source" => row[:path], "target" => target_abs }
+          out << publish_leaf(mentry, row, repo_root)
         end
       end
       out
     end
 
+    def publish_leaf(mentry, row, repo_root)
+      target_rel = mentry.publish_target_for(row[:key])
+      target_abs = File.expand_path(File.join(repo_root, target_rel))
+      unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
+        raise PublishError.new(
+          "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
+        )
+      end
+
+      Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: @root)
+      @store.fire_event(:published, key: row[:key], envelope: @store.get(row[:key]),
+                                    source: row[:path], target: target_abs)
+      { "key" => row[:key], "source" => row[:path], "target" => target_abs }
+    end
+
     def derived_zone?(mentry)
       writers = @manifest.zone_writers(mentry.zone)
       writers.include?("build")
@@ -73,13 +82,17 @@ module Textus
     end
 
     def publish_and_fire(mentry, target_path)
+      envelope = @store.get(mentry.key)
+      repo_root = File.dirname(@root)
+
       mentry.publish_to.each do |rel|
-        repo_root = File.dirname(@root)
-        Publisher.publish(source: target_path, target: File.join(repo_root, rel), store_root: @root)
+        target_abs = File.join(repo_root, rel)
+        Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: @root)
+        @store.fire_event(:published, key: mentry.key, envelope: envelope,
+                                      source: target_path, target: target_abs)
       end
 
-      envelope = @store.get(mentry.key)
-      @store.fire_event(:build, key: mentry.key, envelope: envelope,
+      @store.fire_event(:built, key: mentry.key, envelope: envelope,
                                 sources: Array(mentry.projection&.fetch("select", nil)).compact)
     end
   end

data/lib/textus/cli/group/policy.rb

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Group
+      class Policy < Group
+        self.cli_name = "policy"
+        subcommands["list"]    = Verb::PolicyList
+        subcommands["explain"] = Verb::PolicyExplain
+      end
+    end
+  end
+end

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

@@ -7,7 +7,8 @@ module Textus
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(store.accept(key, as: role))
+          ctx = Textus::Composition.context(store, role: role)
+          emit(Textus::Composition.writes_accept(ctx).call(key))
         end
       end
     end

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

@@ -0,0 +1,31 @@
+module Textus
+  class CLI
+    class Verb
+      class Audit < Verb
+        option :key_filter, "--key=KEY"
+        option :zone, "--zone=Z"
+        option :role_filter, "--role=ROLE"
+        option :verb_filter, "--verb=V"
+        option :since, "--since=ISO8601|RELATIVE"
+        option :correlation_id, "--correlation-id=ID"
+        option :limit, "--limit=N"
+
+        def call(store)
+          role = Role.resolve(flag: nil, env: ENV, root: store.root)
+          ctx = Textus::Composition.context(store, role: role)
+          since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ctx.now)
+          rows = Textus::Composition.audit(ctx).call(
+            key: key_filter,
+            zone: zone,
+            role: role_filter,
+            verb: verb_filter,
+            since: since_time,
+            correlation_id: correlation_id,
+            limit: limit&.to_i,
+          )
+          emit({ "verb" => "audit", "rows" => rows })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Textus
+  class CLI
+    class Verb
+      class Blame < Verb
+        option :limit, "--limit=N"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("blame requires a key")
+          role = Role.resolve(flag: nil, env: ENV, root: store.root)
+          ctx = Textus::Composition.context(store, role: role)
+          rows = Textus::Composition.blame(ctx).call(key: key, limit: limit&.to_i)
+          emit({ "verb" => "blame", "key" => key, "rows" => rows })
+        end
+      end
+    end
+  end
+end

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

@@ -5,7 +5,8 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          emit(Textus::Builder.new(store).build(prefix: prefix))
+          ctx = Textus::Composition.context(store, role: "build")
+          emit(Textus::Composition.writes_build(ctx).call(prefix: prefix))
         end
       end
     end

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

@@ -8,7 +8,8 @@ module Textus
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(store.delete(key, if_etag: if_etag, as: role))
+          ctx = Textus::Composition.context(store, role: role)
+          emit(Textus::Composition.writes_delete(ctx).call(key, if_etag: if_etag))
         end
       end
     end

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

@@ -0,0 +1,17 @@
+module Textus
+  class CLI
+    class Verb
+      class Freshness < Verb
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+
+        def call(store)
+          role = Role.resolve(flag: nil, env: ENV, root: store.root)
+          ctx = Textus::Composition.context(store, role: role)
+          rows = Textus::Composition.freshness(ctx).call(prefix: prefix, zone: zone)
+          emit({ "verb" => "freshness", "rows" => rows })
+        end
+      end
+    end
+  end
+end

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

@@ -2,9 +2,16 @@ module Textus
   class CLI
     class Verb
       class Get < Verb
+        option :as_flag, "--as=ROLE"
+
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          emit(store.get(key))
+          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+          ctx = Textus::Composition.context(store, role: role)
+          result = Textus::Composition.reads_get(ctx).call(key)
+          raise Textus::UnknownKey.new(key, suggestions: store.manifest.suggestions_for(key)) if result.nil?
+
+          emit(result)
         end
       end
     end

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

@@ -23,16 +23,16 @@ module Textus
           end
 
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          callable = store.registry.rpc_callable(:fetch, name)
+          callable = store.registry.rpc_callable(:intake, name)
           view = Store::View.new(store, writable: true, as: role)
 
           begin
-            Timeout.timeout(Textus::Refresh::FETCH_TIMEOUT_SECONDS) do
+            Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do
               callable.call(config: {}, store: view, args: args)
             end
           rescue Timeout::Error
             raise UsageError.new(
-              "hook run '#{name}' exceeded #{Textus::Refresh::FETCH_TIMEOUT_SECONDS}s timeout",
+              "hook run '#{name}' exceeded #{Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS}s timeout",
             )
           rescue Textus::Error
             raise

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

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class Verb
+      class PolicyExplain < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("policy explain requires a KEY")
+          role = Role.resolve(flag: nil, env: ENV, root: store.root)
+          ctx = Textus::Composition.context(store, role: role)
+          result = Textus::Composition.policy_explain(ctx).call(key: key)
+          emit({ "verb" => "policy_explain" }.merge(result.transform_keys(&:to_s)))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Textus
+  class CLI
+    class Verb
+      class PolicyList < Verb
+        def call(store)
+          policies = store.manifest.policies.blocks.map do |b|
+            row = { "match" => b.match }
+            if b.refresh
+              row["refresh"] = {
+                "ttl_seconds" => b.refresh.ttl_seconds,
+                "on_stale" => b.refresh.on_stale,
+                "sync_budget_ms" => b.refresh.sync_budget_ms,
+              }
+            end
+            row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
+            row["promote_requires"] = b.promote.requires if b.promote
+            row["retention"] = b.retention if b.retention
+            row
+          end
+          emit({ "verb" => "policy_list", "policies" => policies })
+        end
+      end
+    end
+  end
+end

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

@@ -15,15 +15,15 @@ module Textus
           raw = @stdin.read
           payload =
             if fetch_name
-              callable = store.registry.rpc_callable(:fetch, fetch_name)
+              callable = store.registry.rpc_callable(:intake, fetch_name)
               result =
                 begin
-                  Timeout.timeout(Textus::Refresh::FETCH_TIMEOUT_SECONDS) do
+                  Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do
                     callable.call(config: { "bytes" => raw }, store: Textus::Store::View.new(store), args: {})
                   end
                 rescue Timeout::Error
                   raise UsageError.new(
-                    "fetch '#{fetch_name}' exceeded #{Textus::Refresh::FETCH_TIMEOUT_SECONDS}s timeout",
+                    "fetch '#{fetch_name}' exceeded #{Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS}s timeout",
                   )
                 end
               basename = key.split(".").last
@@ -42,7 +42,8 @@ module Textus
           meta = payload["_meta"] || payload["frontmatter"] || {}
           body = payload["body"] || ""
           if_etag = payload["if_etag"]
-          emit(store.put(key, meta: meta, body: body, if_etag: if_etag, as: role))
+          ctx = Textus::Composition.context(store, role: role)
+          emit(Textus::Composition.writes_put(ctx).call(key, meta: meta, body: body, if_etag: if_etag))
         end
       end
     end

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

@@ -7,7 +7,8 @@ module Textus
         def call(store)
           key = positional.shift or raise UsageError.new("refresh requires a key")
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          emit(Textus::Refresh.call(store, key, as: role))
+          ctx = Textus::Composition.context(store, role: role)
+          emit(Textus::Composition.refresh_worker(ctx).run(key))
         end
       end
     end

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

@@ -0,0 +1,19 @@
+module Textus
+  class CLI
+    class Verb
+      class RefreshStale < Verb
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+          ctx = Textus::Composition.context(store, role: role)
+          result = Textus::Application::Refresh::All.call(ctx, prefix: prefix, zone: zone)
+          emit(result)
+          exit(1) unless result["ok"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class Verb
+      class Reject < Verb
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("reject requires a key")
+          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+          emit(store.reject(key, as: role))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli.rb

@@ -7,22 +7,27 @@ module Textus
     # plus a new file under lib/textus/cli/.
     VERBS = {
       "accept" => Verb::Accept,
+      "audit" => Verb::Audit,
+      "blame" => Verb::Blame,
+      "reject" => Verb::Reject,
       "build" => Verb::Build,
       "delete" => Verb::Delete,
       "deps" => Verb::Deps,
       "doctor" => Verb::Doctor,
+      "freshness" => Verb::Freshness,
       "get" => Verb::Get,
       "hook" => Group::Hook,
       "init" => Verb::Init,
       "intro" => Verb::Intro,
       "key" => Group::Key,
       "list" => Verb::List,
+      "policy" => Group::Policy,
       "published" => Verb::Published,
       "put" => Verb::Put,
       "rdeps" => Verb::Rdeps,
       "refresh" => Verb::Refresh,
+      "refresh-stale" => Verb::RefreshStale,
       "schema" => Group::Schema,
-      "stale" => Verb::Stale,
       "where" => Verb::Where,
     }.freeze
 
@@ -48,6 +53,10 @@ module Textus
                                   0
       when "--help", "-h"    then print_help
                                   0
+      when "stale"
+        raise UsageError.new(
+          "textus stale was removed in 0.9.2 — use `textus freshness` instead",
+        )
       else
         klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
         dispatch(klass, argv)
@@ -84,13 +93,18 @@ module Textus
           textus where KEY
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
-          textus stale [--prefix=KEY] [--zone=Z]
+          textus freshness [--prefix=KEY] [--zone=Z]
+          textus refresh-stale [--prefix=KEY] [--zone=Z]
+          textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
+          textus blame KEY [--limit=N]
           textus doctor
           textus intro
 
           textus key {mv,uid,migrate}
           textus schema {show,init,diff,migrate}
           textus hook {list,run}
+          textus policy {list,explain}
+          textus migrate {zones,policies}
       HELP
     end
   end

data/lib/textus/composition.rb

@@ -0,0 +1,71 @@
+module Textus
+  module Composition
+    module_function
+
+    def context(store, role:, correlation_id: nil, dry_run: false)
+      Textus::Application::Context.new(
+        store: store,
+        role: role,
+        correlation_id: correlation_id,
+        dry_run: dry_run,
+      )
+    end
+
+    def reads_get(ctx)
+      Textus::Application::Reads::Get.new(ctx: ctx, orchestrator: refresh_orchestrator(ctx))
+    end
+
+    def freshness(ctx)
+      Textus::Application::Reads::Freshness.new(ctx: ctx)
+    end
+
+    def audit(ctx)
+      Textus::Application::Reads::Audit.new(ctx: ctx)
+    end
+
+    def blame(ctx)
+      Textus::Application::Reads::Blame.new(ctx: ctx)
+    end
+
+    def policy_explain(ctx)
+      Textus::Application::Reads::PolicyExplain.new(ctx: ctx)
+    end
+
+    def refresh_worker(ctx)
+      Textus::Application::Refresh::Worker.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def refresh_orchestrator(ctx)
+      Textus::Application::Refresh::Orchestrator.new(
+        worker: refresh_worker(ctx),
+        bus: ctx.store.bus,
+        store_root: ctx.store.root,
+        store: ctx.store,
+      )
+    end
+
+    def writes_put(ctx)
+      Textus::Application::Writes::Put.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_delete(ctx)
+      Textus::Application::Writes::Delete.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_build(ctx)
+      Textus::Application::Writes::Build.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_accept(ctx)
+      Textus::Application::Writes::Accept.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def writes_publish(ctx)
+      Textus::Application::Writes::Publish.new(ctx: ctx, bus: ctx.store.bus)
+    end
+
+    def event_bus(ctx)
+      Textus::Infra::EventBus.new(registry: ctx.store.registry)
+    end
+  end
+end

data/lib/textus/doctor/check/handler_allowlist.rb

@@ -0,0 +1,33 @@
+module Textus
+  module Doctor
+    class Check
+      # For every entry with an `intake.handler`, look up its handler_allowlist
+      # policy (if any) and verify the declared handler is allowed. Emits a
+      # failure when the handler is rejected by policy.
+      class HandlerAllowlist < Check
+        def call
+          out = []
+          store.manifest.entries.each do |mentry|
+            handler = mentry.intake_handler
+            next if handler.nil?
+
+            allow = store.manifest.policies_for(mentry.key).handler_allowlist
+            next if allow.nil?
+            next if allow.allows?(handler)
+
+            out << {
+              "code" => "policy.handler_not_allowed",
+              "level" => "error",
+              "subject" => mentry.key,
+              "message" => "entry '#{mentry.key}' declares intake.handler='#{handler}' but the " \
+                           "handler_allowlist policy permits only: #{allow.handlers.join(", ")}",
+              "fix" => "either change intake.handler to one of [#{allow.handlers.join(", ")}], " \
+                       "or extend the handler_allowlist policy in .textus/manifest.yaml",
+            }
+          end
+          out
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/intake_registration.rb

@@ -0,0 +1,46 @@
+module Textus
+  module Doctor
+    class Check
+      class IntakeRegistration < Check
+        BUILTIN = %i[json csv markdown-links ical-events rss].freeze
+
+        def call
+          declared = collect_declared_handlers
+          registered = store.registry.rpc_names(:intake).to_set
+
+          out = (declared - registered).map do |name|
+            {
+              "code" => "intake.handler_missing",
+              "level" => "error",
+              "subject" => name.to_s,
+              "message" => "manifest references intake handler '#{name}' but no Textus.intake(:#{name}) is registered",
+              "fix" => "create .textus/hooks/#{name}.rb with `Textus.intake(:#{name}) { ... }`",
+            }
+          end
+
+          (registered - declared - BUILTIN.to_set).each do |name|
+            out << {
+              "code" => "intake.handler_orphan",
+              "level" => "warning",
+              "subject" => name.to_s,
+              "message" => "Textus.intake(:#{name}) is registered but no manifest entry references it",
+              "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
+            }
+          end
+
+          out
+        end
+
+        private
+
+        def collect_declared_handlers
+          set = Set.new
+          store.manifest.entries.each do |mentry|
+            set << mentry.intake_handler.to_sym if mentry.intake_handler
+          end
+          set
+        end
+      end
+    end
+  end
+end