view release on metacpan or  search on metacpan

lib/API/Docker/API/System.pm  view on Meta::CPAN

  # callback path too, where the check would otherwise run per event.
  #
  # exists, not truth: `on_event => $cb` with an unset $cb is a caller bug,
  # and falling back to the buffered path for it would answer an unbounded
  # feed by hanging. Handed over as it is, the transport says so instead.
  return $self->client->get('/events',
    params         => \%params,
    croak_on_error => 0,
    %{ $self->_request_options },
    exists $opts{on_event} ? ( on_event => $opts{on_event} ) : ( ndjson => 1 ),
  );
}


sub df {
  my ($self) = @_;
  return $self->client->get('/system/df',
    %{ $self->_request_options },
  );
}


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

  # Two spellings of the same AuthConfig. The credential keys and the name
  # `auth` cannot collide -- the engine's AuthConfig has no `auth` field --
  # so both are accepted, but not at once: which one wins would be a silent
  # choice about someone's credentials.
  my @flat = grep { defined $opts{$_} }
    qw( username password email serveraddress identitytoken );
  croak __PACKAGE__ . '->auth takes either auth => $config or the credential '
    . 'keys themselves, not both (' . join(', ', @flat) . ' given beside auth)'
    if defined $opts{auth} && @flat;

  my $config = defined $opts{auth}
    ? $self->_registry_auth_config($opts{auth})
    : { map { $_ => $opts{$_} } @flat };

  # Stricter than the engine, deliberately. An empty AuthConfig is a valid
  # body -- Podman answers it 500 'getting username and password: cannot
  # prompt for username without stdin' -- but a credential check with no
  # credentials in it is a caller bug, and answering it with the engine's
  # message would hide that.
  croak __PACKAGE__ . '->auth requires credentials: pass username/password, '
    . 'identitytoken, or auth => $config' unless keys %$config;

  return $self->client->post('/auth', $config,
    %{ $self->_request_options },
    (exists $opts{response} ? (response => $opts{response}) : ()));
}



1;

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 0.004

=head1 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

=head1 DESCRIPTION

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

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

=head2 client

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

=head2 info

    my $info = $system->info;

Get system-wide information about the Docker daemon.

Returns hashref with keys including: