CPAN Meta Browser
CPAN Meta Browser is a two-part application for convenient access to metadata for the CPAN (Comprehensive Perl Archive Network). The first part is a refresh
command which will download this metadata and index it into the selected backend database. The second part is a web application which provides search functionality into the indexed database.
/path/to/cpan-meta-browser.pl refresh
hypnotoad /path/to/cpan-meta-browser.pl
The Module Index Search
searches the CPAN packages index, which is the file 02packages.details.txt. This is the canonical mapping of module name to the latest authorized stable release of that module, maintained by PAUSE and used by CPAN installers when given a module to install.
The Permissions Search
searches the PAUSE permissions database, which is the file 06perms.txt. This is the listing of authors that can upload new stable releases of a module and have it indexed, and that can modify the permissions for that module name. The first-come
permission, granted to the first user to upload a module name, has ultimate authority on the name, and can add or remove any other user's permissions. The permission manager
permission can add or remove other co-maint
permissions. The co-maint
permission can only remove their own permission. Note that these module permissions are not hierarchical. An author must have permissions for each individual module name they wish to have indexed.
The Author Search
searches the CPAN authors database, which is the file 00whois.xml. This contains public details of the PAUSE accounts.
Perl v5.20.0 or higher is required. Perl dependencies are listed in cpanfile. They can be installed by running:
cpanm --installdeps .
CPAN Meta Browser is configured by the file cpan-meta-browser.conf in the application home directory. The configuration file is a Perl hash. The hypnotoad
key will be used to configure Hypnotoad if it is used to start the web application.
There are three backends available for CPAN Meta Browser. The backend can be set as backend
in the configuration file, or CPAN_META_BROWSER_BACKEND
in the environment.
The default backend is sqlite
and requires Mojo::SQLite. sqlite_path
may be set to a file path to store the database (must be in a writable directory, defaults to cpan-meta.sqlite in the application home directory).
The pg
backend requires Mojo::Pg and a PostgreSQL server running at least version 9.6, with the pg_trgm
extension. This is usually packaged in the -contrib
package for PostgreSQL and must be installed in the database that will be used:
CREATE EXTENSION pg_trgm;
pg_url
must also be set to a database connection URL in the form postgresql://user:password@host:port/database
.
The redis
backend requires Mojo::Redis and a Redis server running at least version 3.2.0. redis_url
may be set to a database connection URL in the form redis://x:auth@host:port/database
(defaults to redis://localhost:6379/0
).
In addition to the browser interface, CPAN Meta Browser provides an API to the contents of the files it indexes. The endpoints below are relative to the installation path, such as https://cpanmeta.grinnz.com/. All endpoints return JSON, and the module and author parameters are case insensitive and trim surrounding whitespace.
GET /api/v2/packages/:module
GET /api/v2/packages/:module?as_prefix=1
GET /api/v2/packages/:module?as_infix=1
GET /api/v2/packages?module=:module&module=:module
Retrieves details from the CPAN module index for the specified module name. If the as_prefix
option is enabled, details are returned for all module names starting with the specified prefix. If the as_infix
option is enabled, details are returned for all module names containing the specified infix. Multiple module names may be specified as query parameters, but this will disable prefix/infix matching.
# GET /api/v2/packages/Moose
{
"data" : [
{
"module" : "Moose",
"owner" : "STEVAN",
"path" : "E\/ET\/ETHER\/Moose-2.2010.tar.gz",
"uploader" : "ETHER",
"version" : "2.2010"
}
],
"last_updated" : "1519669561"
}
# GET /api/v2/packages/Mojo::UserAgent?as_prefix=1
{
"data" : [
{
"module" : "Mojo::UserAgent",
"owner" : "SRI",
"path" : "S\/SR\/SRI\/Mojolicious-7.69.tar.gz",
"uploader" : "SRI","version":null
},
{
"module" : "Mojo::UserAgent::Cached",
"owner" : "NICOMEN",
"path" : "N\/NI\/NICOMEN\/Mojo-UserAgent-Cached-1.06.tar.gz",
"uploader" : "NICOMEN",
"version" : "1.06"
},
...
{
"module" : "Mojo::UserAgent::Transactor",
"owner" : "SRI",
"path" : "S\/SR\/SRI\/Mojolicious-7.69.tar.gz",
"uploader" : "SRI",
"version" : null
}
],
"last_updated" : "1519669561"
}
# GET /api/v2/packages?module=LWP&module=Mojo
{
"data": [
{
"module": "LWP",
"owner": "OALDERS",
"path": "O/OA/OALDERS/libwww-perl-6.38.tar.gz",
"uploader": "OALDERS",
"version": "6.38"
},
{
"module": "Mojo",
"owner": "SRI",
"path": "S/SR/SRI/Mojolicious-8.14.tar.gz",
"uploader": "SRI",
"version": null
}
],
"last_updated": 1556271962
}
GET /api/v2/perms?author=:author
GET /api/v2/perms?module=:module
GET /api/v2/perms?author=:author&module=:module&as_prefix=1&other_authors=1
GET /api/v2/perms?module=:module&as_infix=1
Retrieves details from the CPAN permissions database for the specified author CPAN ID and/or module name. If the as_prefix
option is enabled, details are returned for all module names starting with the specified prefix. If the as_infix
option is enabled, details are returned for all module names containing the specified infix. If the other_authors
option is enabled, details are returned for all authors with permissions for the matched modules, not just the specified author CPAN ID.
# GET /api/v2/perms?author=LWWWP
{
"data" : [
{
"author" : "LWWWP",
"best_permission" : "f",
"module" : "HTML::Entities",
"owner" : "LWWWP"
},
{
"author" : "LWWWP",
"best_permission" : "c",
"module" : "HTML::FormatMarkdown",
"owner" : "NIGELM"
},
...
{
"author" : "LWWWP",
"best_permission" : "f",
"module" : "WWW::RobotRules",
"owner" : "LWWWP"
}
],
"last_updated" : "1519670202"
}
# GET /api/v2/perms?author=LWWWP&other_authors=1
{
"data" : [
{
"author" : "ETHER",
"best_permission" : "c",
"module" : "HTML::Entities",
"owner" : "LWWWP"
},
{
"author" : "GAAS",
"best_permission" : "c",
"module" : "HTML::Entities",
"owner" : "LWWWP"
},
...
{
"author" : "MSTROUT",
"best_permission" : "c",
"module" : "WWW::RobotRules",
"owner" : "LWWWP"
}
],
"last_updated" : "1519670202"
}
# GET /api/v2/perms?author=LWWWP&module=LWP::UserAgent
{
"data" : [
{
"author" : "LWWWP",
"best_permission" : "f",
"module" : "LWP::UserAgent",
"owner" : "LWWWP"
}
],
"last_updated" : "1519670202"
}
# GET /api/v2/perms?author=LWWWP&module=LWP::UserAgent&other_authors=1
{
"data" : [
{
"author" : "ETHER",
"best_permission" : "c",
"module" : "LWP::UserAgent",
"owner" : "LWWWP"
},
{
"author" : "GAAS",
"best_permission" : "c",
"module" : "LWP::UserAgent",
"owner" : "LWWWP"
},
...
{
"author" : "OALDERS",
"best_permission" : "c",
"module" : "LWP::UserAgent",
"owner" : "LWWWP"
}
],
"last_updated" : "1519670802"
}
# GET /api/v2/perms?module=LWP::UserAgent&as_prefix=1
{
"data" : [
{
"author" : "ETHER",
"best_permission" : "c",
"module" : "LWP::UserAgent",
"owner" : "LWWWP"
},
{
"author" : "GAAS",
"best_permission" : "c",
"module" : "LWP::UserAgent",
"owner" : "LWWWP"
},
...
{
"author" : "SEKIMURA",
"best_permission" : "f",
"module" : "LWP::UserAgent::WithCache",
"owner" : "SEKIMURA"
}
],
"last_updated" : "1519670802"
}
GET /api/v2/authors/:author
GET /api/v2/authors/:author?as_prefix=1
GET /api/v2/authors/:author?as_infix=1
Retrieves details from the CPAN author database for the specified author CPAN ID. If the as_prefix
option is enabled, details are returned for all author CPAN IDs starting with the specified prefix. If the as_infix
option is enabled, details are returned for all author CPAN IDs containing the specified infix.
# GET /api/v2/authors/DBOOK
{
"data" : [
{
"asciiname" : null,
"author" : "DBOOK",
"email" : null,
"fullname" : "Dan Book",
"has_cpandir" : true,
"homepage" : "http:\/\/github.com\/Grinnz",
"introduced" : 1417016502
}
],
"last_updated" : "1519670892"
}
# GET /api/v2/authors/XA?as_prefix=1
{
"data" : [
{
"asciiname" : null,
"author" : "XACHEN",
"email" : "...",
"fullname" : "Justin Cassidy",
"has_cpandir" : false,
"homepage" : null,
"introduced" : 1251852104
},
{
"asciiname" : "Grzegorz Rozniecki",
"author" : "XAERXESS",
"email" : "...",
"fullname" : "Grzegorz Rożniecki",
"has_cpandir" : true,
"homepage" : null,
"introduced" : 1360005262
},
...
{
"asciiname" : null,
"author" : "XAXXON",
"email" : "...",
"fullname" : "Zac Hansen",
"has_cpandir" : false,
"homepage" : "http:\/\/xaxxon.slackworks.com\/",
"introduced" : 1133035986
}
],
"last_updated" : "1519670892"
}
This software is Copyright (c) 2017 by Dan Book <dbook@cpan.org>.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
Bundled Perl 5 Raptor Copyright (c) 2012, Sebastian Riedel.
Licensed under the CC-SA License, Version 4.0 http://creativecommons.org/licenses/by-sa/4.0.