API.pm

filter: Statementstmt 88.5% 62 / 70 Branchbran 35.0% 7 / 20 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 93.3% 14 / 15 Podpod 100% 3 / 3 totaltotal 79.6% 86 / 108 CC 12 SCAR 10.5
CC
12
Cov
77%
__ANON__
5.8
__ANON__
3.6
__ANON__
3.6
CRAP 2.9
« API/Router.pm ↑ Summary
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
BranchTrueFalseTotal
if (not -e $dir) { } 4 0 4
elsif (not -d $dir) { } 0 0 0
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
BranchTrueFalseTotal
File::Copy::Recursive::fcopy($idx, $dir) or die "Cannot copy $idx to ${dir}: $!\n" 4 0 4
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
BranchTrueFalseTotal
if (not -e $dir) { } 2 0 2
elsif (not -d $dir) { } 0 0 0
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
BranchTrueFalseTotal
if (not -e $dir) { } 3 0 3
elsif (not -d $dir) { } 0 0 0
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
BranchTrueFalseTotal
open my $fh, "<:raw", $fn or die "Cannot open ${fn}: $!\n" 116 0 116
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
BranchTrueFalseTotal
open my $fh, ">:utf8", $fn or die "Cannot open ${fn}: $!\n" 57 0 57
243 57 print $fh $encoder->encode($data);
244 57 ▶ close $fh or die "Cannot close $fn: $!\n";
Branch: 1 branch
BranchTrueFalseTotal
close $fh or die "Cannot close ${fn}: $!\n" 57 0 57
245 }
246  
247 5 __PACKAGE__->meta->make_immutable;
248  
249 5 1;
250  
251 __END__
« API/Router.pm ↑ Summary