metatron 0.11.4 → 0.11.5

data/integration/manifests/crd.yaml

@@ -0,0 +1,46 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: widgets.metatron.therubyist.org
+spec:
+  group: metatron.therubyist.org
+  scope: Namespaced
+  names:
+    plural: widgets
+    singular: widget
+    kind: Widget
+    shortNames:
+      - wdg
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      subresources:
+        status: {}
+      additionalPrinterColumns:
+        - name: Replicas
+          type: integer
+          jsonPath: .spec.replicas
+        - name: Config
+          type: string
+          jsonPath: .spec.configValue
+        - name: Age
+          type: date
+          jsonPath: .metadata.creationTimestamp
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                replicas:
+                  type: integer
+                  minimum: 1
+                image:
+                  type: string
+                configValue:
+                  type: string
+            status:
+              type: object
+              x-kubernetes-preserve-unknown-fields: true

data/integration/manifests/namespace.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: __NAMESPACE__
+  labels:
+    app.kubernetes.io/part-of: metatron-integration

data/integration/manifests/sample-widget.yaml

@@ -0,0 +1,9 @@
+apiVersion: metatron.therubyist.org/v1
+kind: Widget
+metadata:
+  name: sample
+  namespace: __NAMESPACE__
+spec:
+  replicas: 2
+  image: registry.k8s.io/pause:3.9
+  configValue: sample

data/lib/metatron/composite_controller.rb

@@ -32,7 +32,10 @@ module Metatron
 
       headers = {}
 
-      return Rack::Response[412, headers, []].to_a if etag_matches?(headers)
+      # Metacontroller only accepts 304 Not Modified when it sends
+      # If-None-Match; a 412 is treated as a hook failure. See
+      # https://github.com/metacontroller/metacontroller/blob/master/pkg/hooks/webhook_etag.go
+      return Rack::Response[304, headers, []].to_a if etag_matches?(headers)
 
       Rack::Response[200, headers, processed_data].to_a
     end

data/lib/metatron/controller.rb

@@ -20,21 +20,63 @@ module Metatron
 
     def call
       begin
-        if request&.content_type&.include?("json")
-          body = request.body.read
-          request.body.rewind if request.body.respond_to?(:rewind)
-
-          self.params = JSON.parse(body) unless body.empty?
-        end
+        parse_params
+      rescue Metatron::PayloadTooLarge
+        return Metatron::Problem.response(
+          status: 413,
+          title: "Payload Too Large",
+          detail: "Request body exceeds the maximum allowed size"
+        )
       rescue JSON::ParserError => e
         return [400, {}, [{ error: "Request must be JSON: #{e.message}" }.to_json]]
       end
 
-      _call
+      begin
+        _call
+      rescue StandardError, NotImplementedError => e
+        log_exception(e)
+        Problem.response(
+          status: 500,
+          title: "Internal Server Error",
+          detail: "The controller failed to handle the request."
+        )
+      end
     end
 
     private
 
     attr_reader :request
+
+    def parse_params
+      return unless request&.content_type&.include?("json")
+
+      body = read_bounded_body
+
+      self.params = JSON.parse(body) unless body.empty?
+    end
+
+    # Read the request body, enforcing the configured size cap.
+    # Raises PayloadTooLarge when the body exceeds the limit; the
+    # controller's rescue converts it to a 413 problem document.
+    def read_bounded_body
+      limit = Metatron.max_body_bytes
+      raise Metatron::PayloadTooLarge if request.content_length.to_i > limit
+
+      # Read at most one byte more than the limit so an oversized
+      # chunked body (no Content-Length) is still caught.
+      body = request.body.read(limit + 1) || ""
+      request.body.rewind if request.body.respond_to?(:rewind)
+      raise Metatron::PayloadTooLarge if body.bytesize > limit
+
+      body
+    end
+
+    # Record the failure for the operator without leaking it to the caller.
+    def log_exception(error)
+      Metatron.logger&.error(
+        "Metatron controller raised #{error.class}: #{error.message}\n" \
+        "#{Array(error.backtrace).join("\n")}"
+      )
+    end
   end
 end

data/lib/metatron/middleware/auth.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module Metatron
+  # Rack middleware shipped with Metatron.
+  module Middleware
+    # Requires a shared secret to be presented as a Bearer token before the
+    # request reaches the controller.
+    #
+    # The middleware is opt-in: it enforces nothing until a secret is
+    # configured, either by passing `secret:` to the constructor or by setting
+    # the `METATRON_AUTH_SECRET` environment variable. With no secret
+    # configured, requests are passed straight through, so existing
+    # applications behave exactly as they did before.
+    #
+    # Metacontroller can send the matching credential via the hook spec's
+    # `webhook.authorization.secretRef`, which points at a Kubernetes Secret
+    # whose value is shared with this middleware.
+    #
+    # @example
+    #   use Metatron::Middleware::Auth, secret: ENV["METATRON_AUTH_SECRET"]
+    #
+    # @see https://metacontroller.github.io/metacontroller/api/compositecontroller.html
+    class Auth
+      # Environment variable consulted when no secret is passed explicitly.
+      SECRET_ENV_VAR = "METATRON_AUTH_SECRET"
+
+      # The only authentication scheme understood by this middleware.
+      SCHEME = "Bearer"
+
+      # Rack environment key holding the `Authorization` header.
+      AUTHORIZATION_HEADER = "HTTP_AUTHORIZATION"
+
+      # Challenge sent with unauthorized responses.
+      CHALLENGE = "Bearer realm=\"metatron\""
+
+      attr_reader :app
+
+      # @param app [#call] the Rack application to protect
+      # @param secret [String, nil] the shared secret; falls back to the environment
+      # @param env_var [String] the environment variable to read the secret from
+      def initialize(app, secret: nil, env_var: SECRET_ENV_VAR)
+        @app = app
+        @secret = secret
+        @env_var = env_var
+      end
+
+      def call(env)
+        expected = configured_secret
+        return app.call(env) if expected.nil?
+
+        presented = bearer_token(env)
+        return unauthorized if presented.nil?
+        return unauthorized unless secure_compare?(presented, expected)
+
+        app.call(env)
+      end
+
+      private
+
+      # The secret to check against, or nil when authentication is disabled.
+      def configured_secret
+        secret = @secret || ENV.fetch(@env_var, nil)
+        return nil if secret.nil?
+
+        secret = secret.to_s
+        secret.empty? ? nil : secret
+      end
+
+      # Extract the token from an `Authorization: Bearer <token>` header.
+      #
+      # @return [String, nil] the token, or nil when no usable token is present
+      def bearer_token(env)
+        header = env[AUTHORIZATION_HEADER]
+        return nil if header.nil?
+
+        scheme, token = header.to_s.split(" ", 2)
+        return nil if scheme.nil? || token.nil?
+        return nil unless scheme.casecmp?(SCHEME)
+
+        token = token.strip
+        token.empty? ? nil : token
+      end
+
+      # Compare the presented token with the secret in constant time.
+      def secure_compare?(presented, expected)
+        return false unless presented.bytesize == expected.bytesize
+
+        Rack::Utils.secure_compare(presented, expected)
+      end
+
+      def unauthorized
+        Problem.response(
+          status: 401,
+          title: "Unauthorized",
+          detail: "A valid Bearer token is required to access this endpoint.",
+          headers: { "www-authenticate" => CHALLENGE }
+        )
+      end
+    end
+  end
+end

data/lib/metatron/middleware/body_limit.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Metatron
+  # Rack middleware shipped with Metatron.
+  module Middleware
+    # Rejects request bodies larger than a configurable cap.
+    #
+    # The cap is enforced twice: up front from the `Content-Length` header
+    # (cheap, and catches the common case without reading anything), and again
+    # while reading the body, so that a missing or understated
+    # `Content-Length` cannot be used to exhaust memory. The body is buffered
+    # up to the cap and handed to the application as a rewound stream.
+    #
+    # @example
+    #   use Metatron::Middleware::BodyLimit, max_bytes: 1_048_576
+    class BodyLimit
+      # Default cap on request body size: 1 MiB, which is generous for
+      # Metacontroller sync payloads.
+      DEFAULT_MAX_BYTES = 1024 * 1024
+
+      # Environment variable consulted when no limit is passed explicitly.
+      MAX_BYTES_ENV_VAR = "METATRON_MAX_REQUEST_BODY_BYTES"
+
+      attr_reader :app
+
+      # @param app [#call] the Rack application to protect
+      # @param max_bytes [Integer, nil] the cap; falls back to the environment
+      # @param env_var [String] the environment variable to read the cap from
+      def initialize(app, max_bytes: nil, env_var: MAX_BYTES_ENV_VAR)
+        @app = app
+        @max_bytes = max_bytes
+        @env_var = env_var
+      end
+
+      def call(env)
+        limit = max_bytes
+
+        length = env["CONTENT_LENGTH"]
+        return payload_too_large(limit) if length && length.to_i > limit
+
+        input = env["rack.input"]
+        return app.call(env) if input.nil?
+
+        body = read_capped(input, limit)
+        return payload_too_large(limit) if body.nil?
+
+        env["rack.input"] = StringIO.new(body).tap(&:binmode)
+        app.call(env)
+      end
+
+      private
+
+      # The maximum number of bytes accepted in a request body.
+      def max_bytes
+        return @max_bytes unless @max_bytes.nil?
+
+        configured = ENV.fetch(@env_var, nil)
+        return DEFAULT_MAX_BYTES if configured.nil? || configured.empty?
+
+        configured.to_i
+      end
+
+      # Read at most `limit` bytes from the input stream.
+      #
+      # @return [String, nil] the body, or nil when it is larger than the limit
+      def read_capped(input, limit)
+        chunk = input.read(limit + 1)
+        chunk = "" if chunk.nil?
+        return nil if chunk.bytesize > limit
+
+        chunk
+      end
+
+      def payload_too_large(limit)
+        Problem.response(
+          status: 413,
+          title: "Payload Too Large",
+          detail: "Request bodies may not exceed #{limit} bytes."
+        )
+      end
+    end
+  end
+end

data/lib/metatron/problem.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json" unless defined? JSON # allow for JSON to be loaded elsewhere
+
+module Metatron
+  # Helpers for RFC 9457 "Problem Details for HTTP APIs" responses.
+  #
+  # Problem documents give clients a machine-readable error body without
+  # leaking internals (backtraces, environment, gem versions). They are used
+  # by the shipped middleware and by the controller's exception boundary.
+  module Problem
+    # Media type used for problem documents.
+    CONTENT_TYPE = "application/problem+json"
+
+    # Stable problem type identifiers. These are identifiers only; they are
+    # not required to resolve to a human-readable page.
+    TYPES = {
+      401 => "urn:metatron:problem:unauthorized",
+      413 => "urn:metatron:problem:payload-too-large",
+      500 => "urn:metatron:problem:internal-server-error"
+    }.freeze
+
+    class << self
+      # Build a Rack response triple carrying a problem document.
+      #
+      # @param status [Integer] the HTTP status code
+      # @param title [String] a short, human-readable summary of the problem
+      # @param detail [String, nil] a human-readable explanation of this occurrence
+      # @param type [String, nil] overrides the default problem type for the status
+      # @param headers [Hash] additional response headers
+      # @return [Array] a Rack response
+      def response(status:, title:, detail: nil, type: nil, headers: {})
+        body = document(status: status, title: title, detail: detail, type: type)
+        [status, { "content-type" => CONTENT_TYPE }.merge(headers), [body]]
+      end
+
+      # Build a problem document.
+      #
+      # @return [String] the serialized problem document
+      def document(status:, title:, detail: nil, type: nil)
+        problem = { type: type || TYPES.fetch(status, "about:blank"), title: title, status: status }
+        problem[:detail] = detail unless detail.nil?
+        problem.to_json
+      end
+    end
+  end
+end

data/lib/metatron/template.rb

@@ -38,6 +38,10 @@ module Metatron
     end
 
     def initialize(name)
+      unless name.is_a?(String) && !name.strip.empty?
+        raise ArgumentError, "name must be a non-empty string"
+      end
+
       @name = name
       @api_version = "v1"
       @kind = find_kind

data/lib/metatron/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Metatron
-  VERSION = "0.11.4"
+  VERSION = "0.11.5"
 end

data/lib/metatron.rb

@@ -11,15 +11,24 @@ require "base64"
 
 # The top-level module for Metatron
 module Metatron
+  # Default request body limit (1 MiB). Override via
+  # METATRON_MAX_REQUEST_BODY_BYTES or Metatron.max_body_bytes=.
+  DEFAULT_MAX_BYTES = 1_048_576
+
   class Error < StandardError; end
+  class PayloadTooLarge < Error; end
   class ConfigError < Error; end
 
-  singleton_class.attr_accessor :logger
+  singleton_class.attr_accessor :max_body_bytes, :logger
+  self.max_body_bytes = ENV.fetch("METATRON_MAX_REQUEST_BODY_BYTES", DEFAULT_MAX_BYTES).to_i
   self.logger = Logger.new($stdout, level: ENV.fetch("LOG_LEVEL", :warn))
 end
 
 # Internal requirements
 require "metatron/version"
+require "metatron/problem"
+require "metatron/middleware/auth"
+require "metatron/middleware/body_limit"
 require "metatron/template"
 require "metatron/templates/concerns/annotated"
 require "metatron/templates/concerns/namespaced"

data/metatron.gemspec

@@ -28,8 +28,9 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.3"
 
   spec.add_dependency "base64"
-  spec.add_dependency "json", "~> 2.6"
-  spec.add_dependency "rack", ">= 2.2.8", "< 4"
+  # Floors past the last rubysec/ruby-advisory-db patched releases.
+  spec.add_dependency "json", ">= 2.21.2", "< 3"
+  spec.add_dependency "rack", ">= 2.2.25", "< 4"
 
   spec.add_development_dependency "bundler",             "~> 2.3"
   spec.add_development_dependency "byebug",              "~> 11"

data/script/integration

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+#
+# Run Metatron's integration suite against a real Metacontroller installation
+# in a throwaway k3d cluster.
+#
+# Usage:
+#   script/integration            # create cluster, run specs, delete cluster
+#   script/integration --keep     # leave the cluster running for debugging
+#   script/integration --metacontroller-version v4.17.6
+#   script/integration --k3d-version v5.9.0
+#
+# Environment:
+#   K3D_CLUSTER_NAME            cluster name (default: metatron-integration)
+#   K3D_VERSION                 expected k3d version, verified when set
+#   METATRON_IT_NAMESPACE       namespace for the fixture controller
+#   METATRON_IT_IMAGE           fixture image tag (default: metatron-integration:test)
+#   METATRON_IT_AUTH_TOKEN      bearer token shared with Metacontroller
+#   METACONTROLLER_VERSION      release tag to install (default: v4.17.6)
+#   METACONTROLLER_REPO         local Metacontroller clone; used when the tag exists
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+CLUSTER="${K3D_CLUSTER_NAME:-metatron-integration}"
+K3D_VERSION="${K3D_VERSION:-}"
+NAMESPACE="${METATRON_IT_NAMESPACE:-metatron-integration}"
+IMAGE="${METATRON_IT_IMAGE:-metatron-integration:test}"
+AUTH_TOKEN="${METATRON_IT_AUTH_TOKEN:-integration-secret-token}"
+METACONTROLLER_VERSION="${METACONTROLLER_VERSION:-v4.17.6}"
+METACONTROLLER_REPO="${METACONTROLLER_REPO:-$HOME/Development/golang/metacontroller}"
+KEEP=0
+
+usage() {
+  sed -n '2,/^set -euo pipefail$/p' "$0" | sed '$d' | sed 's/^# \{0,1\}//'
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --keep)
+      KEEP=1
+      shift
+      ;;
+    --metacontroller-version)
+      METACONTROLLER_VERSION="${2:?missing version}"
+      shift 2
+      ;;
+    --k3d-version)
+      K3D_VERSION="${2:?missing version}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+for command in docker k3d kubectl; do
+  if ! command -v "$command" >/dev/null 2>&1; then
+    echo "error: $command is required but not installed" >&2
+    exit 1
+  fi
+done
+
+if ! docker info >/dev/null 2>&1; then
+  echo "error: the Docker daemon is not reachable" >&2
+  exit 1
+fi
+
+if [[ -n "$K3D_VERSION" ]]; then
+  installed_k3d="$(k3d version | awk '/^k3d version/ {print $3; exit}')"
+  if [[ "$installed_k3d" != "$K3D_VERSION" ]]; then
+    echo "error: requested k3d $K3D_VERSION but $installed_k3d is installed" >&2
+    exit 1
+  fi
+fi
+
+KUBECONFIG_FILE=""
+cleanup() {
+  status=$?
+  if [[ "$KEEP" -eq 0 ]]; then
+    k3d cluster delete "$CLUSTER" >/dev/null 2>&1 || true
+  else
+    echo
+    echo "Cluster '$CLUSTER' left running."
+    echo "  export KUBECONFIG=$KUBECONFIG_FILE"
+    echo "  kubectl -n $NAMESPACE get widgets,deployments,services,configmaps,secrets"
+  fi
+  if [[ "$KEEP" -eq 0 && -n "$KUBECONFIG_FILE" ]]; then
+    rm -f "$KUBECONFIG_FILE"
+  fi
+  exit "$status"
+}
+trap cleanup EXIT INT TERM
+
+dump_debug() {
+  echo "=== cluster state ===" >&2
+  kubectl get pods -A >&2 || true
+  echo "=== fixture controller logs ===" >&2
+  kubectl -n "$NAMESPACE" logs -l app=widget-controller --tail=200 >&2 || true
+}
+trap dump_debug ERR
+
+render_manifest() {
+  sed -e "s|__NAMESPACE__|$NAMESPACE|g" \
+      -e "s|__IMAGE__|$IMAGE|g" \
+      -e "s|__AUTH_TOKEN__|$AUTH_TOKEN|g" \
+      "$1"
+}
+
+apply_metacontroller_manifest() {
+  local file="$1"
+  if [[ -n "$LOCAL_MANIFESTS" ]]; then
+    git -C "$METACONTROLLER_REPO" show "$METACONTROLLER_VERSION:manifests/production/$file" | kubectl apply -f -
+  else
+    kubectl apply -f "$REMOTE_MANIFESTS/$file"
+  fi
+}
+
+# Prefer the local Metacontroller clone when it has the requested tag, so
+# local runs do not depend on GitHub. CI falls back to the pinned release URL.
+LOCAL_MANIFESTS=""
+REMOTE_MANIFESTS=""
+if [[ -d "$METACONTROLLER_REPO/.git" ]] && \
+   git -C "$METACONTROLLER_REPO" rev-parse -q --verify "refs/tags/$METACONTROLLER_VERSION" >/dev/null; then
+  LOCAL_MANIFESTS=1
+  echo "Using Metacontroller $METACONTROLLER_VERSION manifests from $METACONTROLLER_REPO"
+else
+  REMOTE_MANIFESTS="https://raw.githubusercontent.com/metacontroller/metacontroller/${METACONTROLLER_VERSION}/manifests/production"
+  echo "Using Metacontroller $METACONTROLLER_VERSION manifests from $REMOTE_MANIFESTS"
+fi
+
+echo "Creating k3d cluster '$CLUSTER'"
+k3d cluster delete "$CLUSTER" >/dev/null 2>&1 || true
+k3d cluster create "$CLUSTER" \
+  --agents 1 \
+  --wait \
+  --timeout 180s \
+  --kubeconfig-update-default=false \
+  --kubeconfig-switch-context=false
+
+KUBECONFIG_FILE="$(mktemp)"
+k3d kubeconfig write "$CLUSTER" --output "$KUBECONFIG_FILE" >/dev/null
+export KUBECONFIG="$KUBECONFIG_FILE"
+
+echo "Building fixture controller image '$IMAGE'"
+docker build --file "$ROOT/integration/Dockerfile" --tag "$IMAGE" "$ROOT"
+
+echo "Importing '$IMAGE' into '$CLUSTER'"
+k3d image import "$IMAGE" --cluster "$CLUSTER"
+
+echo "Installing Metacontroller $METACONTROLLER_VERSION"
+apply_metacontroller_manifest metacontroller-namespace.yaml
+apply_metacontroller_manifest metacontroller-crds-v1.yaml
+apply_metacontroller_manifest metacontroller-rbac.yaml
+apply_metacontroller_manifest metacontroller.yaml
+
+kubectl wait --for=condition=Established --timeout=120s \
+  crd/compositecontrollers.metacontroller.k8s.io
+kubectl -n metacontroller rollout status statefulset/metacontroller --timeout=180s
+
+echo "Deploying fixture controller in namespace '$NAMESPACE'"
+render_manifest "$ROOT/integration/manifests/namespace.yaml" | kubectl apply -f -
+render_manifest "$ROOT/integration/manifests/crd.yaml" | kubectl apply -f -
+kubectl wait --for=condition=Established --timeout=120s \
+  crd/widgets.metatron.therubyist.org
+render_manifest "$ROOT/integration/manifests/controller.yaml" | kubectl apply -f -
+kubectl -n "$NAMESPACE" rollout status deployment/widget-controller --timeout=180s
+render_manifest "$ROOT/integration/manifests/composite-controller.yaml" | kubectl apply -f -
+
+export RUN_INTEGRATION=1
+export METATRON_IT_NAMESPACE="$NAMESPACE"
+export METATRON_IT_RUN_ID="${METATRON_IT_RUN_ID:-$(date +%s)-$$}"
+export METATRON_IT_AUTH_TOKEN="$AUTH_TOKEN"
+
+cd "$ROOT"
+bundle exec rspec spec/integration --format documentation