/ 
DarkPAN-Resolver-SQLite-1.0.2
/ DarkPAN::Resolver::SQLite

NAME

DarkPAN::Resolver::SQLite - a cpm resolver for multi-version DarkPAN indexes

SYNOPSIS

# install the latest version from your DarkPAN
cpm install \
  --resolver +DarkPAN::Resolver::SQLite,https://cpan.openbedrock.net/orepan2 \
  Amazon::API

# install a specific historical version
cpm install \
  --resolver +DarkPAN::Resolver::SQLite,https://cpan.openbedrock.net/orepan2 \
  Amazon::API@2.6.0

# or a range
cpm install \
  --resolver +DarkPAN::Resolver::SQLite,https://cpan.openbedrock.net/orepan2 \
  'Amazon::API~">= 2.0.0, < 3.0.0"'

DESCRIPTION

DarkPAN::Resolver::SQLite is a resolver plugin for cpm that resolves distributions from a DarkPAN's multi-version SQLite index (as produced by DarkPAN::Indexer).

A conventional DarkPAN publishes 02packages.details.txt.gz, which records one indexed distribution for each package. A resolver using that index therefore cannot select an older distribution merely because its tarball still exists in the repository.

DarkPAN::Resolver::SQLite instead reads the multi-version index produced by DarkPAN::Indexer, allowing it to select the highest available version that satisfies the requested version constraint.

Because it participates in cpm's ordered resolver cascade, the SQLite resolver composes with cpm's normal CPAN resolvers. Requests the DarkPAN can satisfy are resolved from its multi-version index; requests it cannot satisfy continue to cpm's default resolvers.

By default, adding --resolver does not disable cpm's normal resolvers. Users who specify --no-default-resolvers are responsible for supplying the complete resolver chain themselves.

WHY THIS EXISTS

A standard 02packages index is sufficient when only the current indexed version matters. This resolver exists for DarkPANs that retain multiple historical distributions and need normal Perl version constraints to select among them.

USAGE

Invoke it as a custom cpm resolver. cpm prepends App::cpm::Resolver:: to a bare resolver name, so a class outside that namespace must be given with a leading + (take-the-name-verbatim):

--resolver +DarkPAN::Resolver::SQLite,<mirror-url>

<mirror-url> is the public base URL of your DarkPAN (the same URL a browser or cpanm --mirror would use), for example https://cpan.openbedrock.net/orepan2. The resolver fetches the index from <mirror-url>/modules/packages.db.gz.

Only a public HTTP(S) URL is required -- the resolver uses HTTP::Tiny and does not need AWS credentials or S3 access, even for an S3-backed DarkPAN fronted by CloudFront. (HTTPS requires IO::Socket::SSL/Net::SSLeay to be present, as with any HTTP::Tiny https use.)

HOW IT WORKS

On construction the resolver fetches modules/packages.db.gz from the mirror, decompresses it to a temporary file, opens the SQLite database, and uses it only for package lookups.

1. selects all rows for the requested package from the index;
2. keeps only versions that satisfy the request's version range, using cpm's own version semantics (App::cpm::version) so its choices agree with the rest of the cascade;
3. picks the highest satisfying version (compared in Perl -- SQLite's lexical ORDER BY would order 1.10.0 below 1.9.0);
4. reconstructs the fetch URI from the stored distribution path via App::cpm::DistNotation and returns it to cpm.

The temporary database file is removed when the resolver object is destroyed.

METHODS

These implement the cpm resolver contract; you do not normally call them directly.

new

DarkPAN::Resolver::SQLite->new( $ctx, $mirror_url )

Fetches and opens the index. Called by cpm with the context and the argument you supplied after the class name in --resolver.

resolve

$resolver->resolve( $ctx, $task )

Resolves one request. $task carries package and version_range. Returns a resolution hashref (source, distfile, uri, version, package) on success, or { error => ... } if the package or a satisfying version is not found -- allowing the cascade to fall through to the next resolver.

LIMITATIONS

Per-package resolution only: like every cpm resolver, it answers "which version of this package, from where"; it is not a global dependency solver. The version index it reads must be published by DarkPAN::Indexer at modules/packages.db.gz under the mirror. The whole index is fetched on construction (no incremental/conditional fetch); this is negligible for typical index sizes.

The resolver can select only distributions recorded in the published SQLite index. A distribution tarball that exists in the repository but has not been indexed is not visible to the resolver.

SEE ALSO

DarkPAN::Indexer, App::cpm, App::cpm::Resolver::02Packages

AUTHOR

Rob Lauer