File Coverage

blib/lib/IO/K8s.pm

Criterion	Covered	Total	%
statement	170	215	79.0
branch	78	126	61.9
condition	26	54	48.1
subroutine	19	23	82.6
pod	9	13	69.2
total	302	431	70.0

package IO::K8s;
# ABSTRACT: Objects representing things found in the Kubernetes API

use v5.10;
use Moo;
use Module::Runtime qw(require_module);
use JSON::MaybeXS;
use Scalar::Util ();
use namespace::clean;

our $VERSION = '1.008';

# Track which classes we've auto-generated
my %_autogen_cache;

# Default resource map - maps short names to class paths relative to IO::K8s
my %DEFAULT_RESOURCE_MAP = (
    # Core API resources
    Binding => 'Api::Core::V1::Binding',
    ComponentStatus => 'Api::Core::V1::ComponentStatus',
    ConfigMap => 'Api::Core::V1::ConfigMap',
    Endpoints => 'Api::Core::V1::Endpoints',
    Event => 'Api::Core::V1::Event',
    LimitRange => 'Api::Core::V1::LimitRange',
    Namespace => 'Api::Core::V1::Namespace',
    Node => 'Api::Core::V1::Node',
    PersistentVolume => 'Api::Core::V1::PersistentVolume',
    PersistentVolumeClaim => 'Api::Core::V1::PersistentVolumeClaim',
    Pod => 'Api::Core::V1::Pod',
    PodTemplate => 'Api::Core::V1::PodTemplate',
    ReplicationController => 'Api::Core::V1::ReplicationController',
    ResourceQuota => 'Api::Core::V1::ResourceQuota',
    Secret => 'Api::Core::V1::Secret',
    Service => 'Api::Core::V1::Service',
    ServiceAccount => 'Api::Core::V1::ServiceAccount',
    # Apps
    ControllerRevision => 'Api::Apps::V1::ControllerRevision',
    DaemonSet => 'Api::Apps::V1::DaemonSet',
    Deployment => 'Api::Apps::V1::Deployment',
    ReplicaSet => 'Api::Apps::V1::ReplicaSet',
    StatefulSet => 'Api::Apps::V1::StatefulSet',
    # Batch
    CronJob => 'Api::Batch::V1::CronJob',
    Job => 'Api::Batch::V1::Job',
    # Networking
    Ingress => 'Api::Networking::V1::Ingress',
    IngressClass => 'Api::Networking::V1::IngressClass',
    NetworkPolicy => 'Api::Networking::V1::NetworkPolicy',
    # Storage
    CSIDriver => 'Api::Storage::V1::CSIDriver',
    CSINode => 'Api::Storage::V1::CSINode',
    CSIStorageCapacity => 'Api::Storage::V1::CSIStorageCapacity',
    StorageClass => 'Api::Storage::V1::StorageClass',
    VolumeAttachment => 'Api::Storage::V1::VolumeAttachment',
    # Authorization
    LocalSubjectAccessReview => 'Api::Authorization::V1::LocalSubjectAccessReview',
    SelfSubjectAccessReview => 'Api::Authorization::V1::SelfSubjectAccessReview',
    SelfSubjectRulesReview => 'Api::Authorization::V1::SelfSubjectRulesReview',
    SubjectAccessReview => 'Api::Authorization::V1::SubjectAccessReview',
    # Authentication
    SelfSubjectReview => 'Api::Authentication::V1::SelfSubjectReview',
    TokenRequest => 'Api::Authentication::V1::TokenRequest',
    TokenReview => 'Api::Authentication::V1::TokenReview',
    # RBAC
    ClusterRole => 'Api::Rbac::V1::ClusterRole',
    ClusterRoleBinding => 'Api::Rbac::V1::ClusterRoleBinding',
    Role => 'Api::Rbac::V1::Role',
    RoleBinding => 'Api::Rbac::V1::RoleBinding',
    # Policy
    Eviction => 'Api::Policy::V1::Eviction',
    PodDisruptionBudget => 'Api::Policy::V1::PodDisruptionBudget',
    # Autoscaling
    HorizontalPodAutoscaler => 'Api::Autoscaling::V2::HorizontalPodAutoscaler',
    Scale => 'Api::Autoscaling::V1::Scale',
    # Certificates
    CertificateSigningRequest => 'Api::Certificates::V1::CertificateSigningRequest',
    # Coordination
    Lease => 'Api::Coordination::V1::Lease',
    # Discovery
    EndpointSlice => 'Api::Discovery::V1::EndpointSlice',
    # Scheduling
    PriorityClass => 'Api::Scheduling::V1::PriorityClass',
    # Node
    RuntimeClass => 'Api::Node::V1::RuntimeClass',
    # Flowcontrol
    FlowSchema => 'Api::Flowcontrol::V1::FlowSchema',
    PriorityLevelConfiguration => 'Api::Flowcontrol::V1::PriorityLevelConfiguration',
    # Admissionregistration
    MutatingWebhookConfiguration => 'Api::Admissionregistration::V1::MutatingWebhookConfiguration',
    ValidatingAdmissionPolicy => 'Api::Admissionregistration::V1::ValidatingAdmissionPolicy',
    ValidatingAdmissionPolicyBinding => 'Api::Admissionregistration::V1::ValidatingAdmissionPolicyBinding',
    ValidatingWebhookConfiguration => 'Api::Admissionregistration::V1::ValidatingWebhookConfiguration',
    # Extension APIs (different base paths)
    CustomResourceDefinition => 'ApiextensionsApiserver::Pkg::Apis::Apiextensions::V1::CustomResourceDefinition',
    APIService => 'KubeAggregator::Pkg::Apis::Apiregistration::V1::APIService',
);

has json => (is => 'ro', default => sub {
    return JSON::MaybeXS->new(utf8 => 1, canonical => 1);
});

# Resource map - can be customized per instance
# Returns a copy so add() can safely mutate without affecting other instances
has resource_map => (
    is => 'ro',
    lazy => 1,
    default => sub { +{ %DEFAULT_RESOURCE_MAP } },
);

# OpenAPI spec for auto-generating unknown types
has openapi_spec => (
    is => 'ro',
    predicate => 1,
);

# External resource map providers to merge at construction time
# e.g. with => ['IO::K8s::Cilium'] or with => [IO::K8s::Cilium->new]
has with => (
    is => 'ro',
    default => sub { [] },
);

# User namespaces to search for pre-built classes (checked before IO::K8s::)
# e.g. ['MyProject::K8s'] will look for MyProject::K8s::HelmChart before IO::K8s::...
has class_namespaces => (
    is => 'ro',
    default => sub { [] },
);

# Internal: unique autogen namespace for this instance (isolated, collision-free)
has _autogen_namespace => (
    is => 'ro',
    lazy => 1,
    default => sub {
        my $self = shift;
        # Create unique identifier based on object address
        my $id = sprintf('%x', 0 + $self);
        return "IO::K8s::_AUTOGEN_$id";
    },
);

# Class method to get default resource map
sub default_resource_map { \%DEFAULT_RESOURCE_MAP }

sub BUILD {
    my ($self) = @_;
    $self->add(@{$self->with}) if @{$self->with};
}

# Merge external resource maps into this instance
# Accepts: class names, objects with resource_map(), or plain hashrefs
sub add {
    my ($self, @providers) = @_;
    my $map = $self->resource_map;

    for my $provider (@providers) {
        my $ext_map;
        if (ref $provider eq 'HASH') {
            $ext_map = $provider;
        } else {
            my $obj = ref $provider ? $provider : do {
                require_module($provider); $provider->new;
            };
            $ext_map = $obj->resource_map;
        }

        for my $kind (keys %$ext_map) {
            my $class_path = $ext_map->{$kind};

            # Resolve full class name for api_version lookup
            my $full_class = $class_path =~ /^\+/
                ? substr($class_path, 1) : "IO::K8s::$class_path";

            # Try to load the class and get its api_version
            my $api_version;
            if (_class_exists($full_class) && $full_class->can('api_version')) {
                $api_version = $full_class->api_version;
            }

            if (exists $map->{$kind}) {
                # COLLISION: short name already taken
                # Ensure the original entry also has a domain-qualified key
                my $orig_path = $map->{$kind};
                my $orig_class = $orig_path =~ /^\+/
                    ? substr($orig_path, 1) : "IO::K8s::$orig_path";
                if (_class_exists($orig_class) && $orig_class->can('api_version')) {
                    my $orig_av = $orig_class->api_version;
                    if ($orig_av && !exists $map->{"$orig_av/$kind"}) {
                        $map->{"$orig_av/$kind"} = $orig_path;
                    }
                }
                # New entry: domain-qualified only (no short name)
                if ($api_version) {
                    $map->{"$api_version/$kind"} = $class_path;
                }
            } else {
                # No collision: register short name
                $map->{$kind} = $class_path;
                # Also register domain-qualified
                if ($api_version) {
                    $map->{"$api_version/$kind"} = $class_path;
                }
            }
        }
    }
    return $self;
}

# Expand short class name to full class path
# Supports:
#   'Pod'                    -> lookup in resource_map -> IO::K8s::Api::Core::V1::Pod
#   'Api::Core::V1::Pod'     -> IO::K8s::Api::Core::V1::Pod
#   'IO::K8s::...'           -> returned as-is
#   '+MyApp::K8s::Resource'  -> MyApp::K8s::Resource (+ prefix = full class name)
#
# Search order:
#   1. User's class_namespaces (if class exists)
#   2. IO::K8s built-in (resource_map or relative path)
#   3. Auto-generate from openapi_spec (if available)
sub expand_class {
    my ($self, $class, $api_version) = @_;

    # +FullClassName - strip + and use as-is
    return substr($class, 1) if $class =~ /^\+/;

    # Already a full IO::K8s class name - return as-is
    return $class if $class =~ /^IO::K8s::/;

    # Already a loaded class (e.g. CRD class passed by ref) - return as-is
    return $class if _class_exists($class);

    my $map = ref($self) ? $self->resource_map : \%DEFAULT_RESOURCE_MAP;

    # Domain-qualified string: 'cilium.io/v2/NetworkPolicy'
    if ($class =~ m{/}) {
        if (my $mapped = $map->{$class}) {
            return $mapped =~ /^\+/ ? substr($mapped, 1) : "IO::K8s::$mapped";
        }
        return undef;
    }

    # Short name + api_version disambiguation: 'NetworkPolicy' + 'cilium.io/v2'
    if ($api_version) {
        my $qualified = "$api_version/$class";
        if (my $mapped = $map->{$qualified}) {
            return $mapped =~ /^\+/ ? substr($mapped, 1) : "IO::K8s::$mapped";
        }
    }

    # Short name like "Pod" - look up in resource_map
    if (my $mapped = $map->{$class}) {
        # Mapped value with + prefix = full class name
        return substr($mapped, 1) if $mapped =~ /^\+/;

        my $rel_path = $mapped;

        # 1. Check user's class_namespaces first
        if (ref($self)) {
            for my $ns (@{$self->class_namespaces}) {
                my $user_class = "${ns}::${rel_path}";
                return $user_class if _class_exists($user_class);
            }
        }

        # 2. Check IO::K8s built-in
        my $builtin_class = 'IO::K8s::' . $rel_path;
        return $builtin_class if _class_exists($builtin_class);

        # 3. Try auto-generation if we have openapi_spec
        if (ref($self) && $self->has_openapi_spec) {
            my $autogen = $self->_autogen_class_for($class);
            return $autogen if $autogen;
        }

        # Fall back to IO::K8s:: path (might not exist, but let load_class handle error)
        return $builtin_class;
    }

    # Not in resource_map - might be a CRD or relative path
    # 1. Check user's class_namespaces
    if (ref($self)) {
        for my $ns (@{$self->class_namespaces}) {
            my $user_class = "${ns}::${class}";
            return $user_class if _class_exists($user_class);
        }
    }

    # 2. Check IO::K8s relative path
    my $builtin_class = 'IO::K8s::' . $class;
    return $builtin_class if _class_exists($builtin_class);

    # 3. Try auto-generation for unknown types
    if (ref($self) && $self->has_openapi_spec) {
        my $autogen = $self->_autogen_class_for($class);
        return $autogen if $autogen;
    }

    # Fall back
    return $builtin_class;
}

# Check if a class exists (is loaded or can be loaded)
sub _class_exists {
    my ($class) = @_;
    # Check if already loaded
    return 1 if $class->can('new');
    # Try to load it
    eval { require_module($class) };
    return !$@;
}

# Auto-generate a class from OpenAPI spec for unknown type
sub _autogen_class_for {
    my ($self, $kind) = @_;

    return unless $self->has_openapi_spec;

    my $spec = $self->openapi_spec;
    my $defs = $spec->{definitions} // {};

    # Find the definition for this kind
    my $def_name = $self->_find_definition_for_kind($kind, $defs);
    return unless $def_name;

    # Check cache first
    my $cache_key = $self->_autogen_namespace . '::' . $def_name;
    return $_autogen_cache{$cache_key} if $_autogen_cache{$cache_key};

    # Generate the class
    require IO::K8s::AutoGen;
    my $class = IO::K8s::AutoGen::get_or_generate(
        $def_name,
        $defs->{$def_name},
        $defs,
        $self->_autogen_namespace,
    );

    $_autogen_cache{$cache_key} = $class;
    return $class;
}

# Find OpenAPI definition name for a given kind
sub _find_definition_for_kind {
    my ($self, $kind, $defs) = @_;

    # Direct match by kind name at end of definition
    for my $def_name (keys %$defs) {
        my $def = $defs->{$def_name};
        # Check x-kubernetes-group-version-kind
        if (my $gvk_list = $def->{'x-kubernetes-group-version-kind'}) {
            for my $gvk (@$gvk_list) {
                if ($gvk->{kind} eq $kind) {
                    return $def_name;
                }
            }
        }
        # Also check if definition name ends with the kind
        if ($def_name =~ /\.\Q$kind\E$/) {
            return $def_name;
        }
    }

    return undef;
}

sub load_class {
    my ($self, $class) = @_;
    require_module $class;
}

sub json_to_object {
    my ($self, $class_or_json, $json) = @_;

    # If only one argument, auto-detect class from kind
    if (!defined $json) {
        return $self->inflate($class_or_json);
    }

    # Two arguments: class and JSON
    my $class = $self->expand_class($class_or_json);
    my $struct = $self->json->decode($json);
    return $self->struct_to_object($class, $struct);
}

sub struct_to_object {
    my ($self, $class_or_struct, $params) = @_;

    # If only one argument (a hashref), auto-detect class from kind
    if (!defined $params && ref($class_or_struct) eq 'HASH') {
        return $self->inflate($class_or_struct);
    }

    # Two arguments: class and params
    my $class = $self->expand_class($class_or_struct);

    # Already an object of the right class — pass through as-is
    return $params if Scalar::Util::blessed($params) && $params->isa($class);

    $self->load_class($class);
    my $inflated = $self->_inflate_struct($class, $params);
    return $class->new(%$inflated);
}

sub inflate {
    my ($self, $data) = @_;

    # Accept both JSON string and hashref
    my $struct = ref($data) eq 'HASH' ? $data : $self->json->decode($data);

    my $kind = $struct->{kind}
        or die "Cannot inflate: missing 'kind' field in data";
    my $api_version = $struct->{apiVersion};

    my $class = $self->expand_class($kind, $api_version);
    $self->load_class($class);
    my $inflated = $self->_inflate_struct($class, $struct);
    return $class->new(%$inflated);
}

sub new_object {
    my ($self, $short_class, @args) = @_;

    # Support:
    #   ->new_object('Pod', { ... })
    #   ->new_object('Pod', foo => 'bar')
    #   ->new_object('Pod', { ... }, 'cilium.io/v2')  # with api_version
    my ($params, $api_version);
    if (@args >= 2 && ref($args[0]) eq 'HASH' && !ref($args[1])) {
        ($params, $api_version) = @args;
    } elsif (@args == 1 && ref($args[0]) eq 'HASH') {
        $params = $args[0];
    } else {
        $params = { @args };
    }

    my $class = $self->expand_class($short_class, $api_version);
    return $self->struct_to_object($class, $params);
}

sub _inflate_struct {
    my ($self, $class, $params) = @_;

    # Blessed objects should be caught by struct_to_object before reaching
    # here.  If one does slip through (defensive), extract its data rather
    # than silently returning {} which would create an empty object.
    if (Scalar::Util::blessed($params)) {
        return $params->TO_JSON if $params->can('TO_JSON');
        return {};
    }

    return {} unless ref $params eq 'HASH';

    # Opaque fields that should be passed through as-is (complex JSON structures)
    my %opaque_fields = map { $_ => 1 } qw(fieldsV1 rawExtension raw);

    # Get attribute info from the registry (keyed by Perl attr name)
    my $attr_info = $class->_k8s_attr_info;

    # Build reverse map: JSON key → Perl attr name (for sanitized names)
    my %json_to_perl;
    for my $perl_name (keys %$attr_info) {
        my $json_key = $attr_info->{$perl_name}{json_key} // $perl_name;
        $json_to_perl{$json_key} = $perl_name;
    }

    my %args;

    for my $attr (keys %$params) {
        my $value = $params->{$attr};
        next unless defined $value;

        # Pass through opaque fields without type coercion
        if ($opaque_fields{$attr}) {
            $args{$attr} = $value;
            next;
        }

        # Look up by Perl attr name (handles sanitized JSON keys like x-kubernetes-*)
        my $perl_name = $json_to_perl{$attr} // $attr;
        my $info = $attr_info->{$perl_name} // {};

        if ($info->{is_array_of_objects}) {
            my $inner_class = $info->{class};
            $args{$attr} = [ map { $self->struct_to_object($inner_class, $_) } @$value ];
        } elsif ($info->{is_hash_of_objects}) {
            my $inner_class = $info->{class};
            $args{$attr} = { map { $_ => $self->struct_to_object($inner_class, $value->{$_}) } keys %$value };
        } elsif ($info->{is_object}) {
            $args{$attr} = $self->struct_to_object($info->{class}, $value);
        } elsif ($info->{is_bool}) {
            $args{$attr} = (ref($value) eq '' && lc($value) eq 'true') || $value ? 1 : 0;
        } else {
            $args{$attr} = $value;
        }
    }

    return \%args;
}

sub object_to_struct {
    my ($self, $object) = @_;
    return $object->TO_JSON;
}

sub object_to_json {
    my ($self, $object) = @_;
    return $object->to_json;
}

sub load {
    my ($self, $file) = @_;

    require IO::K8s::Manifest;

    # Set k8s instance for DSL functions
    local $IO::K8s::Manifest::_k8s_instance = $self;

    return IO::K8s::Manifest->_load_file($file, $self);
}

sub load_yaml {
    my ($self, $file_or_string, %opts) = @_;

    require YAML::PP;

    my $content;
    if ($file_or_string !~ /\n/ && -f $file_or_string) {
        # It's a file path
        open my $fh, '<', $file_or_string or die "Cannot open $file_or_string: $!";
        $content = do { local $/; <$fh> };
        close $fh;
    } else {
        # It's YAML content
        $content = $file_or_string;
    }

    # Parse multi-document YAML (Load returns all docs in list context)
    my @docs = YAML::PP::Load($content);

    my $collect_errors = $opts{collect_errors};
    my @objects;
    my @errors;

    # Inflate each document - this validates types!
    for my $i (0 .. $#docs) {
        my $doc = $docs[$i];
        next unless $doc && ref($doc) eq 'HASH';

        if ($collect_errors) {
            eval { push @objects, $self->inflate($doc) };
            if ($@) {
                my $name = $doc->{metadata}{name} // "document $i";
                my $kind = $doc->{kind} // 'unknown';
                push @errors, "$kind/$name: $@";
            }
        } else {
            push @objects, $self->inflate($doc);
        }
    }

    # In collect_errors mode, return (objects, errors) in list context
    if ($collect_errors) {
        return (\@objects, \@errors);
    }

    return \@objects;
}

1;

__END__