/ 
API-Docker-0.004
/ API::Docker::Role::Entity::Config

NAME

API::Docker::Role::Entity::Config - Config operations, on the generated config type

VERSION

version 0.004

SYNOPSIS

my $docker = API::Docker->new;
my ($config) = @{ $docker->configs->list };

say $config->id;
say $config->spec->name;
say $config->spec->data;        # still base64, as the daemon sent it
say $config->decoded_data;      # the bytes

my %spec = %{ $config->spec->TO_JSON };
delete $spec{Data};             # already base64 -- see update
$spec{Labels} = { app => 'web' };
$config->update(%spec);

$config->remove;

DESCRIPTION

The convenience methods of a Docker config. This role is composed, at load time, into API::Docker::Type::Config, the generated class the daemon answers config requests with -- the same definition for GET /configs and GET /configs/{id}, so "list" in API::Docker::API::Configs and "inspect" in API::Docker::API::Configs hand back one class and there is no list-versus-inspect shape to keep apart.

A config is a secret whose value can be read back: the daemon returns it in spec->data as base64, where a secret returns no payload at all -- "There is no accessor for the value" in API::Docker::Role::Entity::Secret. "decoded_data" is the accessor for it.

Decoding is offered here, not in the API class

API::Docker::API::Configs hands back the daemon's response with nothing rewritten, which is the rule the whole distribution follows -- so $config->spec->data is the base64 string the engine sent, unchanged, and stays that way. "decoded_data" does not touch it either: it decodes on demand and returns the bytes, leaving the spec verbatim for anyone who wants to compare it against the wire or hand it back.

That is the whole reason the accessor belongs on the entity rather than on the API class: an entity may offer a derived view of a response, an API method may not silently replace one.

The spec goes back as a whole

$config->spec is an API::Docker::Type::ConfigSpec object rather than the raw HashRef the hand-written entity kept, so the idiom for an update is %{ $config->spec->TO_JSON }: TO_JSON renders the spec back into the daemon's own spelling, which is what "update" puts in the request body. Mind the Data it brings with it -- see "update".

Why the methods are a role applied to a generated class rather than a class of their own: "DESCRIPTION" in API::Docker::Role::Entity.

decoded_data

my $text = $config->decoded_data;

The config's content: $config->spec->data run through "decode_base64" in MIME::Base64. Returns nothing when the object carries no Spec or no Data in it.

The result is raw bytes, symmetric with what "create" in API::Docker::API::Configs takes -- decode the character set yourself if the config holds text above U+007F, for instance with Encode::decode_utf8.

The spec is left alone; see "Decoding is offered here, not in the API class".

version_index

my $index = $config->version_index;

The ->index out of ->version, which is what the daemon wants as the version query parameter on an update. Returns nothing when the object carries no Version -- including the case where the daemon sent one the model could not use, which leaves the attribute unset and the raw value in ->unknown_fields->{Version}.

It is the version as of the moment this object was fetched, which is exactly the token's meaning: an update built on a stale entity is refused by the daemon rather than silently overwriting whatever changed in between.

inspect

my $fresh = $config->inspect;

Get fresh config information. Returns another API::Docker::Type::Config -- the same class, since the daemon describes a config one way.

update

my %spec = %{ $config->spec->TO_JSON };
delete $spec{Data};                 # already base64 -- see below
$spec{Labels} = { app => 'web' };
$config->update(%spec);

Update the config. Passes ->id and, by default, "version_index" to "update" in API::Docker::API::Configs; everything else is the spec and becomes the request body.

The default is only a default. A version key in the arguments is used verbatim and removed before the spec goes out -- the spec's own fields are all capitalised (Name, Labels, Data, ...), so a lowercase version cannot collide with one:

$config->update(version => $index, %spec);

A Data passed here is raw bytes and gets encoded on the way out, so the Data that $config->spec->TO_JSON brings along -- already base64 -- would be encoded a second time. Drop it, or pass "decoded_data" in its place.

remove

$config->remove;

Remove the config. The daemon answers 204 with no body, so this returns nothing.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-api-docker/issues.

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.