matsuri 0.1.0 → 0.3.0

data/lib/matsuri/transform/combinators.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Transform
+    # Combinators are Element -> Element: they take a transform step and
+    # return a transform step, so selectivity lives in the wrapper and the
+    # wrapped element stays total. They are machinery, not presenters —
+    # never registry-named; names cross the declaration boundary, machinery
+    # does not.
+    module Combinators
+      # Applies its element only to manifests meeting the criteria —
+      # identity otherwise. Criteria are the conjunction of the declared
+      # {kind:, name:, namespace:} constraints, the same addressing grammar
+      # import lookup uses; an undeclared key constrains nothing, an unknown
+      # key is an error.
+      class Match
+        CRITERIA_KEYS = %w[kind name namespace].freeze
+
+        attr_reader :criteria, :element
+
+        def initialize(criteria, element)
+          @criteria = Map.new(criteria)
+          unknown = @criteria.keys - CRITERIA_KEYS
+          raise ArgumentError, "unknown match criteria #{unknown.inspect}; use #{CRITERIA_KEYS.join(', ')}" if unknown.any?
+
+          @element = Callable.new([element])
+        end
+
+        def call(manifest)
+          return manifest unless matches?(manifest)
+
+          element.call(manifest)
+        end
+
+        def matches?(manifest)
+          m = Map === manifest ? manifest : Map.new(manifest)
+          (criteria[:kind].nil?      || m.get(:kind) == criteria[:kind]) &&
+            (criteria[:name].nil?      || m.get(:metadata, :name) == criteria[:name]) &&
+            (criteria[:namespace].nil? || m.get(:metadata, :namespace) == criteria[:namespace])
+        end
+      end
+
+      # The declaration-surface vocabulary. Sugars grow on demand.
+      module Helpers
+        def match(criteria, element)
+          Match.new(criteria, element)
+        end
+
+        def match_kind(kind, element)
+          Match.new({ kind: kind }, element)
+        end
+
+        def match_deployments(element)
+          match_kind('Deployment', element)
+        end
+      end
+
+      extend Helpers
+    end
+  end
+end

data/lib/matsuri/transform/env.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Transform
+    # The array <-> map isomorphism for container env entries. Manifests
+    # carry env as an ordered array of {name:, value:|valueFrom:} entries;
+    # the map side exists so entries can be updated by key. The round trip
+    # preserves order, appends new keys at the end, and compacts duplicate
+    # names (last write wins), so it is not a 1-to-1 mapping.
+    module Env
+      extend self
+
+      def update_kv(kv, key, value)
+        updated_kv = env_to_map(kv).update(key, value)
+        expand_env(updated_kv)
+      end
+
+      def env_to_map(kv)
+        kv.inject(Map.new) do |acc, entry|
+          case
+          when entry.key?('value')
+            acc[entry['name']] = entry['value']
+          when entry.key?('valueFrom')
+            acc[entry['name']] = entry['valueFrom']
+          else
+            nil
+          end
+          acc
+        end
+      end
+
+      def expand_env(hash)
+        hash.map do |k, v|
+          if v.is_a?(Hash)
+            { name: k, valueFrom: v }
+          else
+            { name: k, value: v.to_s }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/transform/kubernetes.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Matsuri
+  module Transform
+    # The Kubernetes dialect: Algebra + Env ops addressed to the manifest
+    # shapes Kubernetes actually uses — container lists, env entries,
+    # labels, volumes, node affinity. Well-known paths are constants so a
+    # misspelled path cannot exist at a call site.
+    module Kubernetes
+      include Algebra
+      include Env
+      extend self
+
+      NODE_SELECTOR_TERMS_PATH = %i[
+        affinity
+        nodeAffinity
+        requiredDuringSchedulingIgnoredDuringExecution
+        nodeSelectorTerms
+      ].freeze
+
+      # The pod spec within a pod-template workload or a bare pod manifest.
+      def pod_spec_path(manifest)
+        manifest.get(:spec, :template, :spec) ? %i[spec template spec] : %i[spec]
+      end
+
+      # Set the env variable of a container, defaults to container 0
+      def set_env(spec, key, value, container: 0)
+        path = [:containers, container, :env]
+        spec.set(path, update_kv(spec.get(path), key, value))
+      end
+
+      # Set the env variables for all containers
+      def set_all_env(spec, key, value)
+        size = spec.get(:containers).length
+        if size > 0 then
+          (0..size - 1).inject(spec) do |spec, i|
+            set_env(spec, key, value, container: i)
+          end
+        else
+          # If there are no containers, there are other things wrong with the manifest.
+          # However, return the same spec to satisify the zero-point property of the transform
+          spec
+        end
+      end
+
+      def set_resources(spec, resources_spec, container_name:)
+        container_num = index_by_name!(spec.get(:containers), container_name)
+        spec.set([:containers, container_num, :resources], resources_spec)
+      end
+
+      # Curried form of set_resources: names the container and the resource
+      # spec up front, returns the spec -> spec step.
+      def with_resources(name, resource_spec)
+        ->(spec) { set_resources(spec, resource_spec, container_name: name) }
+      end
+
+      # Set a label
+      def set_label(metadata, key, value)
+        metadata.set(:labels, key, value)
+      end
+
+      # Append a volume mount to a container, defaults to container 0
+      def append_volume_mount(spec, volume_mount_spec, container: 0)
+        append_to(spec, [:containers, container, :volumeMounts], volume_mount_spec)
+      end
+
+      # Append a volume
+      def append_volume(spec, volume_spec)
+        append_to(spec, [:volumes], volume_spec)
+      end
+
+      def without_container(spec, name:)
+        update_in(spec, [:containers]) { |x| except_entry_by_name(x, name: name) }
+      end
+
+      # Helper for updating node selector terms
+      def update_in_node_selector_terms(spec, &f)
+        update_in(spec, NODE_SELECTOR_TERMS_PATH, &f)
+      end
+
+      # Helper for updating node affinity terms
+      def append_node_affinity(spec, match_expressions)
+        update_in(spec, NODE_SELECTOR_TERMS_PATH) do |terms|
+          terms + [match_expressions]
+        end
+      end
+    end
+  end
+end

data/lib/matsuri/transform.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Matsuri
+  # Pure manifest transformation strata. Nothing under this namespace shells
+  # out or touches a cluster; everything operates on plain data (Map / Hash /
+  # Array) and composes as values.
+  module Transform
+    autoload :Algebra,     'matsuri/transform/algebra'
+    autoload :Callable,    'matsuri/transform/callable'
+    autoload :Env,         'matsuri/transform/env'
+    autoload :Kubernetes,  'matsuri/transform/kubernetes'
+    autoload :Combinators, 'matsuri/transform/combinators'
+
+    # Raised by strict by-name lookups when no entry matches.
+    class EntryNotFound < StandardError; end
+
+    # Raised by path-addressed ops when nothing exists at the path.
+    class PathNotFound < StandardError; end
+  end
+end

data/lib/matsuri/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Matsuri
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/matsuri.rb

@@ -1,5 +1,161 @@
-require "matsuri/version"
+# frozen_string_literal: true
+
+require 'matsuri/core_ext'
 
 module Matsuri
-  # Your code goes here...
+  # Raised when a declared hole — a let() with no sensible default — is read
+  # before a definition fills it. Inherits NoMethodError: the definition has
+  # no working version of that let. The raise lands in the code that expected
+  # the value, so the implementer can inspect that context and see what the
+  # definition needs.
+  class UndefinedLet < NoMethodError; end
+
+  autoload :Initializer, 'matsuri/initializer'
+  autoload :Config,      'matsuri/config'
+  autoload :Platform,    'matsuri/platform'
+  autoload :ShellOut,    'matsuri/shell_out'
+  autoload :Registry,    'matsuri/registry'
+
+  autoload :Task,        'matsuri/task'
+  autoload :Cmd,         'matsuri/cmd'
+  autoload :Stack,       'matsuri/stack'
+  autoload :Acceptor,    'matsuri/acceptor'
+  autoload :Presenter,   'matsuri/presenter'
+  autoload :Transform,   'matsuri/transform'
+
+  module Acceptors
+    autoload :ImageTag, 'matsuri/acceptors/image_tag'
+  end
+
+  module Presenters
+    autoload :SeedImage,     'matsuri/presenters/seed_image'
+    autoload :SeedReplicas,  'matsuri/presenters/seed_replicas'
+    autoload :SeedResources, 'matsuri/presenters/seed_resources'
+    autoload :PruneEmpty,    'matsuri/presenters/prune_empty'
+    autoload :Helpers,       'matsuri/presenters/helpers'
+  end
+
+  module Kubernetes
+    autoload :Base,                    'matsuri/kubernetes/base'
+
+    # Core
+    autoload :Pod,                     'matsuri/kubernetes/pod'
+    autoload :Service,                 'matsuri/kubernetes/service'
+    autoload :Endpoints,               'matsuri/kubernetes/endpoints'
+    autoload :Ingress,                 'matsuri/kubernetes/ingress'
+    autoload :Secret,                  'matsuri/kubernetes/secret'
+    autoload :ConfigMap,               'matsuri/kubernetes/config_map'
+
+    # Apps
+    autoload :ReplicaSet,              'matsuri/kubernetes/replica_set'
+    autoload :StatefulSet,             'matsuri/kubernetes/stateful_set'
+    autoload :DaemonSet,               'matsuri/kubernetes/daemon_set'
+    autoload :Deployment,              'matsuri/kubernetes/deployment'
+    autoload :CronJob,                 'matsuri/kubernetes/cron_job'
+
+    autoload :HorizontalPodAutoscaler, 'matsuri/kubernetes/horizontal_pod_autoscaler'
+
+    # Persistent Storage
+    autoload :PersistentVolume,        'matsuri/kubernetes/persistent_volume'
+    autoload :PersistentVolumeClaim,   'matsuri/kubernetes/persistent_volume_claim'
+    autoload :StorageClass,            'matsuri/kubernetes/storage_class'
+
+    # Other
+    autoload :ImportedManifest,        'matsuri/kubernetes/imported_manifest'
+  end
+
+  module Cmds
+    autoload :Cli,      'matsuri/cmds/cli'
+    autoload :Kubectl,  'matsuri/cmds/kubectl'
+    autoload :Show,     'matsuri/cmds/show'
+    autoload :Diff,     'matsuri/cmds/diff'
+    autoload :Status,   'matsuri/cmds/status'
+    autoload :Create,   'matsuri/cmds/create'
+    autoload :Delete,   'matsuri/cmds/delete'
+    autoload :Apply,    'matsuri/cmds/apply'
+    autoload :Recreate, 'matsuri/cmds/recreate'
+    autoload :Scale,    'matsuri/cmds/scale'
+
+    autoload :Generate, 'matsuri/cmds/generate'
+  end
+
+  module Tasks
+    autoload :Kubectl,    'matsuri/tasks/kubectl'
+    autoload :KubectlOps, 'matsuri/tasks/kubectl_ops'
+    autoload :Stacks,     'matsuri/tasks/stacks'
+    autoload :HashDiff,   'matsuri/tasks/hash_diff'
+    autoload :Docker,     'matsuri/tasks/docker'
+    autoload :Pod,        'matsuri/tasks/pod'
+    autoload :Cluster,    'matsuri/tasks/cluster'
+  end
+
+  module Concerns
+    autoload :ImportManifest,     'matsuri/concerns/import_manifest'
+    autoload :ExportManifest,     'matsuri/concerns/export_manifest'
+    autoload :Diffable,           'matsuri/concerns/diffable'
+
+    autoload :Awaiting,           'matsuri/concerns/awaiting'
+    autoload :RegistryHelpers,    'matsuri/concerns/registry_helpers'
+    autoload :PodTemplate,        'matsuri/concerns/pod_template'
+
+    module Pods
+      autoload :SpreadPods,       'matsuri/concerns/pods/spread_pods'
+      autoload :SpreadTopology,   'matsuri/concerns/pods/spread_topology'
+    end
+  end
+
+  module DSL
+    module Cluster
+      autoload :Scope,                 'matsuri/dsl/cluster/scope'
+
+      autoload :Role,                  'matsuri/dsl/cluster/role'
+      autoload :ClusterRole,           'matsuri/dsl/cluster/cluster_role'
+      autoload :AggregatedClusterRole, 'matsuri/dsl/cluster/aggregated_cluster_role'
+      autoload :Binding,               'matsuri/dsl/cluster/binding'
+
+      autoload :ServiceAccount,        'matsuri/dsl/cluster/service_account'
+    end
+
+    module Concerns
+      autoload :Metadata,        'matsuri/dsl/concerns/metadata'
+      autoload :RbacRules,       'matsuri/dsl/concerns/rbac_rules'
+      autoload :DefaultBinding,  'matsuri/dsl/concerns/default_binding'
+      autoload :ManifestSet,     'matsuri/dsl/concerns/manifest_set'
+    end
+  end
+
+  def self.define(type, name, inherits: nil, &blk)
+    Matsuri::Registry.define(type, name, inherits: inherits, &blk)
+  end
+
+  def self.environment
+    Matsuri::Config.environment
+  end
+
+  def self.dev?
+    Matsuri::Config.environment == 'dev'
+  end
+
+  def self.staging?
+    Matsuri::Config.environment == 'staging'
+  end
+
+  def self.production?
+    Matsuri::Config.environment == 'production'
+  end
+
+  def self.log(level, message = nil, &blk)
+    case level
+    when :fatal then
+      log_output! message, &blk
+      exit(1)
+    when :error, :warn then log_output! message, &blk
+    when :info         then log_output! message, &blk if Matsuri::Config.verbose
+    when :debug        then log_output! message, &blk if Matsuri::Config.debug
+    end
+  end
+
+  def self.log_output!(message)
+    puts(message || yield)
+  end
 end

data/matsuri.gemspec

@@ -1,4 +1,5 @@
-# coding: utf-8
+# frozen_string_literal: true
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'matsuri/version'
@@ -7,18 +8,30 @@ Gem::Specification.new do |spec|
   spec.name          = "matsuri"
   spec.version       = Matsuri::VERSION
   spec.authors       = ["Ho-Sheng Hsiao"]
-  spec.email         = ["hosh@shopapps.co"]
+  spec.email         = ["ho-sheng.hsiao@solace.health"]
 
   spec.summary       = %q{Build a dev environment using Docker and Kubernetes}
   spec.description   = %q{Framework and toolkit to build a dev environment using Docker and Kubernetes}
-  spec.homepage      = "https://github.com/shopappsio/matsuri"
+  spec.homepage      = "https://github.com/matsuri-rb/matsuri"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.10"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.add_dependency 'base64'
+  spec.add_dependency 'thor'
+  spec.add_dependency 'mixlib-shellout'
+  spec.add_dependency 'mixlib-config'
+  spec.add_dependency 'rlet', '~> 0.7.0'
+  spec.add_dependency 'map'
+  spec.add_dependency 'hashdiff'
+  spec.add_dependency 'rainbow'
+  spec.add_dependency 'unit', '~> 0.5.0'
+
+  spec.add_development_dependency "bundler", ">= 2.4"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec"
 end

data/tests/bin/minikube-start.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+set -euo pipefail
+
+# Starts the matsuri test cluster under its own profile. --keep-context
+# leaves the user's kubectl context alone; scripts address the cluster
+# with --context matsuri. Pass minikube flags through, e.g.
+# bin/minikube-start.sh --kubernetes-version=v1.34.0.
+# kubectl and minikube dial the VM over the local network: on macOS, run
+# from a Local Network-granted context (not tmux).
+PROFILE="${PROFILE:-matsuri}"
+
+# vfkit is the darwin driver; the flake only ships it there.
+case "$(uname -s)" in
+  Darwin) DRIVER="${DRIVER:-vfkit}" ;;
+  *) DRIVER="${DRIVER:-podman}" ;;
+esac
+
+minikube start \
+  -p "${PROFILE}" \
+  --driver="${DRIVER}" \
+  --keep-context \
+  "$@"
+
+# The example repo's namespaces precede anything matsuri converges;
+# they are raw manifests, applied outside matsuri.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+kubectl --context "${PROFILE}" apply -f "${SCRIPT_DIR}/../example/platform/namespaces"

data/tests/bin/probe-save-config.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+set -euo pipefail
+
+# Probes the mechanics the seed model rests on: a create WITHOUT
+# --save-config (the kubectl default) keeps seeded fields out of
+# last-applied, so ongoing applies of a manifest that omits them never
+# prune them, and another controller (an HPA) takes ownership
+# uncontested.
+#
+# Sequence:
+#   1. create from the seeded manifest (replicas: 3), no --save-config
+#   2. apply the declared manifest (no replicas) -> replicas must stay 3
+#   3. scale to 5 (stands in for the HPA taking ownership)
+#   4. apply the declared manifest again -> replicas must stay 5
+#
+# Start the cluster with bin/minikube-start.sh first. kubectl dials the
+# VM: on macOS run from a Local Network-granted context (not tmux).
+
+TESTS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONTEXT="${CONTEXT:-matsuri}"
+K8S="${TESTS_DIR}/k8s/save-config"
+KUBECTL=(kubectl --context "${CONTEXT}" --namespace matsuri-probes)
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+replicas() {
+  "${KUBECTL[@]}" get deployment save-config-probe -o jsonpath='{.spec.replicas}'
+}
+
+kubectl --context "${CONTEXT}" apply -f "${K8S}/namespace.yaml"
+"${KUBECTL[@]}" delete deployment save-config-probe --ignore-not-found --wait
+
+"${KUBECTL[@]}" create -f "${K8S}/deployment-seeded.yaml"
+[ "$(replicas)" = "3" ] || fail "create did not land the seed (replicas=$(replicas))"
+
+"${KUBECTL[@]}" apply -f "${K8S}/deployment-declared.yaml"
+[ "$(replicas)" = "3" ] || fail "first apply pruned the seeded replicas (replicas=$(replicas))"
+
+"${KUBECTL[@]}" scale deployment save-config-probe --replicas=5
+"${KUBECTL[@]}" apply -f "${K8S}/deployment-declared.yaml"
+[ "$(replicas)" = "5" ] || fail "apply clobbered controller-owned replicas (replicas=$(replicas))"
+
+echo "last-applied for the record (replicas must be absent):"
+"${KUBECTL[@]}" apply view-last-applied deployment save-config-probe
+
+echo "PASS: seeded create + ongoing applies leave replicas controller-owned"