/ 
Skilletor-0.001
/ Skilletor::Source::Url

NAME

Skilletor::Source::Url - A url source: an https .tar.gz, conditional GET, staged swap into the shared cache

VERSION

version 0.001

SYNOPSIS

use Skilletor::Source::Url;

my $src = Skilletor::Source::Url->new(
  url        => 'https://skills.example.com/skills.tar.gz',
  cache_root => $cache_root,
);
my $loc = $src->resolve;   # { dir, version => 'etag:"abc"' or 'sha256:…', warning? }
my $moved = $src->check( $loc->{version} );

DESCRIPTION

The reference's sources/url.ts (spec §4.4, §9). "resolve" GETs the tarball with the cache's ETag as If-None-Match; a 304 reuses the cache, a 200 is unpacked by Skilletor::Tar into a <hash>.stage-XXXXXX tree next to the cache and swapped in through a <hash>.backup-XXXXXX tree, so a reader never sees half a tree. The cache keeps its version in .skilletor-version (format 2, then the version): the ETag, or the archive's sha256 when the server sends none. A failed download serves the cache with a warning; an unsafe archive is an error, never a fallback.

Requests carry the headers Node's fetch sends (user-agent: node, accept-encoding: gzip, deflate, …) and a compressed response is decoded as fetch decodes it, so a server answers both implementations alike – the same ETag, the same version, the same lock.

url

The tarball's https URL.

cache_root

Where the caches live ("cache_root" in Skilletor::Cache).

timeout_ms

Default 60000. HTTP::Tiny's timeout is per read, not for the whole request.

allow_http

Tests only: permits http://127.0.0.1 and http://localhost.

http

The HTTP::Tiny agent; inject one to stub the network.

cache_dir

This source's cache directory ("url_cache_dir" in Skilletor::Cache).

resolve

{ dir, version, warning? }; see "DESCRIPTION".

cached

{ dir, version } of the cache without a request – what "resolve" serves when its download fails (unknown without a version file), minus the warning (a Perl addition for offline callers). Throws Skilletor::Error::Source when there is no cache.

check

$src->check($cached_version);

A HEAD request: changed unless both the server and $cached_version have an ETag and they are equal.

cache_version

$src->cache_version($dir);

sweep_cache

Skilletor::Source::Url->sweep_cache($cache_root);

CACHE_FORMAT

format 2, the first line of a current version file.

SUPPORT

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.