k8s-rails 0.1.0

data/lib/k8s-rails.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# K8sRails — Kubernetes API / CRD convention layer for Rails applications.
+#
+# Design: docs/design.md (KBR-DESIGN-001)
+#
+# Load-time contract (§3 / §7): requiring this entry point has NO side effects
+# and does NOT load kruby. The kruby-dependent Client (and therefore kruby
+# itself) is loaded lazily on the first `K8sRails::Client.build` /
+# `K8sRails.connected?` call. This lets the gem be `require`d even when no
+# cluster is reachable and keeps kruby's load cost out of app boot.
+module K8sRails
+  # Lazy load (§7): referencing K8sRails::Client (e.g. Client.build) is the
+  # moment kruby is required — never at gem require time. Direct constant
+  # access works, while a plain `require "k8s-rails"` stays kruby-free.
+  autoload :Client, File.expand_path("k8s_rails/client", __dir__)
+
+  class << self
+    # Settings, set once via `configure` (§5.1).
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Configure the gem. Runs once — a second call warns and is ignored
+    # (design §5.1). Yields the Configuration object.
+    def configure
+      if @configured
+        warn "[K8sRails] K8sRails.configure called more than once; ignoring the second call."
+        return config
+      end
+
+      @configured = true
+      yield config
+      config
+    end
+
+    # Reset configuration, the cached transport, and declared CRDs.
+    # Test support (§5.1).
+    def reset!
+      @config = nil
+      @configured = false
+      CRD.clear!
+      Client.reset! if client_loaded?
+    end
+
+    # The shared transport (design §5.2). Triggers the lazy load of the
+    # kruby-dependent Client on first call.
+    def client
+      Client.build
+    end
+
+    # Lightweight connectivity check (§5.2). Raises Unavailable/ApiError.
+    def connected?
+      Client.connected?
+    end
+
+    # Declare a CRD and return its Resource class (design §5.3, K5).
+    #   Workflow = K8sRails.crd(group: "argoproj.io", version: "v1alpha1",
+    #                            plural: "workflows", kind: "Workflow")
+    # Re-declaring the same kind raises K8sRails::RedeclarationError.
+    def crd(group:, version:, plural:, kind:, namespace: nil, readonly: true)
+      CRD.declare(group:, version:, plural:, kind:, namespace:, readonly:)
+    end
+
+    # Design §8: run an API call inside a `k8s-rails.request` notification.
+    #
+    #   K8sRails.instrument(:list, group: "g", version: "v1", plural: "p", namespace: "ns") do
+    #     # ... actual transport call ...
+    #   end
+    #
+    # The notification payload is
+    #   { operation:, group:, version:, plural:, namespace:, duration_ms:,
+    #     status: "ok" | "unavailable" | "api_error" }.
+    # The block's return value always flows through unchanged. No-op when
+    # `config.instrumentation` is false or ActiveSupport is not loaded.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- fixed §8 wrapper
+    def instrument(operation, metadata)
+      return yield unless instrumentation_enabled?
+
+      payload = { operation: operation }.merge(metadata)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        result = yield
+        payload[:status] = "ok"
+      rescue K8sRails::Unavailable
+        payload[:status] = "unavailable"
+        raise
+      rescue K8sRails::ApiError, K8sRails::NotFound
+        payload[:status] = "api_error"
+        raise
+      ensure
+        # Fallback for exceptions outside the K8sRails hierarchy (e.g. a
+        # programming error like NoMethodError from a malformed stub): keep
+        # the documented status enum (ok/unavailable/api_error) intact while
+        # re-raising the original exception.
+        payload[:status] ||= "api_error"
+        payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1_000).round(2)
+        ActiveSupport::Notifications.instrument("k8s-rails.request", payload)
+      end
+      result
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    # True only when the user opted in AND ActiveSupport is actually loaded
+    # (spec helper may stub this to exercise the no-op path deterministically).
+    def instrumentation_enabled?
+      config.instrumentation && defined?(ActiveSupport::Notifications)
+    end
+  end
+
+  # Whether the kruby-dependent client file has actually been required yet
+  # (an autoloaded-but-unreferenced constant still counts as "not loaded"
+  # for `defined?`/`const_defined?`, so $LOADED_FEATURES is authoritative).
+  def self.client_loaded?
+    $LOADED_FEATURES.any? { |f| f.end_with?("k8s_rails/client.rb") }
+  end
+end
+
+# Pure-Ruby components with no kruby dependency — safe to load eagerly.
+require_relative "k8s_rails/version"
+require_relative "k8s_rails/errors"
+require_relative "k8s_rails/configuration"
+require_relative "k8s_rails/normalizer"
+require_relative "k8s_rails/crd"

data/lib/k8s_rails/client.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+# kruby の require は本ファイルにのみ許される（design §7）。
+# 他のファイルは kruby の定数・クラスを参照しない。
+# Typhoeus は kruby が require するため転送層例外もここに閉じ込める。
+require "kubernetes"
+
+module K8sRails
+  # Resolves a connection to the Kubernetes API and exposes the four
+  # CustomObjects operations as a small internal transport (design §5.2 / §7).
+  #
+  #   api = K8sRails::Client.build
+  #   api.list(group, version, namespace, plural)
+  #   api.get(group, version, namespace, plural, name)
+  #   api.create(group, version, namespace, plural, body)
+  #   api.patch(group, version, namespace, plural, name, body)
+  #
+  # Connection is LAZY: `build` does no network I/O — it only resolves a
+  # `Kubernetes::Configuration` and builds an in-memory `CustomObjectsApi`.
+  # The first real call is where DNS/timeout/TLS can fail.
+  class Client
+    class << self
+      # Return the shared transport, building it on first call (lazy connect).
+      #
+      # Resolution order (design §5.2):
+      #   0. `config.api_client` (test injection) → used as the transport
+      #      directly, connection resolution skipped.
+      #   1. `config.connection` if set, else `Kubernetes::Configuration.default_config`
+      #   2. K1 bridge: duplicate `api_key['authorization']` into
+      #      `api_key['BearerToken']` (kruby 1.36 in-cluster/KUBECONFIG write the
+      #      token under 'authorization' but auth_settings reads 'BearerToken').
+      #   3. Build `ApiClient` → `CustomObjectsApi` (in-memory, no I/O).
+      #   4. Wrap in a StringKeyedAdapter that normalizes responses (K2) and
+      #      converts kruby errors to K8sRails exceptions.
+      def build
+        @build ||=
+          if (injected = K8sRails.config.api_client)
+            StringKeyedAdapter.new(injected)
+          else
+            StringKeyedAdapter.new(build_custom_objects_api)
+          end
+      end
+
+      # Lightweight connectivity probe (design §5.2). Performs one lightweight
+      # `/version` call via VersionApi and returns true on success. Raises
+      # K8sRails::Unavailable / ApiError on failure (the app may rescue).
+      def connected?
+        config = build_configuration
+        # The probe also authenticates — apply the K1 bridge or the Authorization
+        # header would be empty on clusters where /version requires auth.
+        bridge_bearer_token(config)
+        VersionApiProbe.new(config).probe
+      end
+
+      # Reset cached connection + transport (test support, §5.1).
+      def reset!
+        @build = nil
+      end
+
+      # Convert a kruby ApiError to the K8sRails exception tree (K3, §5.4).
+      #   - code 0 (transport failure: DNS/timeout/connect/TLS) → Unavailable
+      #   - code 404 → NotFound
+      #   - anything else (401/403/409/422/5xx) → ApiError (keeps code + body)
+      def convert_api_error(kruby_error)
+        code = kruby_error.code
+        return Unavailable.new("K8s に接続できません: #{transport_message(kruby_error)}") if code.zero?
+        return NotFound.new("リソースが見つかりません") if code == 404
+
+        ApiError.new(
+          code: code,
+          response: kruby_error.response_body,
+          message: "Kubernetes API エラー (HTTP #{code})"
+        )
+      end
+
+      private
+
+      # kruby's ApiError#message is "<msg>\nHTTP status code: N". For code 0 the
+      # message is the libcurl reason (e.g. "Could not resolve host"). Strip the
+      # status-code suffix for a clean Unavailable message.
+      def transport_message(kruby_error)
+        kruby_error.message.to_s.sub(/\nHTTP status code:.*\z/, "").strip
+      end
+
+      # Build a lazy in-memory CustomObjectsApi from the resolved configuration.
+      def build_custom_objects_api
+        config = build_configuration
+        bridge_bearer_token(config)
+        api_client = Kubernetes::ApiClient.new(config)
+        Kubernetes::CustomObjectsApi.new(api_client)
+      end
+
+      def build_configuration
+        K8sRails.config.connection || Kubernetes::Configuration.default_config
+      end
+
+      # K1 bridge (kruby 1.36.x quirk): InClusterConfig writes the Bearer token
+      # to `api_key['authorization']` (and the KUBECONFIG path can too), but
+      # `Configuration#auth_settings` reads `api_key['BearerToken']` for the
+      # `Authorization` header. Without the bridge the header is empty → 401.
+      # Duplicate only when the target key is not already set.
+      def bridge_bearer_token(config)
+        auth = config.api_key["authorization"]
+        return if auth.nil? || config.api_key.key?("BearerToken")
+
+        config.api_key["BearerToken"] = auth
+      end
+    end
+
+    # Wraps a CustomObjectsApi (or an injected test double) so that
+    #   - every response is deep-stringified (K2), and
+    #   - kruby errors are converted to K8sRails exceptions (K3).
+    #
+    # The adapter is the ONLY place kruby response shapes / errors are touched,
+    # so a kruby upgrade is a one-file change (§7).
+    class StringKeyedAdapter
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def list(group, version, namespace, plural)
+        handle do
+          Normalizer.stringify(
+            @transport.list_namespaced_custom_object(group, version, namespace, plural)
+          )
+        end
+      end
+
+      def get(group, version, namespace, plural, name)
+        handle do
+          Normalizer.stringify(
+            @transport.get_namespaced_custom_object(group, version, namespace, plural, name)
+          )
+        end
+      end
+
+      def create(group, version, namespace, plural, body)
+        handle do
+          Normalizer.stringify(
+            @transport.create_namespaced_custom_object(group, version, namespace, plural, body)
+          )
+        end
+      end
+
+      def patch(group, version, namespace, plural, name, body)
+        handle do
+          Normalizer.stringify(
+            @transport.patch_namespaced_custom_object(group, version, namespace, plural, name, body)
+          )
+        end
+      end
+
+      private
+
+      def handle
+        yield
+      rescue Kubernetes::ApiError => e
+        raise Client.convert_api_error(e)
+      rescue Kubernetes::ConfigError, Typhoeus::Errors::TyphoeusError => e
+        raise Unavailable, "K8s に接続できません: #{e.message}"
+      end
+    end
+
+    # One-shot /version probe backed by VersionApi#get_code (the kruby 1.36.x
+    # equivalent of a lightweight connectivity check).
+    class VersionApiProbe
+      def initialize(config)
+        @api = Kubernetes::VersionApi.new(Kubernetes::ApiClient.new(config))
+      end
+
+      def probe
+        @api.get_code
+        true
+      rescue Kubernetes::ApiError => e
+        raise Client.convert_api_error(e)
+      rescue Kubernetes::ConfigError, Typhoeus::Errors::TyphoeusError => e
+        raise Unavailable, "K8s に接続できません: #{e.message}"
+      end
+    end
+  end
+end

data/lib/k8s_rails/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module K8sRails
+  # Settings held by `K8sRails.configure` (design §5.1).
+  #
+  #   K8sRails.configure do |config|
+  #     config.namespace = ENV.fetch("K8S_NAMESPACE", "default")
+  #   end
+  #
+  # This class is pure data: it never touches the network or kruby.
+  class Configuration
+    # CRD 宣言が namespace 未指定時のデフォルト。
+    attr_accessor :namespace
+
+    # Kubernetes::Configuration インスタンス。省略時は default_config の自動
+    # 検出（in-cluster → KUBECONFIG）。認証を上書きする場合に指定する。
+    attr_accessor :connection
+
+    # テスト専用（§5.1）。CustomObjectsApi と同型の 4 メソッド
+    # （`get_namespaced_custom_object` 等の *_namespaced_custom_object 4 メソッド）を実装した素の
+    # オブジェクトを指定すると、Client.build は接続解決をスキープしてこれを
+    # 内部トランスポートとして使う。
+    attr_accessor :api_client
+
+    # ActiveSupport::Notifications での計測の ON/OFF（§8。M3 で実装）。
+    attr_accessor :instrumentation
+
+    def initialize
+      @namespace = "default"
+      @connection = nil
+      @api_client = nil
+      @instrumentation = true
+    end
+  end
+end

data/lib/k8s_rails/crd.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module K8sRails
+  # CRD declaration registry + DSL (design §5.3 / K5).
+  #
+  #   Workflow = K8sRails.crd(
+  #     group: "argoproj.io", version: "v1alpha1",
+  #     plural: "workflows", kind: "Workflow",
+  #     namespace: K8sRails.config.namespace, # optional
+  #     readonly: false,                        # default true
+  #   )
+  #
+  # `crd` returns a `Resource` subclass with the coordinates bound; the same
+  # class is registered under its kind name so a second declaration of the
+  # same kind raises K8sRails::RedeclarationError (config-mistake detection).
+  # The registry is in-memory: no kruby, no network at declaration time.
+  class CRD
+    # Registered kinds, e.g. { "Workflow" => Workflow }.
+    def self.registered
+      @registered ||= {}
+    end
+
+    def self.clear!
+      @registered = {}
+    end
+
+    # Declare a CRD and return its Resource class (K5: group/version/plural/
+    # kind are explicit — never guessed). `readonly` must be an explicit
+    # boolean: mutations are enabled ONLY by `readonly: false` (design §5.3 /
+    # K4), so nil/other values fail fast instead of silently allowing writes.
+    def self.declare(group:, version:, plural:, kind:, namespace: nil, readonly: true)
+      unless [true, false].include?(readonly)
+        raise ArgumentError,
+              "readonly must be true or false (got #{readonly.inspect}) — mutations require an explicit readonly: false"
+      end
+
+      if registered.key?(kind)
+        raise RedeclarationError, "CRD kind #{kind} is already declared — re-declaration is a configuration mistake"
+      end
+
+      resource = Resource.declare(
+        group: group,
+        version: version,
+        plural: plural,
+        kind: kind,
+        namespace: namespace,
+        readonly: readonly
+      )
+      registered[kind] = resource
+      resource
+    end
+  end
+end

data/lib/k8s_rails/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module K8sRails
+  # Base class for all K8sRails errors (K3, design §5.4).
+  #
+  # Apps rescue the specific subclass they care about, or `K8sRails::Error`
+  # to catch everything this gem raises. Errors that are NOT wrapped (e.g.
+  # programming errors like NoMethodError) propagate raw on purpose — we never
+  # mask a bug as a K8s problem.
+  class Error < StandardError; end
+
+  # The cluster cannot be reached, or the connection/transport layer failed
+  # (DNS failure, timeout, connection refused, TLS handshake error, etc.).
+  #
+  # In kruby 1.36.x these surface as `Kubernetes::ApiError` with `code == 0`
+  # (the transport layer has no HTTP status). A small allowlist of low-level
+  # network exceptions is also mapped here in case a future kruby/Typhoeus
+  # release lets them escape raw (see Client::TRANSFER_LAYER_ERRORS).
+  class Unavailable < Error; end
+
+  # The requested resource does not exist (HTTP 404).
+  class NotFound < Error; end
+
+  # Any other Kubernetes API error (401/403/409/422/5xx, ...).
+  # Carries the HTTP `#code` and the raw API `#response` body so callers can
+  # inspect or display it.
+  class ApiError < Error
+    attr_reader :code, :response
+
+    def initialize(code:, response: nil, message: nil)
+      @code = code
+      @response = response
+      super(message || "Kubernetes API error (HTTP #{code})")
+    end
+  end
+
+  # create/patch was called on a CRD declared with `readonly: true` (M2).
+  # A configuration mistake — raised, never swallowed.
+  class ReadOnlyError < Error; end
+
+  # A CRD with the same name was declared twice (M2). A configuration mistake.
+  class RedeclarationError < Error; end
+end

data/lib/k8s_rails/normalizer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module K8sRails
+  # Pure-Ruby deep key stringification for API responses (K2, design §5.2).
+  #
+  # kruby deserializes JSON into Hash/Array with SYMBOL keys. Our public API
+  # contract (and the apps that consume it) expect STRING keys, so every
+  # response is passed through here before returning.
+  #
+  # This is deliberately NOT ActiveSupport's `deep_stringify_keys`: the gem
+  # must also work in non-Rails environments (cron scripts, etc.) where
+  # ActiveSupport is absent. No AS dependency.
+  module Normalizer
+    module_function
+
+    # Return a copy of +value+ with all Hash keys converted to strings.
+    # Non-Hash/Array values are returned unchanged (strings, numbers, nil,
+    # Time objects, ...).
+    def stringify(value)
+      deep_stringify_keys(value)
+    end
+
+    def deep_stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, entry), acc|
+          acc[key.to_s] = deep_stringify_keys(entry)
+        end
+      when Array
+        value.map { |entry| deep_stringify_keys(entry) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/k8s_rails/resource.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module K8sRails
+  # Base for generated CRD access classes (design §5.3).
+  #
+  # A `K8sRails.crd` declaration returns a `Class.new(Resource)` with the
+  # declared coordinates bound as class methods. All operations go through
+  # the shared transport (`K8sRails.client`), which handles kruby error
+  # conversion (K3) and response stringification (K2) — this class never
+  # touches kruby itself (§7).
+  #
+  #   Workflow = K8sRails.crd(group: "argoproj.io", version: "v1alpha1",
+  #                            plural: "workflows", kind: "Workflow")
+  #   Workflow.list
+  #   Workflow.find("wf-1")
+  class Resource
+    # Bind declared coordinates to a fresh anonymous subclass. `namespace`
+    # may be nil — resolved from `K8sRails.config.namespace` at call time.
+    def self.declare(group:, version:, plural:, kind:, namespace: nil, readonly: true)
+      Class.new(self) do
+        define_singleton_method(:group_name) { group }
+        define_singleton_method(:version_name) { version }
+        define_singleton_method(:plural_name) { plural }
+        define_singleton_method(:kind_name) { kind }
+        define_singleton_method(:declared_namespace) { namespace }
+        define_singleton_method(:readonly?) { readonly }
+      end
+    end
+
+    class << self
+      # All objects in the namespace. Returns an array of string-keyed Hashes
+      # (design §5.3: `[{ "name" => "...", ... }]`).
+      def list(namespace: resolved_namespace)
+        K8sRails.instrument(:list, instrument_meta(namespace)) do
+          transport.list(group_name, version_name, namespace, plural_name)["items"] || []
+        end
+      end
+
+      # One object by name. Raises K8sRails::NotFound when absent.
+      def find(name, namespace: resolved_namespace)
+        K8sRails.instrument(:find, instrument_meta(namespace)) do
+          transport.get(group_name, version_name, namespace, plural_name, name)
+        end
+      end
+
+      # Like `find`, but returns nil instead of raising on NotFound.
+      def find_or_nil(name, namespace: resolved_namespace)
+        find(name, namespace: namespace)
+      rescue NotFound
+        nil
+      end
+
+      # Create from a CRD body hash. `readonly: true` declarations raise
+      # K8sRails::ReadOnlyError (K4).
+      def create(attributes, namespace: resolved_namespace)
+        assert_writable
+        K8sRails.instrument(:create, instrument_meta(namespace)) do
+          transport.create(group_name, version_name, namespace, plural_name, attributes)
+        end
+      end
+
+      # JSON Patch a named object. Same readonly restriction as `create`.
+      def patch(name, operations, namespace: resolved_namespace)
+        assert_writable
+        K8sRails.instrument(:patch, instrument_meta(namespace)) do
+          transport.patch(group_name, version_name, namespace, plural_name, name, operations)
+        end
+      end
+
+      private
+
+      # Notification metadata for design §8 (`k8s-rails.request`).
+      def instrument_meta(namespace)
+        { group: group_name, version: version_name, plural: plural_name, namespace: }
+      end
+
+      # Declared namespace wins; otherwise the gem default (resolved at call
+      # time so `K8sRails.reset!` + reconfigure works in tests).
+      def resolved_namespace
+        declared_namespace || K8sRails.config.namespace
+      end
+
+      def transport
+        K8sRails.client
+      end
+
+      def assert_writable
+        return unless readonly?
+
+        raise ReadOnlyError, "#{kind_name} is declared readonly — create/patch are disabled (K4)"
+      end
+    end
+  end
+end

data/lib/k8s_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module K8sRails
+  VERSION = "0.1.0"
+end