/ 
IO-K8s-1.110
⭐ Starred 0 / IO::K8s::List

NAME

IO::K8s::List - Generic list container for Kubernetes API responses

VERSION

version 1.110

SYNOPSIS

use IO::K8s::List;

my $list = IO::K8s::List->new(
    items => \@pods,
    metadata => $list_meta,
);

# apiVersion and kind are derived from items
print $list->api_version;  # v1
print $list->kind;         # PodList

DESCRIPTION

Generic container for Kubernetes list responses. Instead of having separate PodList, ServiceList, DeploymentList classes, this single class handles all list types.

The apiVersion and kind are automatically derived from the items.

items

Array of Kubernetes API objects. Required.

metadata

List metadata (IO::K8s::Apimachinery::Pkg::Apis::Meta::V1::ListMeta). Contains pagination info like continue and resourceVersion.

item_class

Optional. The class of items in the list. If not provided, derived from the first item. Used for empty lists where the type can't be inferred, or to override the item type "FROM_STRUCT" would otherwise derive.

Accepted only as a fully-qualified class name, exactly like every other class-name-taking parameter in this distribution: a leading + is stripped before use ("this is already a full class name"), and a short or partially-qualified name is not guessed at -- "kind" and "api_version" simply have nothing to derive from it.

api_version

Returns the Kubernetes API version, derived from items or item_class.

kind

Returns the Kubernetes kind (e.g., "PodList"), derived from items or item_class. For an item_class the Kind is its last :: segment, or the whole name for a single-segment class such as a CRD registered as +Widget -- but only when "api_version" can also resolve for the same item_class; otherwise undef, never a Kind with no apiVersion to go with it.

FROM_STRUCT

my $list = IO::K8s::List->FROM_STRUCT($struct, $k8s);

Inflation hook called by "inflate" in IO::K8s (and so by json_to_object and struct_to_object) whenever the wire kind is List or ends in List -- the shape every real Kubernetes API list response has, and the generic kind: List wrapper besides. Upstream a list response carries no apiVersion/kind on the individual items (the API server omits them there), so the item type is derived from the LIST's own Kind and apiVersion: kind: PodList, apiVersion: v1 means items are v1/Pod.

item_class travels as a sibling key of kind/apiVersion/items in the struct to override the derived type -- the same "use this class, don't derive one" meaning it already has for an empty list built directly via new. It is the only way to inflate a bare kind: List payload, whose Kind minus its List suffix is empty and so derives nothing on its own.

item_class must be a class name. A reference -- plain or blessed, a JSON boolean included -- or an empty class name, '' or a bare +, dies naming this class, the argument and what it received, whether the list has items or not:

IO::K8s::List->FROM_STRUCT: item_class must be a class name, got a reference of type HASH
IO::K8s::List->FROM_STRUCT: item_class must be a class name, got an empty string

An undef item_class is no override: the item type is derived as if the key were absent.

Fails closed: an item Kind that cannot be resolved to a class dies with the same "Cannot resolve Kubernetes GVK" error every other entry point in this distribution uses, naming the ITEM's kind/apiVersion, never a silently empty or half-inflated list.

The wrong shape fails closed in the message form of "new_object" in IO::K8s: a $struct that is not a hash dies naming this class, items that is not an array dies naming the field, the item class and what it received, and an item or metadata that is not a hash dies naming the field -- and for an item its index -- it sits at:

Cannot inflate IO::K8s::List field items: expected an array (a JSON array) of IO::K8s::Api::Core::V1::Pod, got a plain scalar
Cannot inflate IO::K8s::Api::Core::V1::Pod: expected a hash (a JSON object), got a plain scalar while inflating IO::K8s::List field items at element 1

A $struct of undef, and items missing or undef, still give an empty list.

The item_class and shape errors above, and an error an item's constructor raises (a missing required field, a value of the wrong type), name the line that called "inflate" in IO::K8s, FROM_STRUCT or "from_json", not a line inside the distribution.

TO_JSON

my $struct = $list->TO_JSON;

Returns the canonical wire-format hashref for the list: apiVersion and kind when "api_version" and "kind" can derive them, plus an items array of each entry's own TO_JSON (untouched when an item is not a blessed object with a TO_JSON method) and metadata when set. This is the inverse of "FROM_STRUCT" and the input "to_json" runs through its JSON encoder.

to_json

my $json_bytes = $list->to_json;

Serializes the List to a canonical JSON document as a UTF-8 encoded byte string -- the same convention every IO::K8s::Role::Resource class uses, and the input "from_json" reads back.

from_json

my $list = IO::K8s::List->from_json($json_bytes);
my $list = IO::K8s::List->from_json($json_bytes, $k8s);

Builds a List from a JSON document, symmetric to "to_json". The argument is a UTF-8 encoded byte string -- exactly what to_json emits -- and is decoded and handed to "FROM_STRUCT", so the items inflate to typed objects the same way "inflate" in IO::K8s does. Pass an IO::K8s instance as the second argument when the item types must resolve through that instance's providers or class_namespaces; without one a shared default instance is used, as FROM_STRUCT does.

List composes IO::K8s::Role::Resource (since 1.108) so its top-level envelope gets the same _unknown_fields bag and strict handling as every other resource, but it is a container, not an API object with its own GVK, so to_json/from_json/TO_JSON/FROM_STRUCT stay hand-rolled overrides rather than the role's own -- kind/api_version derive from the items, not from a class name. $k8s->inflate reaches the same FROM_STRUCT path from a full wire payload and remains the entry point when the Kind is only known at runtime.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/pplu/io-k8s-p5/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHORS

  • Torsten Raudssus <getty@cpan.org>

  • Jose Luis Martinez Torres <jlmartin@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018-2026 by Jose Luis Martinez Torres <jlmartin@cpan.org>.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004