matsuri 0.1.0 → 0.3.0

data/lib/matsuri/tasks/kubectl_ops/replace.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    module KubectlOps
+      # Full replacement of a live object with a rendered payload.
+      #
+      # One value of the apply_via delivery axis, mutually exclusive with
+      # apply and server-side apply: a resource chooses it with
+      # `let(:apply_via) { :replace }`. No built-in
+      # declares it; the cost of choosing it is that replace clobbers
+      # fields other writers own and never consults
+      # last-applied-configuration — so apply is the default for a reason.
+      class Replace
+        include Matsuri::Task
+
+        let(:input)       { options.fetch(:input) }
+        let(:namespace)   { options.fetch(:namespace) }
+        let(:description) { options.fetch(:description) }
+
+        def run!
+          puts "Replacing #{description}".color(:yellow).bright if verbose
+          puts input if debug
+          kubectl! 'replace -f -', input: input
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/kubectl_ops/rollout_status.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    module KubectlOps
+      # Watches a workload's rollout to completion (kubectl rollout
+      # status) — the post-apply progress watch for manually delivered
+      # changes. Blocks until the rollout finishes or fails.
+      class RolloutStatus
+        include Matsuri::Task
+
+        let(:resource_type) { options.fetch(:resource_type) }
+        let(:name)          { options.fetch(:name) }
+        let(:namespace)     { options.fetch(:namespace) }
+
+        def run!
+          kubectl! "rollout status #{resource_type}/#{name}"
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/kubectl_ops/scale.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    module KubectlOps
+      # Scales a live workload addressed by type/name.
+      class Scale
+        include Matsuri::Task
+
+        let(:resource_type) { options.fetch(:resource_type) }
+        let(:name)          { options.fetch(:name) }
+        let(:namespace)     { options.fetch(:namespace) }
+        let(:replicas)      { options.fetch(:replicas) }
+
+        def run!
+          Matsuri.log :info, "Scaling #{resource_type}/#{name} to #{replicas}".color(:yellow).bright
+          kubectl! "scale --replicas=#{replicas} #{resource_type}/#{name}"
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/kubectl_ops/server_side_apply.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    module KubectlOps
+      # Server-side apply of a rendered manifest payload: the apiserver
+      # merges by field ownership under the given field manager instead
+      # of the client's three-way last-applied merge.
+      #
+      # One value of the apply_via delivery axis
+      # (`let(:apply_via) { :server_side_apply }`). Never passes
+      # --force-conflicts: a conflict marks the frontier where another
+      # manager owns a field this declaration sends, and forcing through
+      # it is an incident-time human judgment — the escape hatch is raw
+      # kubectl, not a flag here.
+      class ServerSideApply
+        include Matsuri::Task
+
+        let(:input)         { options.fetch(:input) }
+        let(:namespace)     { options.fetch(:namespace) }
+        let(:description)   { options.fetch(:description) }
+        let(:field_manager) { options.fetch(:field_manager) }
+
+        def run!
+          puts "Applying (server-side) #{description}".color(:yellow).bright if verbose
+          puts input if debug
+          kubectl! "apply --server-side --field-manager=#{field_manager} -f -", input: input
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/kubectl_ops/status.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    module KubectlOps
+      # Displays the live state of an object addressed by type/name.
+      class Status
+        include Matsuri::Task
+
+        let(:resource_type) { options.fetch(:resource_type) }
+        let(:name)          { options.fetch(:name) }
+        let(:namespace)     { options.fetch(:namespace) }
+
+        def run!
+          kubectl! "get #{resource_type}/#{name} -o wide"
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/kubectl_ops.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    # Delivery mechanism, scoped to kubectl shell-outs. One task per
+    # verb+scenario; resources stay pure generators and the CLI selects
+    # the task. A different delivery mechanism (direct API calls) would
+    # be a sibling namespace, not a branch inside these.
+    #
+    # The module-level functions are the boundary: the single site that
+    # derives task inputs from a rendered resource and reads its delivery
+    # policy lets (apply_via, converge_via, save_config). Present
+    # declarations ride in as pure data (scenario => member list) and the
+    # verb assembles its own scenario's pipeline between the resource and
+    # the task: create-regime verbs assemble :on_create, ongoing-delivery
+    # verbs assemble :on_apply. The empty pipeline is the identity, so
+    # payloads without declarations are byte-identical to the rendered
+    # manifest.
+    module KubectlOps
+      autoload :Apply,    'matsuri/tasks/kubectl_ops/apply'
+      autoload :Create,   'matsuri/tasks/kubectl_ops/create'
+      autoload :Replace,  'matsuri/tasks/kubectl_ops/replace'
+      autoload :ServerSideApply, 'matsuri/tasks/kubectl_ops/server_side_apply'
+      autoload :Delete,   'matsuri/tasks/kubectl_ops/delete'
+      autoload :Recreate, 'matsuri/tasks/kubectl_ops/recreate'
+      autoload :Scale,    'matsuri/tasks/kubectl_ops/scale'
+      autoload :Status,   'matsuri/tasks/kubectl_ops/status'
+      autoload :RolloutStatus, 'matsuri/tasks/kubectl_ops/rollout_status'
+      autoload :Get,      'matsuri/tasks/kubectl_ops/get'
+      autoload :Diff,     'matsuri/tasks/kubectl_ops/diff'
+
+      module_function
+
+      # Under server-side delivery, a resource that is not yet live
+      # routes through the seeding protocol instead: an ordinary apply
+      # cannot land seeds, and nothing we send may ever own them. Every
+      # later apply is the ordinary mechanism. field_manager rides to
+      # every mechanism; only the server-side task reads it.
+      def apply(resource, presenters: {})
+        return Stacks.seed(resource, presenters: presenters) if server_side?(resource.apply_via) && !exists?(resource)
+
+        apply_task_for(resource.apply_via)
+          .new(input:         apply_payload(resource, presenters),
+               namespace:     resource.namespace,
+               description:   description_for(resource),
+               field_manager: resource.field_manager).run!
+      end
+
+      # Routing for the apply_via delivery axis. Unknown values are
+      # fatal — a silent fall-through to client-side apply would deliver
+      # under the wrong merge semantics.
+      def apply_task_for(apply_via)
+        case apply_via
+        when :apply             then Apply
+        when :replace           then Replace
+        when :server_side_apply then ServerSideApply
+        else fail ArgumentError, "unknown apply_via: #{apply_via.inspect}"
+        end
+      end
+
+      def server_side?(apply_via)
+        apply_task_for(apply_via) == ServerSideApply
+      end
+
+      # Whether ongoing delivery under this apply_via consults the
+      # last-applied-configuration annotation. Gates create/recreate's
+      # --save-config: seeding last-applied when nothing consults it arms
+      # a prune trap — a later client-side apply would three-way-merge
+      # against the create payload, seeds included, and prune the seeds.
+      def consults_last_applied?(apply_via)
+        case apply_via
+        when :apply                       then true
+        when :replace, :server_side_apply then false
+        else fail ArgumentError, "unknown apply_via: #{apply_via.inspect}"
+        end
+      end
+
+      def create(resource, presenters: {})
+        creation_task_for(resource, presenters).run!
+      end
+
+      # Bringing into existence: plain create for client-side delivery,
+      # the seeding protocol for server-side. Returned unrun so recreate
+      # can sequence it after teardown.
+      def creation_task_for(resource, presenters)
+        if server_side?(resource.apply_via)
+          Stacks.seed_task(resource, presenters: presenters)
+        else
+          Create.new(input:       payload(resource.manifest_for_export, presenters_for(resource, presenters), :on_create),
+                     namespace:   resource.namespace,
+                     description: description_for(resource),
+                     save_config: consults_last_applied?(resource.apply_via) && resource.save_config)
+        end
+      end
+
+      def delete(resource)
+        Delete.new(identity_for(resource)).run!
+      end
+
+      def recreate(resource, presenters: {})
+        Recreate.new(identity_for(resource)
+          .merge(description: description_for(resource),
+                 create:      creation_task_for(resource, presenters))).run!
+      end
+
+      def scale(resource, replicas)
+        Scale.new(identity_for(resource).merge(replicas: replicas)).run!
+      end
+
+      def status(resource)
+        Status.new(identity_for(resource)).run!
+      end
+
+      def rollout_status(resource)
+        RolloutStatus.new(identity_for(resource)).run!
+      end
+
+      def exists?(resource)
+        Get.new(identity_for(resource)).exists?
+      end
+
+      # Current live manifest as a plain parsed hash; nil when the resource
+      # is not on the cluster.
+      def manifest(resource)
+        Get.new(identity_for(resource)).manifest
+      end
+
+      # Server-side diff of the same payload apply would send: apply_payload
+      # is one site, so the diff can never drift from the delivery — the
+      # invariant extends through presenters. A server-side resource diffs
+      # --server-side under the same field manager apply uses — a different
+      # manager would preview a different conflict frontier. Conflicts
+      # surface as errors (exit 2) and stay loud.
+      def diff(resource, presenters: {})
+        Diff.new(input:         apply_payload(resource, presenters),
+                 namespace:     resource.namespace,
+                 description:   description_for(resource),
+                 server_side:   server_side?(resource.apply_via),
+                 field_manager: resource.field_manager).run!
+      end
+
+      # Lifecycle selection: the resource's converge_via policy picks the
+      # task; the conditional lives here once, not as behavior flags
+      # inside a task.
+      def converge(resource, opts = {}, presenters: {})
+        verbose = Matsuri::Config.verbose
+
+        case resource.converge_via
+        when :recreate
+          puts "Converging #{description_for(resource)} via recreate".color(:yellow) if verbose
+          puts 'Rebuild not implemented. Recreating instead.'.color(:red).bright if opts[:rebuild]
+
+          if opts[:restart] || opts[:rebuild]
+            recreate(resource, presenters: presenters)
+          else
+            create(resource, presenters: presenters) unless exists?(resource)
+          end
+        else
+          puts "Converging #{description_for(resource)} via apply".color(:yellow) if verbose
+          puts 'Rebuild not implemented. Applying instead.'.color(:red).bright if opts[:rebuild]
+          apply(resource, presenters: presenters)
+        end
+      end
+
+      def apply_payload(resource, presenters)
+        payload(resource.applied_manifest_for_export, presenters_for(resource, presenters), :on_apply)
+      end
+
+      # Single merge, both declaration sites: the resource's own members
+      # first (its pipeline completes its self-knowledge), stack members
+      # appended (the boundary's steps admit the finished manifest).
+      # Direct verbs arrive with no stack declarations, so a resource
+      # behaves identically converged directly or through an undeclared
+      # stack.
+      def presenters_for(resource, presenters)
+        own = resource.class.respond_to?(:presenters) ? resource.class.presenters || {} : {}
+        (own.keys + presenters.keys).map(&:to_sym).uniq.each_with_object({}) do |scenario, merged|
+          merged[scenario] = Array(own[scenario]) + Array(presenters[scenario])
+        end
+      end
+
+      def payload(manifest, presenters, scenario)
+        serialize(presentation(manifest, presenters, scenario))
+      end
+
+      # The scenario's pipeline over the rendered manifest. Multi-doc
+      # manifests (arrays) present per document, so match criteria select
+      # documents with the same addressing grammar import lookup uses.
+      # Presented output re-normalizes through deep_stringify_keys — the
+      # same rule *_for_export already applied — so Maps and symbol keys
+      # introduced by transforms never reach the payload.
+      def presentation(manifest, presenters, scenario)
+        pipeline = Matsuri::Transform::Callable.new(Array(presenters[scenario]))
+        return manifest if pipeline.members.empty?
+
+        if manifest.is_a?(Array)
+          manifest.map { |doc| pipeline.call(Map.new(doc)).deep_stringify_keys }
+        else
+          pipeline.call(Map.new(manifest)).deep_stringify_keys
+        end
+      end
+
+      # Multi-doc manifests serialize as concatenated YAML documents,
+      # matching the imported-manifest export rule.
+      def serialize(manifest)
+        manifest.is_a?(Array) ? manifest.map(&:to_yaml).join('') : manifest.to_yaml
+      end
+
+      def description_for(resource)
+        "#{resource.resource_type}/#{resource.name}"
+      end
+
+      def identity_for(resource)
+        { resource_type: resource.resource_type, name: resource.name, namespace: resource.namespace }
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/pod.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    # Pod-scoped cluster reads for the local-dev lifecycle. Resources are
+    # pure generators and carry no verbs or cluster reads; this task takes
+    # identity and selectors as parameters instead.
+    class Pod
+      include Matsuri::Task
+
+      let(:name)      { options.fetch(:name) }
+      let(:namespace) { options.fetch(:namespace) }
+      let(:selector)  { options.fetch(:selector) }
+
+      # The flat label selector addressing a resource's pods: workloads
+      # (Deployment, StatefulSet, ReplicaSet, DaemonSet) declare
+      # match_labels; Service declares selector. Order matters — a workload
+      # also answers selector, with the nested matchLabels shape.
+      def self.pod_selector_for(resource)
+        return resource.match_labels if resource.respond_to?(:match_labels)
+        return resource.selector     if resource.respond_to?(:selector)
+
+        raise ArgumentError, "#{resource.class} does not select pods"
+      end
+
+      # Running, with every container ready. Reads live state by name.
+      def up?
+        cmd = kubectl "get pod/#{name} -o json", echo_level: :debug, no_stdout: true
+        Matsuri.log :fatal, "Unable to get status for pod/#{name}" unless cmd.status.success?
+        pod_json = JSON.parse(cmd.stdout)
+        Matsuri.log :debug, pod_json['status']
+        return false unless pod_json['status']['phase'] == 'Running'
+        return false unless pod_json['status']['containerStatuses']&.any?
+
+        pod_json['status']['containerStatuses'].all? { |c| c['ready'] == true }
+      end
+
+      # Live pods matching the label selector (a flat labels hash).
+      def selected_pods_json
+        sel = selector.to_a.map { |(k, v)| "#{k}=#{v}" }.join(',')
+        cmd = kubectl "get pods -l #{sel} -o json", echo_level: :debug, no_stdout: true
+        JSON.parse(cmd.stdout)
+      end
+
+      def selected_pods
+        selected_pods_json['items']
+      end
+
+      def build!
+      end
+
+      def list!
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/stacks/seed.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    module Stacks
+      # Creation protocol for resources delivered by server-side apply.
+      #
+      # A seeded field (the boot image, an initial replica count) must
+      # exist at birth but never rides the ongoing declaration — the
+      # declared payload omits it, so delivery never contests whoever
+      # rolls it. Server-side apply cannot create such an object safely
+      # on its own: an apply against empty managedFields attributes every
+      # pre-existing field to the synthetic manager before-first-apply,
+      # which never applies again and so never relinquishes — the first
+      # changed-value apply conflicts forever. The protocol below is the
+      # surviving creation path; it and the refuted alternatives are
+      # pinned by tests/bin/probe-ssa.sh.
+      #
+      # Three steps, each loud on failure:
+      # 1. create as <field_manager>-seed (the seed owner) with the
+      #    seeded payload. The create stamps a manager regardless, so
+      #    inject a known one: a converge that dies mid-protocol strands
+      #    an object whose managedFields still read as ours. No
+      #    --save-config — a seeded last-applied is a prune trap for any
+      #    later client-side apply.
+      # 2. Ordinary declared server-side apply as the field manager.
+      #    Equal values co-own; managedFields is never empty, so no
+      #    before-first-apply ghost.
+      # 3. Cede: remove the seed owner's managedFields entry with an
+      #    atomic test+remove JSON patch. Ownership IS the managedFields
+      #    content — deleting the entry is the transfer. The field
+      #    manager ends sole owner of the declared fields; seeds end
+      #    unowned until a controller or deliverer takes them.
+      class Seed
+        include Matsuri::Task
+
+        REMOVAL_ATTEMPTS = 3
+
+        let(:seeded)        { options.fetch(:seeded) }
+        let(:declared)      { options.fetch(:declared) }
+        let(:resource_type) { options.fetch(:resource_type) }
+        let(:name)          { options.fetch(:name) }
+        let(:namespace)     { options.fetch(:namespace) }
+        let(:description)   { options.fetch(:description, "#{resource_type}/#{name}") }
+        let(:field_manager) { options.fetch(:field_manager) }
+        let(:seed_owner)    { "#{field_manager}-seed" }
+
+        def run!
+          puts "Seeding #{description}".color(:yellow).bright if verbose
+          create!
+          apply!
+          cede!
+        end
+
+        def create!
+          puts seeded if debug
+          kubectl! "create --field-manager=#{seed_owner} -f -", input: seeded
+        end
+
+        def apply!
+          KubectlOps::ServerSideApply.new(input:         declared,
+                                          namespace:     namespace,
+                                          description:   description,
+                                          field_manager: field_manager).run!
+        end
+
+        def cede!
+          last = nil
+          REMOVAL_ATTEMPTS.times do
+            idx = seed_owner_index
+            Matsuri.log(:fatal, "#{description}: no managedFields entry for #{seed_owner}") if idx.nil?
+            last = kubectl "patch #{resource_type}/#{name} --type=json -p '#{removal_patch(idx)}'", no_stdout: true
+            return if last.status.success?
+          end
+          Matsuri.log :fatal, "#{description}: could not remove #{seed_owner} after #{REMOVAL_ATTEMPTS} attempts\n#{last.stderr}"
+        end
+
+        # Fresh read per attempt: entry order is not stable, and the test
+        # op in the patch turns a stale index into a rejection, never a
+        # wrong removal.
+        def seed_owner_index
+          cmd = kubectl! "get #{resource_type}/#{name} --show-managed-fields -o json", echo_level: :debug, no_stdout: true
+          JSON.parse(cmd.stdout)['metadata'].fetch('managedFields', []).index { |entry| entry['manager'] == seed_owner }
+        end
+
+        def removal_patch(idx)
+          [{ op: 'test',   path: "/metadata/managedFields/#{idx}/manager", value: seed_owner },
+           { op: 'remove', path: "/metadata/managedFields/#{idx}" }].to_json
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/tasks/stacks.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Tasks
+    # Stack-scope delivery acts: protocols that sequence the kubectl
+    # verbs into one intent. KubectlOps maps one verb to one task; these
+    # compose them.
+    module Stacks
+      autoload :Seed, 'matsuri/tasks/stacks/seed'
+
+      module_function
+
+      # Creation protocol for a server-side-applied resource: seeded
+      # create, declared apply, cede. See Seed.
+      def seed(resource, presenters: {})
+        seed_task(resource, presenters: presenters).run!
+      end
+
+      # The constructed, unrun task — recreate sequences it after
+      # teardown.
+      def seed_task(resource, presenters: {})
+        ops = Matsuri::Tasks::KubectlOps
+        Seed.new(ops.identity_for(resource).merge(
+          seeded:        ops.payload(resource.manifest_for_export, ops.presenters_for(resource, presenters), :on_create),
+          declared:      ops.apply_payload(resource, presenters),
+          description:   ops.description_for(resource),
+          field_manager: resource.field_manager))
+      end
+    end
+  end
+end

data/lib/matsuri/transform/algebra.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Transform
+    # Path-addressed ops over manifest data. A contribution here is a value:
+    # each op takes the carrier and returns it, and pipelines compose by +
+    # over those values — never by super()-chained deltas (let-bound
+    # definitions cannot call super structurally, so the chained style does
+    # not exist here). Ops write through Map#set; the single defensive copy
+    # belongs to the Presenter boundary, not to this algebra.
+    module Algebra
+      extend self
+
+      # Find a deeply nested key, and update it with the return
+      # value of the transform function
+      def update_in(map, path, &f)
+        map.set(path, f.(map.get(path)))
+      end
+
+      def append_to(map, path, entry)
+        existing = map.get(path)
+        raise PathNotFound, "nothing at #{Array(path).join('.')} to append to" if existing.nil?
+
+        map.set(path, existing + [Map.new(entry)])
+      end
+
+      # Given an array of hashes, update values in a path within
+      # each element of the array using the transform function
+      def update_each(arr, path, &f)
+        arr.map { |term| update_in(term, path, &f) }
+      end
+
+      # Given an array of arrays, append a term to each of the arrays within
+      # the array
+      def append_each(a, term)
+        a.map { |l| l + [term] }
+      end
+
+      def index_by_name(a, name)
+        a.index { |entry| entry['name'] == name }
+      end
+
+      def index_by_name!(a, name)
+        index_by_name(a, name) || raise(EntryNotFound, "no entry named #{name.inspect}")
+      end
+
+      def except_entry_by_name(arr, name:)
+        arr.reject { |x| x['name'] == name }
+      end
+    end
+  end
+end

data/lib/matsuri/transform/callable.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Transform
+    # The free monoid over manifest transforms. A Callable holds an ordered
+    # member list and #call reduces the manifest through it. new = identity,
+    # new(label:) { ... } = leaf, new([a, b]) = composite. + concatenates the
+    # operands' member lists into a new instance, so identity and
+    # associativity hold on the nose. Members are never flattened: a
+    # composite passed as a member stays one member, and label rides along
+    # as trace metadata.
+    #
+    # Coercion happens at construction and fails fast: anything #call-able is
+    # taken as-is; a Symbol or String names a registered presenter.
+    class Callable
+      attr_reader :members, :label
+
+      def initialize(members = nil, label: nil, &blk)
+        raise ArgumentError, 'pass members or a block, not both' if blk && members
+
+        @label = label
+        @members =
+          if blk
+            [blk]
+          elsif members.nil?
+            []
+          else
+            Array(members).map { |m| coerce(m) }
+          end
+      end
+
+      def +(other)
+        other_members = other.is_a?(Callable) ? other.members : [coerce(other)]
+        self.class.new(members + other_members)
+      end
+
+      def call(manifest)
+        members.reduce(manifest) { |m, member| member.call(m) }
+      end
+
+      private
+
+      def coerce(member)
+        case member
+        when Symbol, String then Matsuri::Registry.presenter(member)
+        else
+          return member if member.respond_to?(:call)
+
+          raise ArgumentError, "cannot compose #{member.inspect}: not #call-able or a presenter name"
+        end
+      end
+    end
+  end
+end