kube_schema 1.3.0 → 1.3.2

data/lib/kube/schema/instance.rb

@@ -39,44 +39,47 @@ module Kube
 
       # Look up a resource by kind (e.g. "Deployment", "NetworkPolicy").
       # Returns a class that inherits from Kube::Schema::Resource.
+      #
+      # Custom schemas registered via Kube::Schema.register take precedence
+      # over built-in definitions, allowing users to override or extend the
+      # schema for any kind.
       def [](kind)
         @resource_classes[kind] ||= begin
-          entry = find_gvk_entry(kind)
-
-          if entry.nil?
-            raise "No resource schema found for #{kind}!" \
-              "\nUse #list_resources to see available kinds for v#{version}."
-          end
-
-          ref_schema = schemer.ref("#/definitions/#{entry[:definition_key]}")
-          defaults = entry[:defaults].freeze
-
-          Class.new(::Kube::Schema::Resource) do
-            @schema = ref_schema
-            @defaults = defaults
-
-            def self.schema
-              @schema || superclass.schema
+          # Custom schemas win over built-in definitions.
+          custom = find_custom_entry(kind)
+          if custom
+            build_resource_class(custom[:schema], custom[:defaults])
+          else
+            entry = find_gvk_entry(kind)
+
+            if entry.nil?
+              raise "No resource schema found for #{kind}!" \
+                "\nUse #list_resources to see available kinds for v#{version}."
             end
 
-            def self.defaults
-              @defaults || superclass.defaults
-            end
+            ref_schema = schemer.ref("#/definitions/#{entry[:definition_key]}")
+            build_resource_class(ref_schema, entry[:defaults].freeze)
           end
         end
       end
 
-      # All available resource kinds for this version.
+      # All available resource kinds for this version, including any
+      # custom schemas registered via Kube::Schema.register.
       #
       # @return [Array<String>] sorted kind names
       def list_resources
-        gvk_index.keys.sort
+        (gvk_index.keys + Schema.custom_schemas.keys).uniq.sort
       end
 
       private
 
         # The JSONSchemer instance for this version's Swagger document.
         # Cached at the class level so it's built once per version.
+        #
+        # After loading the base Swagger JSON, merges in any extra definition
+        # files found in the schemas directory (e.g. crd-definitions.json,
+        # loft-definitions.json). These files are flat JSON objects where keys
+        # are definition names and values are OpenAPI v2 schema objects.
         def schemer
           self.class.schemers[@version] ||= begin
             path = File.join(SCHEMAS_DIR, "v#{version}.json")
@@ -87,7 +90,18 @@ module Kube
                 "\nUse `Kube::Schema.schema_versions` to get a list."
             end
 
-            JSONSchemer.schema(JSON.parse(File.read(path)))
+            schema = JSON.parse(File.read(path))
+
+            # Merge extra definition files (*-definitions.json) into the
+            # base schema so CRD and aggregated-API types (e.g. loft,
+            # gateway-api) are available alongside built-in k8s types.
+            Dir.glob(File.join(SCHEMAS_DIR, "*-definitions.json")).each do |defs_path|
+              extra = JSON.parse(File.read(defs_path))
+              schema["definitions"] ||= {}
+              schema["definitions"].merge!(extra)
+            end
+
+            JSONSchemer.schema(schema)
           end
         end
 
@@ -151,6 +165,41 @@ module Kube
 
           nil
         end
+
+        # Find a custom schema entry by kind (case-insensitive).
+        # Returns the { schema:, defaults: } hash or nil.
+        def find_custom_entry(kind)
+          registry = Schema.custom_schemas
+          return registry[kind] if registry.key?(kind)
+
+          registry.each do |k, v|
+            return v if k.downcase == kind.downcase
+          end
+
+          nil
+        end
+
+        # Build a Resource subclass from a JSONSchemer instance and defaults hash.
+        def build_resource_class(schema_instance, defaults)
+          Class.new(::Kube::Schema::Resource) do
+            @schema = schema_instance
+            @defaults = defaults
+
+            def self.schema
+              @schema || superclass.schema
+            end
+
+            def self.defaults
+              @defaults || superclass.defaults
+            end
+          end
+        end
+
+        # Called by Kube::Schema.register and reset_custom_schemas! to
+        # invalidate cached resource classes so new registrations take effect.
+        def clear_resource_cache!
+          @resource_classes.clear
+        end
     end
   end
 end

data/lib/kube/schema/resource.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "black_hole_struct"
-
 module Kube
   module Schema
     class Resource
@@ -9,13 +7,16 @@ module Kube
       def initialize(hash = {}, &block)
         deep_symbolize_keys(self.class.defaults.to_h).then do |defaults|
 
+          # You are NEVER allowed to change `apiVersion` or `kind`
+          # Therefore, they are ONLY ever set from the self.defaults
+          # property.
           deep_symbolize_keys(hash).then do |symbolized|
             config = defaults.merge({
-              metadata: symbolized.delete(:metadata),
-              spec: symbolized.delete(:spec),
+              metadata: symbolized.delete(:metadata) || {},
+              spec: symbolized.delete(:spec) || {},
             })
 
-            @data = BlackHoleStruct.new(config)
+            @data = config
           end
         end
 
@@ -68,7 +69,7 @@ module Kube
       # they are facts derived from the GVK metadata.
       def to_h
         defaults = self.class.defaults
-        data = @data.to_h
+        data = @data.reject { |_, v| v.is_a?(Hash) && v.empty? }
 
         if defaults
           symbolized = deep_symbolize_keys(defaults)

data/lib/kube/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Schema
-    VERSION = "1.3.0"
+    VERSION = "1.3.2"
   end
 end

data/lib/kube/schema.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative '../monkey_patches'
-require_relative '../kube/errors'
+require_relative 'monkey_patches'
+require_relative 'errors'
 require_relative 'schema/version'
 require_relative 'schema/resource'
 require_relative 'schema/instance'
@@ -16,6 +16,7 @@ module Kube
 
     @schema_version = nil
     @instances = {}
+    @custom_schemas = {}
 
     GEM_ROOT = File.expand_path("../..", __dir__).freeze
     SCHEMAS_DIR = File.join(GEM_ROOT, "schemas").freeze
@@ -26,6 +27,71 @@ module Kube
       # When nil, the DEFAULT_VERSION is used.
       attr_accessor :schema_version
 
+      # Custom schemas registered via Kube::Schema.register.
+      # Keys are kind strings, values are { schema:, defaults: } hashes.
+      attr_reader :custom_schemas
+
+      # Register a standalone JSON Schema for a custom resource kind.
+      #
+      # This lets users add CRD schemas from any source — for example,
+      # the datreeio/CRDs-catalog, operator repos, or their own CRDs.
+      # Registered kinds take precedence over built-in definitions.
+      #
+      # @param kind [String] The Kubernetes Kind (e.g. "Certificate")
+      # @param schema [Hash, String, Pathname] JSON Schema as a Hash,
+      #   a JSON string, or a file path to a .json file
+      # @param api_version [String] The apiVersion (e.g. "cert-manager.io/v1")
+      #
+      # @example Register from a local file
+      #   Kube::Schema.register("Certificate",
+      #     schema: "schemas/cert-manager.io/certificate_v1.json",
+      #     api_version: "cert-manager.io/v1"
+      #   )
+      #
+      # @example Register from a Hash
+      #   Kube::Schema.register("MyResource",
+      #     schema: { "type" => "object", "properties" => { ... } },
+      #     api_version: "example.com/v1"
+      #   )
+      #
+      def register(kind, schema:, api_version:)
+        require "json"
+        require "json_schemer"
+
+        parsed = case schema
+          when Hash
+            schema
+          when String, Pathname
+            path = schema.to_s
+            if File.exist?(path)
+              JSON.parse(File.read(path))
+            else
+              JSON.parse(path)
+            end
+          else
+            raise ArgumentError,
+              "schema must be a Hash, a JSON string, or a file path — got #{schema.class}"
+          end
+
+        @custom_schemas[kind] = {
+          schema: JSONSchemer.schema(parsed),
+          defaults: { "apiVersion" => api_version, "kind" => kind }.freeze
+        }
+
+        # Invalidate cached resource classes on all instances so the
+        # new registration takes effect immediately.
+        @instances.each_value { |inst| inst.send(:clear_resource_cache!) }
+
+        kind
+      end
+
+      # Remove all custom schema registrations.
+      # Useful for test teardown or resetting state.
+      def reset_custom_schemas!
+        @custom_schemas.clear
+        @instances.each_value { |inst| inst.send(:clear_resource_cache!) }
+      end
+
       # Kube::Schema["1.34"]           => cached Instance (supports ["Deployment"] chaining)
       # Kube::Schema["Deployment"]     => Resource via the default version
       def [](key)
@@ -45,7 +111,9 @@ module Kube
             )
           end
         else
-          Instance.new(schema_version || DEFAULT_VERSION)[key]
+          version = schema_version || DEFAULT_VERSION
+          @instances[version] ||= Instance.new(version)
+          @instances[version][key]
         end
       end