metatron 0.11.4 → 0.11.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee5149b290884a4e26b48f5763caa5149aaca435edd53245654236a2f5e91f6
-  data.tar.gz: 57ed2e8b0a9f7dc41f72b62ff61dec3018332bc5659a5e0a57df6160ac1e6b22
+  metadata.gz: ab7165f1ce223f66f6ae1678aec0e705cdd2b5e8e0c1753020ca6609d4da086d
+  data.tar.gz: 71b400f058f878a7b894ed4bbd94a6b0b56ad2fa4e92718fc316bc8561d226d1
 SHA512:
-  metadata.gz: ee27cb05a60efb40c4f677b90715bdb2825ae673f9d656e7857c544d2271a8130243d16172acb4992519adcbeb4006eac86a95a252e25b435080be0087e3f2a5
-  data.tar.gz: fdd97067b1e3c0a97e8aef6d8a702bcacfab1fff7a5d8113fe5bcc3e7e9c1903112445c11678d6fc4f07efd3d0bdffa2ba42ee7f151ae0517ef45db7fa5aaecc
+  metadata.gz: 68786131eb7b2c690bd99e76cabbcb3aee0b30911ae91cc896953863294e276be86d46397b57708e5488d07aaf0e74a9aeccd873747abb495b5a2be766a8344d
+  data.tar.gz: 5c35532f391ff7d6b6878870ea57994124f3afb2c4dfd34eb0c6bf7228d8fa9942951dbea9fa7a86a8f3f7fd4e00cc0dfcf4a2dea36e5d7c4aca0c4d9d42d111

data/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.github
+.bundle
+.yardoc
+coverage
+doc
+pkg
+spec
+tmp

data/.github/workflows/ci.yml

@@ -2,6 +2,13 @@ name: CI
 
 on:
   pull_request:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   lint:
@@ -52,3 +59,61 @@ jobs:
       
       - name: Run tests
         run: bundle exec rake spec
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Refresh the advisory database
+        run: bundle exec bundler-audit update
+
+      - name: Audit dependencies for known vulnerabilities
+        run: bundle exec bundler-audit check
+
+  integration:
+    name: integration (k3d ${{ matrix.k3d }}, Metacontroller ${{ matrix.metacontroller }})
+    # Keep cluster-backed work behind the fast, cheap jobs.
+    needs: [lint, yard, test, security]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        k3d: ["v5.9.0"]
+        metacontroller: ["v4.17.6"]
+    env:
+      K3D_VERSION: ${{ matrix.k3d }}
+      METACONTROLLER_VERSION: ${{ matrix.metacontroller }}
+      K3D_CLUSTER_NAME: metatron-it-${{ github.run_id }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Install k3d
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh \
+            | TAG="$K3D_VERSION" bash
+
+      - name: Verify container tooling
+        run: |
+          docker version
+          k3d version
+          kubectl version --client
+
+      - name: Run integration tests
+        run: script/integration

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.4"
+  ".": "0.11.5"
 }

data/.rubocop.yml

@@ -11,6 +11,9 @@ AllCops:
   Exclude:
   - 'db/schema.rb'
   - 'vendor/**/*'
+  # Cluster-backed fixture app and specs; style is not what they are testing.
+  - 'integration/**/*'
+  - 'spec/integration/**/*'
   TargetRubyVersion: 3.3
   NewCops: enable
 

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.11.5](https://github.com/jgnagy/metatron/compare/metatron/v0.11.4...metatron/v0.11.5) (2026-11-11)
+
+
+### Features
+
+* add k3d/Metacontroller integration harness ([953e331](https://github.com/jgnagy/metatron/commit/953e331fcaee3ee0a2a949582aacd821e01bace4))
+* add k3d/Metacontroller integration harness ([16bd24a](https://github.com/jgnagy/metatron/commit/16bd24aa2e3b4202ce2f58e27baa59305286fd08))
+* add name validation to Template base class (closes [#15](https://github.com/jgnagy/metatron/issues/15)) ([#102](https://github.com/jgnagy/metatron/issues/102)) ([caabdef](https://github.com/jgnagy/metatron/commit/caabdefbe87e92800adfb53a830674e631079b54))
+* **security:** controller-level request body cap (M-1) ([c263e14](https://github.com/jgnagy/metatron/commit/c263e14700ecca7263f82f8a2666df887261b316))
+* **security:** opt-in auth + body-limit middleware, controller exception boundary ([481d44c](https://github.com/jgnagy/metatron/commit/481d44cfc1782ffb7a223d4da12fe7d7ec280d05))
+* **security:** webhook auth, request body cap, exception boundary — best of both ([dd60c8a](https://github.com/jgnagy/metatron/commit/dd60c8a1324b398031fa56b0a160e36012764576))
+
+
+### Bug Fixes
+
+* **deps:** raise gemspec floors past CVE-vulnerable rack/json, add bundler-audit CI ([c9e5ab0](https://github.com/jgnagy/metatron/commit/c9e5ab0c88eba4622c528d29273385f4ef86cf02))
+* **deps:** raise gemspec floors past CVE-vulnerable rack/json, add bundler-audit CI ([5a3ed39](https://github.com/jgnagy/metatron/commit/5a3ed39c6b8a94e768c447d7cf2849e5b0df2e53))
+* return 304 for matched ETags ([c38da6f](https://github.com/jgnagy/metatron/commit/c38da6f8b60681fd56096e6c3591d967698dfadd))
+
 ## [0.11.4](https://github.com/jgnagy/metatron/compare/metatron/v0.11.3...metatron/v0.11.4) (2026-07-06)
 
 

data/CONTRIBUTING.md

@@ -16,7 +16,38 @@ Before you begin, ensure that your contribution is associated with a [GitHub iss
 
 Please make sure that your code passes the existing tests and add tests for any new functionality. Please write [RSpec](https://rspec.info/) examples for new features you add or modify.
 
-To execute the tests, run `bundle exec rake spec`.
+To execute the unit tests, run `bundle exec rake spec`.
+
+#### Integration Testing
+
+Metatron also has a cluster-backed suite that runs a fixture controller against a
+real [Metacontroller](https://metacontroller.github.io/metacontroller/)
+installation. It requires Docker, [`k3d`](https://k3d.io/), and `kubectl`.
+
+```sh
+bundle exec rake integration
+```
+
+The task builds the fixture image, creates a throwaway k3d cluster, installs a
+pinned Metacontroller release, runs `spec/integration`, and deletes the cluster.
+Useful options:
+
+```sh
+script/integration --keep                          # leave the cluster running
+script/integration --metacontroller-version v4.17.5
+script/integration --k3d-version v5.9.0
+```
+
+Set `METACONTROLLER_VERSION` to test another Metacontroller release and
+`K3D_VERSION` to assert the expected k3d binary is installed. CI currently pins
+the latest k3d and Metacontroller releases, using a matrix that is ready for
+additional versions. The integration job runs only after the faster lint,
+test, security, and docs jobs succeed.
+If a local Metacontroller clone exists at
+`$HOME/Development/golang/metacontroller` with the requested tag, its manifests
+are used instead of downloading them; otherwise the pinned release manifests
+are fetched from GitHub. The normal `rake spec` task skips these examples
+unless `RUN_INTEGRATION=1` is set.
 
 ### Coding Style
 

data/Gemfile

@@ -6,3 +6,8 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in metatron.gemspec
 gemspec
+
+group :development, :test do
+  # Dependency vulnerability scanner; run by the `security` CI job on every PR.
+  gem "bundler-audit", "~> 0.9"
+end

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    metatron (0.11.4)
+    metatron (0.11.5)
       base64
-      json (~> 2.6)
-      rack (>= 2.2.8, < 4)
+      json (>= 2.21.2, < 3)
+      rack (>= 2.2.25, < 4)
 
 GEM
   remote: https://rubygems.org/
@@ -13,11 +13,14 @@ GEM
     backport (1.2.0)
     base64 (0.2.0)
     benchmark (0.4.0)
+    bundler-audit (0.9.3)
+      bundler (>= 1.2.0)
+      thor (~> 1.0)
     byebug (11.1.3)
     diff-lcs (1.6.0)
     docile (1.4.1)
     jaro_winkler (1.6.0)
-    json (2.10.2)
+    json (2.21.2)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -25,9 +28,9 @@ GEM
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
     logger (1.6.6)
-    nokogiri (1.19.4-arm64-darwin)
+    nokogiri (1.19.7-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.4-x86_64-linux-gnu)
+    nokogiri (1.19.7-x86_64-linux-gnu)
       racc (~> 1.4)
     observer (0.1.2)
     ostruct (0.6.1)
@@ -36,7 +39,7 @@ GEM
       ast (~> 2.4.1)
       racc
     racc (1.8.1)
-    rack (3.1.21)
+    rack (3.2.8)
     rack-test (2.2.0)
       rack (>= 1.3)
     rainbow (3.1.1)
@@ -126,10 +129,12 @@ PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-27
   x86_64-linux
 
 DEPENDENCIES
   bundler (~> 2.3)
+  bundler-audit (~> 0.9)
   byebug (~> 11)
   metatron!
   rack-test (~> 2.0)

data/README.md

@@ -8,6 +8,58 @@ For more information, see the [Metatron Wiki on GitHub](https://github.com/jgnag
 
 For help on how to get started, take a look at the [User Guide](https://github.com/jgnagy/metatron/wiki/User-Guide) in the Wiki!
 
+## Security
+
+Metatron controllers are HTTP endpoints. By default they answer any request that
+looks like a Metacontroller sync request, which means any pod that can reach the
+webhook port can drive your controller — and in controllers that re-render
+existing child `Secrets`, can read credentials.
+
+Metatron ships two opt-in middleware for the two things that matter most:
+
+```ruby
+use Metatron::Middleware::BodyLimit # rejects bodies over 1 MiB with a 413
+use Metatron::Middleware::Auth      # requires the Bearer token shared with Metacontroller
+```
+
+Both are configurable: `METATRON_AUTH_SECRET` (leave it unset and the auth
+middleware stays inert) and `METATRON_MAX_REQUEST_BODY_BYTES` (1 MiB by default,
+which is generous for sync payloads). See the
+[User Guide](https://github.com/jgnagy/metatron/wiki/User-Guide#securing-the-webhook-endpoint)
+for the full setup, including the `webhook.authorization.secretRef` half of the
+handshake on the Metacontroller side.
+
+Errors raised inside `sync`, `customize`, or `finalize` are caught and returned
+as generic JSON `500` problem documents, with the details written to
+`Metatron.logger`. Do not add `Rack::ShowExceptions` to a production stack.
+
+## ETags
+
+If a controller implements `calculate_sync_etag` or
+`calculate_customize_etag`, enable ETag handling on the Metacontroller webhook
+(`etag.enabled: true`). Metatron answers a matching `If-None-Match` request
+with `304 Not Modified`, which Metacontroller uses to replay its cached
+response instead of re-rendering unchanged children.
+
+## Development
+
+Unit tests run without any cluster dependencies:
+
+```sh
+bundle exec rake spec
+```
+
+The cluster-backed integration suite runs Metatron against a real
+Metacontroller installation in a throwaway [k3d](https://k3d.io/) cluster. It
+requires Docker, `k3d`, and `kubectl`:
+
+```sh
+bundle exec rake integration
+```
+
+See the [Contributing Guide](CONTRIBUTING.md#integration-testing) for version
+overrides and debugging options.
+
 ## Contributing
 
 If you're interested in contributing to Metatron, please see the [Contributing Guide](CONTRIBUTING.md) in the repository! Be sure to check out the [Code of Conduct](CODE_OF_CONDUCT.md) as well!

data/Rakefile

@@ -16,4 +16,9 @@ task :demo do
   system("rackup --host 0.0.0.0 -P #{File.expand_path(".")}/tmp/daemon.pid")
 end
 
+desc "run integration specs against a real Metacontroller in a k3d cluster"
+task :integration do
+  sh File.expand_path("script/integration", __dir__)
+end
+
 task default: %i[spec rubocop yard]

data/integration/Dockerfile

@@ -0,0 +1,29 @@
+FROM ruby:3.3-slim
+
+ENV BUNDLE_JOBS=4 \
+    BUNDLE_RETRY=3 \
+    RACK_ENV=production
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Keep the gemspec's `git ls-files` call from warning when the build context
+# has no .git directory.
+RUN git init --quiet
+
+# Copy just enough of the gem for `bundle install` to resolve the path
+# dependency, then the fixture app itself.
+COPY metatron.gemspec ./
+COPY lib ./lib
+COPY integration/controller ./integration/controller
+
+WORKDIR /app/integration/controller
+
+RUN bundle install
+
+EXPOSE 9292
+
+CMD ["bundle", "exec", "puma", "-b", "tcp://0.0.0.0:9292", "config.ru"]

data/integration/controller/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Exercise the gem from this checkout, not a published release.
+gem "metatron", path: "../.."
+
+gem "puma", "~> 6.4"

data/integration/controller/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: ../..
+  specs:
+    metatron (0.11.4)
+      base64
+      json (>= 2.21.2, < 3)
+      rack (>= 2.2.25, < 4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.3.0)
+    json (2.21.2)
+    nio4r (2.7.5)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    rack (3.2.8)
+
+PLATFORMS
+  aarch64-linux
+  arm64-darwin-27
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  metatron!
+  puma (~> 6.4)
+
+BUNDLED WITH
+   2.5.22

data/integration/controller/config.ru

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rack"
+require "metatron"
+require_relative "lib/request_logger"
+require_relative "lib/widget_controller"
+
+# The secured stack mirrors a realistic Metatron deployment: body limits and
+# bearer-token auth in front of the CompositeController. `/ping` stays outside
+# the auth stack so Kubernetes probes can reach it without a credential.
+secured = Rack::Builder.new do
+  use IntegrationController::RequestLogger
+  use Metatron::Middleware::BodyLimit
+  use Metatron::Middleware::Auth
+  run IntegrationController::WidgetController
+end
+
+run Rack::URLMap.new(
+  "/ping" => Metatron::Controllers::Ping,
+  "/widgets" => secured
+)

data/integration/controller/lib/request_logger.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module IntegrationController
+  # Logs the final status of each request so integration specs can prove that
+  # paths like ETag short-circuiting (304) and auth rejection (401) actually
+  # happened in the cluster.
+  class RequestLogger
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      Metatron.logger.info("#{env["REQUEST_METHOD"]} #{env["PATH_INFO"]} -> #{status}")
+      [status, headers, body]
+    end
+  end
+end

data/integration/controller/lib/widget_controller.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module IntegrationController
+  # A deliberately small CompositeController used to exercise Metatron against
+  # a real Metacontroller installation. It produces one of each child type the
+  # gem templates most often: a ConfigMap, a Secret, a Deployment, and a
+  # Service.
+  class WidgetController < Metatron::CompositeController
+    DEFAULT_IMAGE = "registry.k8s.io/pause:3.9"
+
+    def sync # rubocop:disable Metrics/AbcSize
+      parent = params.fetch("parent")
+      metadata = parent.fetch("metadata")
+      spec = parent.fetch("spec", {})
+      name = metadata.fetch("name")
+      namespace = metadata["namespace"]
+      replicas = Integer(spec.fetch("replicas", 1))
+      image = spec["image"] || DEFAULT_IMAGE
+      config_value = spec["configValue"] || "default"
+      parent_labels = { "metatron.therubyist.org/parent" => name }
+
+      config_map = Metatron::Templates::ConfigMap.new(
+        "#{name}-config",
+        {
+          "widget.properties" => "replicas=#{replicas}\nimage=#{image}\nconfigValue=#{config_value}\n"
+        }
+      )
+      config_map.namespace = namespace
+      config_map.additional_labels = parent_labels
+
+      secret = Metatron::Templates::Secret.new(
+        "#{name}-secret",
+        { "token" => Digest::SHA256.hexdigest("#{name}:#{metadata["uid"]}") }
+      )
+      secret.namespace = namespace
+      secret.additional_labels = parent_labels
+
+      deployment = Metatron::Templates::Deployment.new(name, replicas: replicas)
+      deployment.namespace = namespace
+      deployment.additional_labels = parent_labels
+      deployment.additional_pod_labels = { "app.kubernetes.io/component" => "widget" }
+      deployment.containers << build_container(image, config_value)
+
+      service = Metatron::Templates::Service.new(name, 80)
+      service.namespace = namespace
+      service.additional_labels = parent_labels
+      service.additional_selector_labels = deployment.additional_pod_labels
+      service.ports.first[:targetPort] = 8080
+
+      {
+        status: { replicas: replicas, configValue: config_value },
+        children: [config_map, secret, deployment, service]
+      }
+    end
+
+    def finalize
+      name = params.dig("parent", "metadata", "name")
+      Metatron.logger.info("finalize #{name}")
+      { status: {}, finalized: true }
+    end
+
+    # A stable ETag lets Metacontroller short-circuit unchanged resyncs with a
+    # 304 instead of re-applying identical children. The integration suite
+    # asserts that this path is taken at least once.
+    def calculate_sync_etag
+      children = sync.fetch(:children).map do |child|
+        child.respond_to?(:render) ? child.render : child
+      end
+      Digest::SHA256.hexdigest(JSON.generate(children))
+    end
+
+    private
+
+    def build_container(image, config_value)
+      container = Metatron::Templates::Container.new("widget", image)
+      container.ports = [{ name: "http", containerPort: 8080 }]
+      container.env = { "WIDGET_CONFIG" => config_value }
+      container
+    end
+  end
+end

data/integration/manifests/composite-controller.yaml

@@ -0,0 +1,62 @@
+apiVersion: metacontroller.k8s.io/v1alpha1
+kind: CompositeController
+metadata:
+  name: widget-controller
+spec:
+  generateSelector: true
+  # Resync often enough that the integration suite can observe the ETag
+  # short-circuit (304) without waiting for a long default interval.
+  resyncPeriodSeconds: 5
+  parentResource:
+    apiVersion: metatron.therubyist.org/v1
+    resource: widgets
+  childResources:
+    - apiVersion: apps/v1
+      resource: deployments
+      updateStrategy:
+        method: InPlace
+    - apiVersion: v1
+      resource: services
+      updateStrategy:
+        method: InPlace
+    - apiVersion: v1
+      resource: configmaps
+      updateStrategy:
+        method: InPlace
+    - apiVersion: v1
+      resource: secrets
+      updateStrategy:
+        method: InPlace
+  hooks:
+    sync:
+      webhook:
+        service:
+          name: widget-controller
+          namespace: __NAMESPACE__
+          port: 9292
+          protocol: http
+        path: /widgets/sync
+        etag:
+          enabled: true
+          cacheTimeoutSeconds: 300
+          cacheCleanupSeconds: 60
+        authorization:
+          type: Bearer
+          secretRef:
+            name: widget-controller-auth
+            namespace: __NAMESPACE__
+            key: token
+    finalize:
+      webhook:
+        service:
+          name: widget-controller
+          namespace: __NAMESPACE__
+          port: 9292
+          protocol: http
+        path: /widgets/finalize
+        authorization:
+          type: Bearer
+          secretRef:
+            name: widget-controller-auth
+            namespace: __NAMESPACE__
+            key: token

data/integration/manifests/controller.yaml

@@ -0,0 +1,70 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: widget-controller-auth
+  namespace: __NAMESPACE__
+  labels:
+    app: widget-controller
+type: Opaque
+stringData:
+  token: __AUTH_TOKEN__
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: widget-controller
+  namespace: __NAMESPACE__
+  labels:
+    app: widget-controller
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: widget-controller
+  template:
+    metadata:
+      labels:
+        app: widget-controller
+    spec:
+      containers:
+        - name: widget-controller
+          image: __IMAGE__
+          imagePullPolicy: IfNotPresent
+          ports:
+            - name: http
+              containerPort: 9292
+          env:
+            - name: METATRON_AUTH_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: widget-controller-auth
+                  key: token
+            - name: LOG_LEVEL
+              value: info
+          readinessProbe:
+            httpGet:
+              path: /ping
+              port: http
+            initialDelaySeconds: 2
+            periodSeconds: 2
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: widget-controller
+  namespace: __NAMESPACE__
+  labels:
+    app: widget-controller
+spec:
+  selector:
+    app: widget-controller
+  ports:
+    - name: http
+      port: 9292
+      targetPort: http