length results from the CPAN

length

API-Docker

view release on metacpan or search on metacpan

t/containers_endpoints.t view on Meta::CPAN

#!/usr/bin/env perl
use strict;
use warnings;
use Test::More;
use FindBin;
use lib "$FindBin::Bin/lib";
use Test::API::Docker::Mock;
use JSON::MaybeXS qw( encode_json );
use MIME::Base64 qw( encode_base64 );
use API::Docker;

# The container endpoints this client did not expose:
#
#   karr k18  GET/PUT/HEAD /containers/{id}/archive  -- what docker cp is
#   karr k19  POST /containers/{id}/attach           -- the one-way variant
#   karr k23  changes, export, resize
#
# Measured against the rootless Podman socket (5.4.2, API 1.41): all five
# routes are served there. A nonexistent container answers 404 on archive,
# export, resize and attach -- and 500 with "layer not known" on changes,
# which is why changes documents that difference.
#
# karr k36 closed the remaining gap: the bytes of a real archive, a real
# attach stream, and the X-Docker-Container-Path-Stat header are now captured
# from apidocker-fixture-* containers on that same socket rather than assumed.
# See the fixture-loading comments below for what each measurement found.

check_live_access();

# GET /containers/{id}/archive?path=/etc/hostname, captured from a running
# apidocker-fixture-archive container on Podman 5.4.2 (API 1.41) -- karr k36
# replaced the hand-built ustar that stood in here before. Measured
# differences from the hand-built version: uname/gname were populated
# ('root'/'root', not empty) on that 5.4.2 socket, devmajor/devminor are the
# ASCII string '0000000' rather than left as raw NUL bytes, and mode reflects
# the file's real permissions (0644, not the guessed 0664). Block size (512),
# the two trailing all-zero blocks that end the archive, the ustar
# magic/version, and the empty prefix field were already right in the
# hand-built one.
#
# karr k62 re-measured the same archive live on Podman 5.8.4 (API 1.44):
# uname/gname now come back NUL rather than 'root', byte-identical to a
# Docker 29.7.2 capture of the same file -- Podman changed to match Docker
# here, so this is no longer a difference between the two engines. The
# fixture below is kept as the 5.4.2 capture rather than recaptured: nothing
# in this file asserts uname/gname (only length, the ustar magic, the member
# name and byte-exact roundtrip through the transport are checked), so the
# 5.4.2 bytes still exercise exactly what this file tests.
my $TAR = load_fixture_raw('containers_archive.tar');

# The one-way attach stream is byte-identical to the logs stream, which is the
# whole claim of karr k19 -- and now measured, not just documented: karr k36
# attached live to an apidocker-fixture-attach-live container across its run
# (POST .../attach?stream=1&stdout=1&stderr=1, connected before the container
# started so the daemon had output to send) and diffed the bytes against
# GET .../logs?stdout=1&stderr=1 on an equivalent run; both came back as this
# same 24-byte frame pair, byte for byte. This is the captured logs fixture
# rather than a second file holding the same bytes: it is real engine output,
# and a copy made by hand would only look like one.
#
# A related hazard the measurement also turned up: attaching with stream=1 to
# a container that has *already* exited still sends the same 24 bytes, but
# Podman never closes the connection afterward -- no Content-Length, no
# chunked encoding, and no close even when the client sends Connection: close
# itself, which _request always does. Reading blocks until EOF, so that call
# hangs forever.
#
# karr k52 narrowed that down: it is stream=1 that hangs, not attach as such.
# Re-measured on Podman 5.4.2 (API 1.41) against one exited container:
# ?logs=1&stdout=1&stderr=1&stream=0 answers 200, sends the 24 bytes and
# closes after 13ms; the same request with stream=1 sends the identical bytes
# and hangs; with Upgrade: tcp it answers 101 UPGRADED and hangs the same
# way; and stream=1 against a container still *running*, which exits three
# seconds later, closes cleanly after 3s. The spec explains it -- stream is
# "from the time the request was made onwards" and its only terminator is the
# container ending, which for a stopped container already happened. So this
# client now follows the engine's own default of stream=0 and defaults logs=1
# instead. Docker was unverified when this was written; it has since been
# measured (29.7.2, API 1.55) and hangs identically, so the hang is not a
# Podman quirk but behaviour the reference leaves unspecified for both.
#
# The live subtests below still never call attach: the transport buffers, and
# an explicit stream => 1 is still a hang waiting to happen.
my $FRAMES = load_fixture_raw('containers_logs_multiplexed.bin');

# X-Docker-Container-Path-Stat for /etc/hostname, decoded from a real header
# captured alongside the archive above (karr k36) -- against the Podman
# socket, so this models Podman's shape specifically, not "the" shape. A
# later side-by-side against a real Docker daemon (29.7.2, API 1.55) on the
# same file confirmed what had only been a guess here: Podman's key names
# match the Docker Engine API reference for five of them (name, size, mode,
# mtime, linkTarget); the sixth, isDir, is Podman's own addition -- Docker
# never sends it, not even for a directory. Two more measured differences
# from Docker: linkTarget is populated here even for a plain regular file
# (Podman echoes the resolved path rather than leaving it empty, which is
# what Docker does), and mode is Go's os.FileMode, not a POSIX stat.st_mode
# word -- for this regular file the two are numerically identical (0644, no
# type bits), but they diverge for a directory. See the live subtest below
# for the Docker-side numbers next to these, and for the case that tells
# FileMode and st_mode apart.
my %STAT = (
  # Podman's answer for /etc/hostname. Docker's answer for the same file
  # omits isDir and reports linkTarget as '' rather than the resolved path;
  # see the live subtest below.
  name       => 'hostname',
  size       => 13,
  mode       => 420,
  mtime      => '2026-08-27T15:36:51.589296398Z',
  linkTarget => '/etc/hostname',
);
my $STAT_HEADER = encode_base64(encode_json(\%STAT), '');

# ---------------------------------------------------------------------------
# A client whose socket is an in-memory sink and whose response is canned, so
# the real _request runs -- and with it raw => 1, raw_body, the query string
# and the verb. Same pattern as t/images_tar.t and t/streaming_shape.t; the
# mock harness replaces _request wholesale and can reach none of it.
package Test::ContainersEndpoints::FakeTransport;
use Moo;
extends 'API::Docker';

has canned => (is => 'rw', default => sub { [200, 'OK', {}, ''] });
has _sink  => (is => 'rw');

sub _build__socket {
  my ($self) = @_;
  my $sink = '';
  $self->_sink(\$sink);
  open my $fh, '>', \$sink or die "open: $!";
  binmode $fh;
  return $fh;
}

sub _read_response { return $_[0]->canned }

sub written { return ${ $_[0]->_sink } }

sub request_line {
  my ($line) = $_[0]->written =~ /\A([^\r\n]+)\r\n/;
  return $line;
}

sub request_body {
  my ($body) = $_[0]->written =~ /\r\n\r\n(.*)\z/s;
  return $body;
}

package main;

sub fake_client {
  return Test::ContainersEndpoints::FakeTransport->new(
    host        => 'unix:///nonexistent.sock',
    api_version => '1.41',
  );
}

# ---------------------------------------------------------------------------
subtest 'the tar fixture really is a tar, so byte-exactness means something' => sub {
  is length($TAR) % 512, 0, 'a whole number of 512-byte blocks';
  is substr($TAR, 257, 5), 'ustar', 'ustar magic in the header block';
  is unpack('Z100', $TAR), 'hostname', 'one member, named after the basename';
  like $TAR, qr/\0/, 'carries NUL bytes -- it is not text';
};

# ===========================================================================
# karr k18 -- the archive endpoints
# ===========================================================================

subtest 'get_archive: asks for raw bytes and hands them back untouched' => sub {
  plan skip_all => 'route assertions are fixture-only' if is_live();

  my %seen;
  my $docker = test_docker(
    'GET /containers/deadbeef/archive' => sub {
      my ($method, $path, %opts) = @_;
      %seen = %opts;
      return $TAR;
    },
  );

  my $out = $docker->containers->get_archive('deadbeef', path => '/etc/hostname');

  ok $seen{raw}, 'the request asked the transport for raw bytes';
  ok !$seen{ndjson}, 'and not for a decoded event stream';
  is_deeply $seen{params}, { path => '/etc/hostname' },
    'path is the only query parameter';
  is $out, $TAR, 'the daemon bytes come back verbatim';
  is length($out), length($TAR), 'no truncation';
};

subtest 'get_archive: raw bytes survive the real _request' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', { 'content-type' => 'application/x-tar' }, $TAR]);

  my $out = $t->containers->get_archive('deadbeef', path => '/var/log/app.log');

  is $out, $TAR, 'byte-exact through _request';
  is $t->request_line,
    'GET /v1.41/containers/deadbeef/archive?path=/var/log/app.log HTTP/1.1',
    'GET on the versioned path, the path parameter keeping its slashes';
};

subtest 'get_archive: a body that looks like JSON is still not decoded' => sub {
  # The transport tries decode_json on any body starting with { or [ unless
  # raw is set. A tar cannot start that way, but the guarantee is "never
  # decoded", not "never decodable" -- so assert it directly.
  my $t = fake_client();
  $t->canned([200, 'OK', {}, '{"name":"not really a tar"}']);

  is ref $t->containers->get_archive('deadbeef', path => '/x'), '',
    'a JSON-shaped body comes back as a plain string, not a HashRef';
};

subtest 'get_archive: the stat out-parameter decodes the header' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK',
    { 'x-docker-container-path-stat' => $STAT_HEADER }, $TAR]);

  my %stat;
  my $out = $t->containers->get_archive('deadbeef',
    path => '/etc/hostname', stat => \%stat);

  is $out, $TAR, 'the return value is still the archive, not the stat';
  is_deeply \%stat, \%STAT,
    'the base64 JSON header is decoded, not handed over as base64';

  # The engine sends the header on this response too, so a caller wanting
  # both does not have to pay for the HEAD as well.
  my $t2 = fake_client();
  $t2->canned([200, 'OK', {}, $TAR]);
  my %empty = ( leftover => 1 );
  $t2->containers->get_archive('deadbeef', path => '/x', stat => \%empty);
  is_deeply \%empty, {}, 'emptied when the engine sent no such header';

  my $err = do { local $@; eval {
    $t->containers->get_archive('deadbeef', path => '/x', stat => 'nope') }; $@ };
  like $err, qr/stat option must be a HashRef/, 'a non-HashRef stat croaks';
};

subtest 'get_archive: the required arguments are required' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', {}, $TAR]);

  my $no_id = do { local $@; eval { $t->containers->get_archive }; $@ };
  like $no_id, qr/Container ID required/, 'a missing id croaks';

  my $no_path = do { local $@; eval {
    $t->containers->get_archive('deadbeef') }; $@ };
  like $no_path, qr/Path required/, 'a missing path croaks';

  my $empty = do { local $@; eval {
    $t->containers->get_archive('deadbeef', path => '') }; $@ };
  like $empty, qr/Path required/, 'an empty path croaks rather than reaching the daemon';
};

subtest 'put_archive: the tar is the request body, the options are the query' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', {}, '']);

  my $out = $t->containers->put_archive('deadbeef', $TAR, path => '/opt/app');

  is $out, undef, 'a success carries no body, so there is nothing to return';
  is $t->request_line, 'PUT /v1.41/containers/deadbeef/archive?path=/opt/app HTTP/1.1',
    'PUT on the archive path';
  like $t->written, qr{Content-Type: application/x-tar\r\n}, 'sent as a tar';
  like $t->written, qr{Content-Length: @{[ length $TAR ]}\r\n}, 'the whole archive';
  is $t->request_body, $TAR, 'the request body is the archive byte for byte';
};

subtest 'put_archive: noOverwriteDirNonDir and copyUIDGID' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', {}, '']);

  $t->containers->put_archive('deadbeef', $TAR,
    path => '/opt/app', noOverwriteDirNonDir => 1, copyUIDGID => 1);
  is $t->request_line,
    'PUT /v1.41/containers/deadbeef/archive?copyUIDGID=1&noOverwriteDirNonDir=1&path=/opt/app HTTP/1.1',
    'both flags on the wire as 1';

  $t->containers->put_archive('deadbeef', $TAR,
    path => '/opt/app', noOverwriteDirNonDir => 0, copyUIDGID => 0);
  is $t->request_line,
    'PUT /v1.41/containers/deadbeef/archive?copyUIDGID=0&noOverwriteDirNonDir=0&path=/opt/app HTTP/1.1',
    'a false flag is sent as 0, not dropped -- the engine reads absence as false too, '
    . 'but a caller that passed it explicitly gets it sent';

  $t->containers->put_archive('deadbeef', $TAR, path => '/opt/app');
  is $t->request_line, 'PUT /v1.41/containers/deadbeef/archive?path=/opt/app HTTP/1.1',
    'neither appears when neither was asked for';
};

subtest 'put_archive: takes a scalar ref, and requires what it requires' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', {}, '']);

  $t->containers->put_archive('deadbeef', \$TAR, path => '/opt/app');
  is $t->request_body, $TAR, 'dereferenced, not stringified';

  my $no_tar = do { local $@; eval {
    $t->containers->put_archive('deadbeef', undef, path => '/opt/app') }; $@ };
  like $no_tar, qr/Tar archive required/, 'a missing archive croaks';

  my $no_path = do { local $@; eval {
    $t->containers->put_archive('deadbeef', $TAR) }; $@ };
  like $no_path, qr/Path required/, 'a missing path croaks';

  my $no_id = do { local $@; eval { $t->containers->put_archive }; $@ };
  like $no_id, qr/Container ID required/, 'a missing id croaks';
};

subtest 'stat_archive: HEAD, and the payload comes out of the header' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', { 'x-docker-container-path-stat' => $STAT_HEADER }, '']);

  my $stat = $t->containers->stat_archive('deadbeef', path => '/etc/hostname');

  is $t->request_line,
    'HEAD /v1.41/containers/deadbeef/archive?path=/etc/hostname HTTP/1.1',
    'the verb is HEAD, not GET';
  is_deeply $stat, \%STAT, 'the header is decoded into a HashRef';
  is $stat->{mode} & 0777, 0644, 'the permission bits are the low nine of mode';
};

subtest 'stat_archive: the base64 alphabet is read tolerantly' => sub {
  # Docker encodes this header with Go's base64.StdEncoding. Decoding is done
  # with the URL-safe characters translated back first, so an engine that

t/containers_endpoints.t view on Meta::CPAN

  is $inspected->TO_JSON->{State}, 'exited',
    'while the raw value still reaches TO_JSON unchanged';
};

subtest 'attach: an empty stream is an empty ArrayRef' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', {}, '']);
  is_deeply $t->containers->attach('deadbeef', require_running => 0), [],
    'a container that wrote nothing gives no frames, not undef';
};

# ===========================================================================
# karr k23 -- changes, export, resize
# ===========================================================================

subtest 'changes: the diff, and what the Kind numbers are' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', { 'content-type' => 'application/json' },
    '[{"Path":"/etc/hostname","Kind":0},{"Path":"/tmp/new","Kind":1},'
    . '{"Path":"/etc/gone","Kind":2}]']);

  my $changes = $t->containers->changes('deadbeef');

  is $t->request_line, 'GET /v1.41/containers/deadbeef/changes HTTP/1.1',
    'GET on the changes path, no query parameters';
  is ref $changes, 'ARRAY', 'an ArrayRef';
  is scalar @$changes, 3, 'one entry per changed path';
  is_deeply $changes->[0], { Path => '/etc/hostname', Kind => 0 }, '0 is modified';
  is_deeply $changes->[1], { Path => '/tmp/new',      Kind => 1 }, '1 is added';
  is_deeply $changes->[2], { Path => '/etc/gone',     Kind => 2 }, '2 is deleted';

  my $err = do { local $@; eval { $t->containers->changes }; $@ };
  like $err, qr/Container ID required/, 'a missing id croaks';
};

subtest 'changes: a container with nothing changed is an empty ArrayRef' => sub {
  # The engine answers that case with a JSON null. The transport decodes any
  # JSON body, scalars included (karr k30), so a null body reaches this
  # method as undef -- which a caller iterating the result would dereference
  # and die on just the same.
  my $t = fake_client();
  $t->canned([200, 'OK', { 'content-type' => 'application/json' }, 'null']);

  is_deeply $t->containers->changes('deadbeef'), [],
    'a null body is normalised to an empty ArrayRef, not left as undef';

  $t->canned([204, 'No Content', {}, '']);
  is_deeply $t->containers->changes('deadbeef'), [],
    'and so is an empty body';
};

subtest 'export: raw tar bytes, never decoded' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', { 'content-type' => 'application/x-tar' }, $TAR]);

  my $out = $t->containers->export('deadbeef');

  is $t->request_line, 'GET /v1.41/containers/deadbeef/export HTTP/1.1',
    'GET on the export path';
  is $out, $TAR, 'byte-exact';
  is length($out), length($TAR), 'no truncation';

  $t->canned([200, 'OK', {}, '{"Id":"not really a tar"}']);
  is ref $t->containers->export('deadbeef'), '',
    'a JSON-shaped body is not decoded either';

  my $err = do { local $@; eval { $t->containers->export }; $@ };
  like $err, qr/Container ID required/, 'a missing id croaks';
};

subtest 'resize: form-identical to the one Exec already had' => sub {
  my $t = fake_client();
  $t->canned([200, 'OK', {}, '']);

  $t->containers->resize('deadbeef', h => 40, w => 120);
  is $t->request_line, 'POST /v1.41/containers/deadbeef/resize?h=40&w=120 HTTP/1.1',
    'w and h as query parameters on a POST with no body';
  is $t->request_body, '', 'no request body';

  $t->exec->resize('deadbeef', h => 40, w => 120);
  is $t->request_line, 'POST /v1.41/exec/deadbeef/resize?h=40&w=120 HTTP/1.1',
    'the exec one spells the query identically -- the two classes no longer '
    . 'disagree about the same capability';

  $t->containers->resize('deadbeef', w => 80);
  is $t->request_line, 'POST /v1.41/containers/deadbeef/resize?w=80 HTTP/1.1',
    'an option that was not given is not sent, as in Exec::resize';

  my $err = do { local $@; eval { $t->containers->resize }; $@ };
  like $err, qr/Container ID required/, 'a missing id croaks';
};

# ===========================================================================
# The entity forwards
# ===========================================================================

subtest 'the container entity forwards all six' => sub {
  plan skip_all => 'route assertions are fixture-only' if is_live();

  my %seen;
  my $docker = test_docker(
    'GET /containers/json' => [ { Id => 'deadbeef', Names => ['/c'] } ],
    'GET /containers/deadbeef/archive'  => sub { $seen{get_archive}++;  $TAR },
    'PUT /containers/deadbeef/archive'  => sub { $seen{put_archive}++;  undef },
    'HEAD /containers/deadbeef/archive' => sub {
      $seen{stat_archive}++;
      mock_response(headers => { 'X-Docker-Container-Path-Stat' => $STAT_HEADER });
    },
    'POST /containers/deadbeef/attach'  => sub { $seen{attach}++; $FRAMES },
    # The entity forwards %opts to the API class, so it inherits attach's
    # running-container check along with everything else -- which is why a
    # forwarding test needs the endpoint that check asks for.
    'GET /containers/deadbeef/json'     => { State => { Running => 1 } },
    'GET /containers/deadbeef/changes'  => sub { $seen{changes}++; [] },
    'GET /containers/deadbeef/export'   => sub { $seen{export}++;  $TAR },
    'POST /containers/deadbeef/resize'  => sub { $seen{resize}++;  undef },
  );

  # The client must stay in a live variable: entities hold it as a weak_ref.
  my ($container) = @{ $docker->containers->list };
  isa_ok $container, 'API::Docker::Type::ContainerSummary';

t/containers_endpoints.t view on Meta::CPAN

  is ref $changes, 'ARRAY', 'changes returns an ArrayRef';
  for my $change (@$changes) {
    ok defined $change->{Path}, 'each entry has a Path';
    like $change->{Kind}, qr/\A[012]\z/, 'and a Kind of 0, 1 or 2';
  }

  my $engine = live_engine();

  my $stat = $docker->containers->stat_archive($container->id,
    path => '/etc/hostname');
  ok defined $stat, 'stat_archive found /etc/hostname';
  is ref $stat, 'HASH', 'and decoded the header into a HashRef';

  # What both engines agree on for a plain regular file: name is the
  # basename and the low nine bits of mode are the POSIX permission bits.
  is $stat->{name}, 'hostname', 'name is the basename, not the full path';
  is $stat->{mode} & 0777, 0644, 'the permission bits are the low nine of mode';

  # The key set and isDir/linkTarget do not: side-by-side measurement against
  # both engines (karr k36, later re-verified against a real Docker daemon --
  # 29.7.2, API 1.55 -- next to Podman 5.4.2, API 1.41, same container, same
  # file) found isDir is Podman's own addition, confirmed rather than
  # guessed: Docker never sends it, not even for a directory. linkTarget
  # differs too -- Docker leaves it empty for a plain file, matching the
  # Docker Engine API reference; Podman echoes the resolved path instead.
  if ($engine eq 'podman') {
    is_deeply [ sort keys %$stat ], [qw( isDir linkTarget mode mtime name size )],
      'Podman: six keys, isDir alongside the five the reference documents';
    is $stat->{linkTarget}, '/etc/hostname',
      'Podman: linkTarget is populated even for a plain regular file -- it '
      . 'echoes the resolved path here rather than leaving it empty';
    ok !$stat->{isDir}, 'Podman: /etc/hostname is not a directory';
  }
  else {
    is_deeply [ sort keys %$stat ], [qw( linkTarget mode mtime name size )],
      'Docker: exactly the five keys the Engine API reference documents, no isDir';
    is $stat->{linkTarget}, '',
      'Docker: linkTarget is left empty for a plain regular file';
    ok !exists $stat->{isDir}, 'Docker: isDir is absent, not merely false';
  }

  # mode itself is Go's os.FileMode, not a POSIX stat.st_mode word -- for a
  # regular file the two coincide (no type bits set), so the check above does
  # not by itself tell them apart. A directory does, on both engines: Go sets
  # os.ModeDir (1<<31) above the permission bits, where POSIX would set
  # S_IFDIR (0040000) at an entirely different position.
  my $dir_stat = $docker->containers->stat_archive($container->id, path => '/etc');
  ok $dir_stat->{mode} & (1 << 31),
    'mode carries Go os.ModeDir above the permission bits -- proof this is '
    . 'FileMode, not raw POSIX stat.st_mode, which never sets that bit';

  if ($engine eq 'podman') {
    ok $dir_stat->{isDir}, 'Podman: /etc is a directory';
  }
  else {
    ok !exists $dir_stat->{isDir}, 'Docker: isDir is absent for a directory too';
  }

  my $tar = $docker->containers->get_archive($container->id,
    path => '/etc/hostname');
  ok defined $tar && length $tar, 'get_archive returned bytes';
  is length($tar) % 512, 0, 'a whole number of tar blocks';
  is substr($tar, 257, 5), 'ustar', 'ustar magic';
  is unpack('Z100', $tar), 'hostname', 'the member is the basename';
};

subtest 'live write: stat_archive on a symlink diverges by engine (karr k36)' => sub {
  plan skip_all => 'live only'       unless is_live();
  plan skip_all => 'write tests off' unless can_write();

  my $docker = test_docker();
  my ($base) = grep { $_->repo_tags && @{ $_->repo_tags } } @{ $docker->images->list };
  plan skip_all => 'no tagged image to base a container on' unless $base;

  # A container of our own: the read-only subtest above cannot pick a symlink
  # off whatever container happens to already exist, so this one creates it,
  # names it apidocker-stat- as agreed, and removes it again below.
  my $created = $docker->containers->create(
    Image => $base->repo_tags->[0],
    Cmd   => [ '/bin/sh', '-c', 'ln -s /etc/hostname /tmp/hnlink' ],
    name  => 'apidocker-stat-symlink-' . $$,
  );
  my $id = $created->{Id};
  register_cleanup(sub { eval { $docker->containers->remove($id, force => 1) } });

  $docker->containers->start($id);
  $docker->containers->wait($id);

  my $stat = $docker->containers->stat_archive($id, path => '/tmp/hnlink');
  ok defined $stat, 'stat_archive found the symlink';

  # Measured for /tmp/hnlink -> /etc/hostname: both engines agree on
  # linkTarget (the resolved target path) and on mode (Go's ModeSymlink,
  # 1<<27, plus the symlink's own 0777) -- but not on name. Docker reports
  # the link itself; Podman resolves through it and reports the target's
  # basename instead.
  is $stat->{linkTarget}, '/etc/hostname',
    'both engines resolve linkTarget to the symlink\'s destination';
  ok $stat->{mode} & (1 << 27),
    'mode carries Go ModeSymlink above the permission bits on both engines';
  is $stat->{mode} & 0777, 0777, 'a symlink\'s own permission bits are 0777 on both';

  my $engine = live_engine();
  if ($engine eq 'podman') {
    is $stat->{name}, 'hostname',
      'Podman fully resolves the symlink -- name is the target\'s basename, not the link\'s';
  }
  else {
    is $stat->{name}, 'hnlink',
      'Docker reports the link itself -- name is the symlink\'s own basename';
  }
};

done_testing;

( run in 1.437 second using v1.01-cache-2.11-cpan-54e63673c56 )