/ 
API-Docker-0.004
/ API::Docker::API::System

NAME

API::Docker::API::System - Docker Engine System API

VERSION

version 0.004

SYNOPSIS

my $docker = API::Docker->new;

# System information
my $info = $docker->system->info;
say "Docker version: " . $info->{ServerVersion};

# API version
my $version = $docker->system->version;
say "API version: " . $version->{ApiVersion};

# Health check
my $pong = $docker->system->ping;

# Monitor events
my $events = $docker->system->events(
    since => time() - 3600,
);

# Disk usage
my $df = $docker->system->df;

# Check registry credentials before doing the work that needs them
my $login = $docker->system->auth(
    username      => 'me',
    password      => 'secret',
    serveraddress => 'ghcr.io',
);
say $login->{Status};   # Login Succeeded

DESCRIPTION

This module provides access to Docker system-level operations including daemon information, version detection, health checks, and event monitoring.

Accessed via $docker->system, or through "using" in API::Docker::Role::Using for a run of calls that needs its own transport bound: $docker->system->using(read_timeout => 5).

client

Reference to API::Docker client. Weak reference to avoid circular dependencies.

info

my $info = $system->info;

Get system-wide information about the Docker daemon.

Returns hashref with keys including:

  • ServerVersion - Docker version

  • Containers - Total number of containers

  • Images - Total number of images

  • Driver - Storage driver

  • MemTotal - Total memory

version

my $version = $system->version;

Get version information about the Docker daemon and API.

Returns hashref with keys including ApiVersion, Version, GitCommit, GoVersion, Os, and Arch.

ping

my $pong = $system->ping;

Health check endpoint. Returns OK string if daemon is responsive.

events

my $events = $system->events(
    since   => 1234567890,
    until   => 1234567900,
    filters => { type => ['container'] },
);

Get events from the Docker daemon. Returns an ArrayRef of events, one per object in the engine's newline-delimited JSON stream, even when the stream carried a single object.

Unlike $docker->images->build, pull and push, this method never croaks on the content of the stream. Those report the outcome of one operation, so an errorDetail object in their stream means that operation failed; /events is a feed, and an object in it is a record of something that happened on the engine, never a failure of this call. Only transport and HTTP errors croak here.

Bound the window with until, or pass on_event. Without a callback the transport buffers the whole response before parsing, so an unbounded call blocks until the daemon closes the connection, which for a live event stream is never.

Options:

  • since - Show events created since this timestamp

  • until - Show events created before this timestamp

  • filters - HashRef of filter name to ArrayRef of string values, e.g. { type => ['container', 'image'] }. Shape-checked and normalised by API::Docker::Role::Filters; the daemon validates the names here, so a misspelt one is a failed request rather than a quiet no-match

  • on_event - CodeRef called with each event as it arrives, instead of the ArrayRef being collected and returned; see below

Following the feed

An unbounded /events is the endpoint this client could not use at all. Pass on_event and the events are handed over one at a time as the daemon sends them:

my $summary = $system->events(
    since    => time - 60,
    on_event => sub {
        my ($event, $stop) = @_;
        say $event->{status};
        $stop->() if $event->{status} eq 'destroy';
    },
);

$summary;   # { delivered => 12, stopped => 1 }

With a callback the return value is that summary HashRef, not the events: delivered is how many went to the callback, stopped is 1 when the callback ended the feed and 0 when the daemon did. Nothing is accumulated -- a feed that runs for a day must not cost memory in proportion to how long it ran, and the callback has been handed every event already. See "Streaming a response as it arrives" in API::Docker::Role::HTTP.

Measured against the rootless Podman socket (5.4.2, API 1.41): with since and no until, this returned in 0.3 seconds as soon as the callback said stop, where the same call without one was still running when it was killed after 22 seconds.

The callback never croaks on the content of the feed either: croak_on_error is off here on both paths, for the reason above.

df

my $usage = $system->df;

Get data usage information (disk usage by images, containers, and volumes).

Returns hashref with LayersSize, Images, Containers, and Volumes arrays.

auth

my $login = $system->auth(
    username      => 'me',
    password      => 'secret',
    serveraddress => 'ghcr.io',
);

# Or hand over the same auth argument images->push takes
$system->auth(auth => $auth);

Check a set of registry credentials against the registry, without pulling or pushing anything. Returns the decoded POST /auth response, a HashRef with Status (Login Succeeded) and, where the registry issues one, IdentityToken.

Bad credentials croak. The engine answers a failed check with an error status, and the transport croaks on any status at or above 400, so a successful return is the answer -- there is no false value to test. That is what makes this useful as a pre-flight check: call it before building and tagging an image, and a stale credential fails the run where it is cheap rather than halfway through a push.

To tell one failure from another, eval and read the status:

my %res;
eval { $docker->system->auth(auth => $auth, response => \%res); 1 }
  or do {
    die "registry rejected the credentials" if $res{status} == 401;
    die "could not reach the registry: $@";
  };

Options -- the AuthConfig keys the engine defines, all optional individually, but at least one is required:

  • username - Registry account name

  • password - Its password or token

  • email - Legacy field, accepted and ignored by current registries

  • serveraddress - Registry to check against, e.g. ghcr.io. Omitted, the engine uses its default registry

  • identitytoken - Bearer token, instead of username and password

  • auth - The whole AuthConfig at once, in any shape "push" in API::Docker::API::Images accepts it: a HashRef, a JSON object, or a base64url-encoded one. Cannot be combined with the keys above

  • response - HashRef the status line and the response headers are written into, as for "get" in API::Docker::Role::HTTP

Passing neither auth nor any credential key croaks before the request is made.

What Podman answers

Measured against the rootless Podman socket (5.4.2, API 1.41): the endpoint exists, but a failed check is 500 Internal Server Error, not Docker's 401, and the message is the registry's own text wrapped by Podman -- {"message":"login attempt to 127.0.0.1:1 failed with status: ..."}. An empty AuthConfig answers {"message":"login attempt to failed with status: getting username and password: cannot prompt for username without stdin"}, also 500. So the croak is reliable on both engines while the status behind it is not: test the outcome, not the number.

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.