| 1 | package PGXN::API; | ||||||||||||||
| 2 | |||||||||||||||
| 3 | 5 | ▶ | use v5.14; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 4 | 5 | ▶ | use utf8; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 5 | 5 | ▶ | use MooseX::Singleton; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 6 | 5 | ▶ | use File::Spec::Functions qw(catfile catdir); | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 7 | 5 | ▶ | use URI::Template; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 8 | 5 | ▶ | use JSON; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 9 | 5 | ▶ | use namespace::autoclean; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 10 | 5 | our $VERSION = v0.22.1; | |||||||||||||
| 11 | |||||||||||||||
| 12 | =head1 Name | ||||||||||||||
| 13 | |||||||||||||||
| 14 | PGXN::API - Maintain and serve a REST API to search PGXN mirrors | ||||||||||||||
| 15 | |||||||||||||||
| 16 | =head1 Synopsis | ||||||||||||||
| 17 | |||||||||||||||
| 18 | In a cron job: | ||||||||||||||
| 19 | |||||||||||||||
| 20 | * * * * 42 pgxn_api_sync --root /var/www/api rsync://master.pgxn.org/pgxn/ | ||||||||||||||
| 21 | |||||||||||||||
| 22 | In a system start script: | ||||||||||||||
| 23 | |||||||||||||||
| 24 | pgxn_api_server --doc-root /var/www/api \ | ||||||||||||||
| 25 | --errors-from oops@example.com \ | ||||||||||||||
| 26 | --errors-to alerts@example.com | ||||||||||||||
| 27 | |||||||||||||||
| 28 | =head1 Description | ||||||||||||||
| 29 | |||||||||||||||
| 30 | L<PGXN|http://pgxn.org> is a L<CPAN|http://cpan.org>-inspired network for | ||||||||||||||
| 31 | distributing extensions for the L<PostgreSQL RDBMS|http://www.postgresql.org>. | ||||||||||||||
| 32 | All of the infrastructure tools, however, have been designed to be used to | ||||||||||||||
| 33 | create networks for distributing any kind of release distributions and for | ||||||||||||||
| 34 | providing a lightweight static file JSON REST API. | ||||||||||||||
| 35 | |||||||||||||||
| 36 | PGXN::API provides a superset of the static file REST API, embellishing the | ||||||||||||||
| 37 | metadata in some files and providing additional APIs, including full-text | ||||||||||||||
| 38 | search and browsable access to all packages on the mirror. Hit the L<PGXN API | ||||||||||||||
| 39 | server|http://api.pgxn.org/> for the canonical deployment of this module. | ||||||||||||||
| 40 | Better yet, read the L<comprehensive API | ||||||||||||||
| 41 | documentation|http://github.com/pgxn/pgxn-api/wiki> or use L<WWW::PGXN> if you | ||||||||||||||
| 42 | just want to use the API. | ||||||||||||||
| 43 | |||||||||||||||
| 44 | There are two simple steps to setting up your own API server using this | ||||||||||||||
| 45 | module: | ||||||||||||||
| 46 | |||||||||||||||
| 47 | =over | ||||||||||||||
| 48 | |||||||||||||||
| 49 | =item * L<pgxn_api_sync> | ||||||||||||||
| 50 | |||||||||||||||
| 51 | This script syncs to a PGXN mirror via rsync and processes newly-synced data | ||||||||||||||
| 52 | to provide the additional data and APIs. Any PGXN mirror will do. If you need | ||||||||||||||
| 53 | to create your own network of mirrors first, see | ||||||||||||||
| 54 | L<PGXN::Manager|http://github.com/pgxn/pgxn-manager/>. Consult the | ||||||||||||||
| 55 | L<pgxn_api_sync> documentation for details on its (minimal) options. | ||||||||||||||
| 56 | |||||||||||||||
| 57 | =item * L<pgxn_api_server> | ||||||||||||||
| 58 | |||||||||||||||
| 59 | A L<Plack> server for the API. In addition to the usual L<plackup> options, it | ||||||||||||||
| 60 | has a few of its own: | ||||||||||||||
| 61 | |||||||||||||||
| 62 | =over | ||||||||||||||
| 63 | |||||||||||||||
| 64 | =item C<--doc-root> | ||||||||||||||
| 65 | |||||||||||||||
| 66 | The path to use for the API document root. This is the same directory as you | ||||||||||||||
| 67 | manage via L<pgxn_api_sync> in a cron job. Optional. If not specified, it will | ||||||||||||||
| 68 | default to a directory named F<www> in the parent directory above the F<PGXN> | ||||||||||||||
| 69 | directory in which this module is installed. If you're running the API from a | ||||||||||||||
| 70 | Git checkout, that should be fine. Otherwise you should probably specify a | ||||||||||||||
| 71 | document root or you're you'll never be able to find it. | ||||||||||||||
| 72 | |||||||||||||||
| 73 | =item C<--errors-to> | ||||||||||||||
| 74 | |||||||||||||||
| 75 | An email address to which error emails should be sent. In the event of an | ||||||||||||||
| 76 | internal server error, the server will send an email to this address with | ||||||||||||||
| 77 | diagnostic information. | ||||||||||||||
| 78 | |||||||||||||||
| 79 | =item C<--errors-from> | ||||||||||||||
| 80 | |||||||||||||||
| 81 | An email address from which alert emails should be sent. | ||||||||||||||
| 82 | |||||||||||||||
| 83 | =back | ||||||||||||||
| 84 | |||||||||||||||
| 85 | =back | ||||||||||||||
| 86 | |||||||||||||||
| 87 | And that's it. If you're interested in the internals of PGXN::API or in | ||||||||||||||
| 88 | hacking on it, read on. Otherwise, just enjoy your own API server! | ||||||||||||||
| 89 | |||||||||||||||
| 90 | =head1 Interface | ||||||||||||||
| 91 | |||||||||||||||
| 92 | =head2 Constructor | ||||||||||||||
| 93 | |||||||||||||||
| 94 | =head3 C<instance> | ||||||||||||||
| 95 | |||||||||||||||
| 96 | my $app = PGXN::Manager->instance; | ||||||||||||||
| 97 | |||||||||||||||
| 98 | Returns the singleton instance of PGXN::Manager. This is the recommended way | ||||||||||||||
| 99 | to get the PGXN::API object. | ||||||||||||||
| 100 | |||||||||||||||
| 101 | =head2 Class Method | ||||||||||||||
| 102 | |||||||||||||||
| 103 | =head3 C<version_string> | ||||||||||||||
| 104 | |||||||||||||||
| 105 | say 'PGXN::API ', PGXN::API->version_string; | ||||||||||||||
| 106 | |||||||||||||||
| 107 | Returns a string representation of the PGXN::API version. | ||||||||||||||
| 108 | |||||||||||||||
| 109 | =cut | ||||||||||||||
| 110 | |||||||||||||||
| 111 | 80 | ▶ | sub version_string { | ||||||||||||
|
Subroutine
version_string: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 112 | 80 | sprintf 'v%vd', $VERSION; | |||||||||||||
| 113 | } | ||||||||||||||
| 114 | |||||||||||||||
| 115 | =head2 Attributes | ||||||||||||||
| 116 | |||||||||||||||
| 117 | =head3 C<uri_templates> | ||||||||||||||
| 118 | |||||||||||||||
| 119 | my $templates = $pgxn->uri_templates; | ||||||||||||||
| 120 | |||||||||||||||
| 121 | Returns a hash reference of the URI templates for the various files stored in | ||||||||||||||
| 122 | the API document root. The keys are the names of the templates, and the values | ||||||||||||||
| 123 | are L<URI::Template> objects. Includes the additional URI templates added by | ||||||||||||||
| 124 | L<PGXN::API::Indexer/update_mirror_meta>. | ||||||||||||||
| 125 | |||||||||||||||
| 126 | =cut | ||||||||||||||
| 127 | |||||||||||||||
| 128 | 3 | ▶ | has uri_templates => (is => 'ro', isa => 'HashRef', lazy => 1, default => sub { | ||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||
| 129 | 3 | my $self = shift; | |||||||||||||
| 130 | 3 | my $tmpl = $self->read_json_from( | |||||||||||||
| 131 | catfile $self->doc_root, 'index.json' | ||||||||||||||
| 132 | ); | ||||||||||||||
| 133 | 3 | return { map { $_ => URI::Template->new($tmpl->{$_}) } keys %{ $tmpl } }; | |||||||||||||
| 134 | 5 | }); | |||||||||||||
| 135 | |||||||||||||||
| 136 | =head3 C<doc_root> | ||||||||||||||
| 137 | |||||||||||||||
| 138 | my $doc_root = $pgxn->doc_root; | ||||||||||||||
| 139 | |||||||||||||||
| 140 | Returns the document root for the API server. The default is the F<www> | ||||||||||||||
| 141 | directory in the root directory of this distribution. | ||||||||||||||
| 142 | |||||||||||||||
| 143 | =cut | ||||||||||||||
| 144 | |||||||||||||||
| 145 | 4 | ▶ | my $trig = sub { | ||||||||||||
|
Subroutine
__ANON__: called CC=5 SCAR=17.5
| |||||||||||||||
| 146 | 4 | my ($self, $dir) = @_; | |||||||||||||
| 147 | 4 | ▶ | if (!-e $dir) { | ||||||||||||
|
Branch: 2 branches
| |||||||||||||||
| 148 | 4 | require File::Path; | |||||||||||||
| 149 | 4 | File::Path::make_path($dir); | |||||||||||||
| 150 | |||||||||||||||
| 151 | # Copy over the index.html. | ||||||||||||||
| 152 | 4 | require File::Copy::Recursive; | |||||||||||||
| 153 | |||||||||||||||
| 154 | 4 | (my $api_dir = __FILE__) =~ s{[.]pm$}{}; | |||||||||||||
| 155 | 4 | my $idx = catfile $api_dir, 'index.html'; | |||||||||||||
| 156 | 4 | ▶ | File::Copy::Recursive::fcopy($idx, $dir) | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 157 | or die "Cannot copy $idx to $dir: $!\n"; | ||||||||||||||
| 158 | |||||||||||||||
| 159 | # Pre-generate the metadata directories. | ||||||||||||||
| 160 | File::Path::make_path(catdir $dir, $_) | ||||||||||||||
| 161 | 4 | for qw(user tag dist extension); | |||||||||||||
| 162 | } elsif (!-d $dir) { | ||||||||||||||
| 163 | 0 | die qq{Location for document root "$dir" is not a directory\n}; | |||||||||||||
| 164 | } | ||||||||||||||
| 165 | 5 | }; | |||||||||||||
| 166 | |||||||||||||||
| 167 | 0 | ▶ | has doc_root => (is => 'rw', isa => 'Str', lazy => 1, trigger => $trig, default => sub { | ||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||
| 168 | 0 | my $file = quotemeta catfile qw(lib PGXN API.pm); | |||||||||||||
| 169 | 0 | my $blib = quotemeta catfile 'blib', ''; | |||||||||||||
| 170 | 0 | (my $dir = __FILE__) =~ s{(?:$blib)?$file$}{www}; | |||||||||||||
| 171 | 0 | $trig->(shift, $dir); | |||||||||||||
| 172 | 0 | $dir; | |||||||||||||
| 173 | 5 | }); | |||||||||||||
| 174 | |||||||||||||||
| 175 | =head3 C<source_dir> | ||||||||||||||
| 176 | |||||||||||||||
| 177 | my $source_dir = $pgxn->source_dir; | ||||||||||||||
| 178 | |||||||||||||||
| 179 | Returns the directory on the file system where sources should be unzipped, | ||||||||||||||
| 180 | which is just the F<src> subdirectory of C<doc_root>. | ||||||||||||||
| 181 | |||||||||||||||
| 182 | =cut | ||||||||||||||
| 183 | |||||||||||||||
| 184 | 2 | ▶ | has source_dir => (is => 'ro', 'isa' => 'Str', lazy => 1, default => sub { | ||||||||||||
|
Subroutine
__ANON__: called CC=3 SCAR=12.7
| |||||||||||||||
| 185 | 2 | my $dir = catdir shift->doc_root, 'src'; | |||||||||||||
| 186 | 2 | ▶ | if (!-e $dir) { | ||||||||||||
|
Branch: 2 branches
| |||||||||||||||
| 187 | 2 | require File::Path; | |||||||||||||
| 188 | 2 | File::Path::make_path($dir); | |||||||||||||
| 189 | } elsif (!-d $dir) { | ||||||||||||||
| 190 | 0 | die qq{Location for source files "$dir" is not a directory\n}; | |||||||||||||
| 191 | } | ||||||||||||||
| 192 | 2 | $dir; | |||||||||||||
| 193 | 5 | }); | |||||||||||||
| 194 | |||||||||||||||
| 195 | =head3 C<mirror_root> | ||||||||||||||
| 196 | |||||||||||||||
| 197 | my $mirror_root = $pgxn->mirror_root; | ||||||||||||||
| 198 | |||||||||||||||
| 199 | Returns the directory on the file system where the PGXN mirror lives, which is | ||||||||||||||
| 200 | just the F<mirror> subdirectory of C<doc_root>. | ||||||||||||||
| 201 | |||||||||||||||
| 202 | =cut | ||||||||||||||
| 203 | |||||||||||||||
| 204 | 3 | ▶ | has mirror_root => (is => 'rw', 'isa' => 'Str', lazy => 1, default => sub { | ||||||||||||
|
Subroutine
__ANON__: called CC=3 SCAR=12.7
| |||||||||||||||
| 205 | 3 | my $dir = catdir shift->doc_root, 'mirror'; | |||||||||||||
| 206 | 3 | ▶ | if (!-e $dir) { | ||||||||||||
|
Branch: 2 branches
| |||||||||||||||
| 207 | 3 | require File::Path; | |||||||||||||
| 208 | 3 | File::Path::make_path($dir); | |||||||||||||
| 209 | } elsif (!-d $dir) { | ||||||||||||||
| 210 | 0 | die qq{Location for source files "$dir" is not a directory\n}; | |||||||||||||
| 211 | } | ||||||||||||||
| 212 | 3 | $dir; | |||||||||||||
| 213 | 5 | }); | |||||||||||||
| 214 | |||||||||||||||
| 215 | =head3 C<read_json_from> | ||||||||||||||
| 216 | |||||||||||||||
| 217 | my $data = $pgxn->read_json_from($filename); | ||||||||||||||
| 218 | |||||||||||||||
| 219 | Loads the contents of C<$filename>, parses them as JSON, and returns the | ||||||||||||||
| 220 | resulting data structure. | ||||||||||||||
| 221 | |||||||||||||||
| 222 | =cut | ||||||||||||||
| 223 | |||||||||||||||
| 224 | 116 | ▶ | sub read_json_from { | ||||||||||||
|
Subroutine
read_json_from: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||
| 225 | 116 | my ($self, $fn) = @_; | |||||||||||||
| 226 | 116 | ▶ | open my $fh, '<:raw', $fn or die "Cannot open $fn: $!\n"; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 227 | 116 | local $/; | |||||||||||||
| 228 | 116 | return JSON->new->utf8->decode(<$fh>); | |||||||||||||
| 229 | } | ||||||||||||||
| 230 | |||||||||||||||
| 231 | =head3 C<write_json_to> | ||||||||||||||
| 232 | |||||||||||||||
| 233 | my $data = $pgxn->write_json_to($filename, $data); | ||||||||||||||
| 234 | |||||||||||||||
| 235 | Writes C<$data> to C<$filename> as JSON. | ||||||||||||||
| 236 | |||||||||||||||
| 237 | =cut | ||||||||||||||
| 238 | |||||||||||||||
| 239 | 57 | ▶ | sub write_json_to { | ||||||||||||
|
Subroutine
write_json_to: called CC=3 SCAR=11.3
Pod
documented
| |||||||||||||||
| 240 | 57 | my ($self, $fn, $data) = @_; | |||||||||||||
| 241 | 57 | my $encoder = JSON->new->space_after->allow_nonref->indent->canonical; | |||||||||||||
| 242 | 57 | ▶ | open my $fh, '>:utf8', $fn or die "Cannot open $fn: $!\n"; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 243 | 57 | print $fh $encoder->encode($data); | |||||||||||||
| 244 | 57 | ▶ | close $fh or die "Cannot close $fn: $!\n"; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 245 | } | ||||||||||||||
| 246 | |||||||||||||||
| 247 | 5 | __PACKAGE__->meta->make_immutable; | |||||||||||||
| 248 | |||||||||||||||
| 249 | 5 | 1; | |||||||||||||
| 250 | |||||||||||||||
| 251 | __END__ | ||||||||||||||