VPNDetection/Database.pm

filter: Statementstmt 100% 135 / 135 Branchbran 70.5% 24 / 34 Conditioncond 52.9% 9 / 17 MC/DCmcdc 27.2% 3 / 11 Subroutinesub 100% 39 / 39 Podpod 50.0% 7 / 14 totaltotal 86.8% 217 / 250 CC 24 SCAR 8.8
CC
24
Cov
90%
_assert_dataset
6.1
download_p
4.0
metadata_p
3.5
CRAP 2.4
« VPNDetection/Bogon.pm ↑ Summary VPNDetection/OauthError.pm »
1 package VPNDetection::Database;
2  
3 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 7 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 7 ▶use VPNDetection::Error;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 7 our $VERSION = '3.14.0';
11  
12 # The formats a dataset is published in. Anything else is refused before it
13 # reaches the API, whose 400 would cost a round trip and name nothing to act on.
14 7 ▶use constant FORMATS => qw(csvgz mmdb);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 7 my %FORMAT = map { $_ => 1 } FORMATS;
16  
17 # The values `list` reports for standing and license_type, so a caller can branch
18 # on each without spelling the list. license_type is undef for an unlicensed family.
19 7 ▶use constant STANDINGS => qw(expired licensed unlicensed);
Subroutine BEGIN: called CC=1 SCAR=0.0
20 7 ▶use constant LICENSE_TYPES => qw(evaluation standard redistribute);
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 # The dataset FAMILIES your organization is licensed to download. A license
23 # covers a family, while a download names one of its versions, so the IDs the
24 # download and checksum calls take come from each family's `versions`.
25 131 ▶sub list {
Subroutine list: called CC=1 SCAR=0.0
Pod documented
26 131 my $self = shift;
27 131 $self->_assert_blocking_ok('list');
28 131 return $self->{client}->_wait($self->list_p(@_));
29 }
30  
31 131 ▶sub list_p {
Subroutine list_p: called CC=1 SCAR=0.0
Pod undocumented
32 131 my ($self, %options) = @_;
33 131 return $self->_body_p('list', \%options, '/api/v1/database/list');
34 }
35  
36 # What is inside one dataset: schema, samples, row count and per-format sizes.
37 38 ▶sub metadata {
Subroutine metadata: called CC=1 SCAR=0.0
Pod documented
38 38 my $self = shift;
39 38 $self->_assert_blocking_ok('metadata');
40 38 return $self->{client}->_wait($self->metadata_p(@_));
41 }
42  
43 38 ▶sub metadata_p {
Subroutine metadata_p: called CC=3 SCAR=12.5
Pod undocumented
44 38 my ($self, $id, %options) = @_;
45 38 ▶ Carp::croak('database->metadata: expected a dataset id') if !defined $id || !length $id;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id and length $id 0 38 38
Condition33%1/3
defined $id and length $id
!ll&&!rl&&r
0038
MC/DC0%0/2
defined $id and length $id
defined $id length $id
Truth table33%1/3
A and B
A= defined $idB= length $id
ABresult
0X0
100
111
46 38 return $self->_body_p('metadata', \%options, '/api/v1/database/metadata', id => $id);
47 }
48  
49 # The digests published alongside one dataset file.
50 #
51 # Returns the WHOLE set rather than one algorithm: which digests a dataset
52 # publishes is the API's choice, not ours, and picking one here is how a caller
53 # ends up holding undef against a perfectly healthy API.
54 21 ▶sub checksums {
Subroutine checksums: called CC=1 SCAR=0.0
Pod documented
55 21 my $self = shift;
56 21 $self->_assert_blocking_ok('checksums');
57 21 return $self->{client}->_wait($self->checksums_p(@_));
58 }
59  
60 21 ▶sub checksums_p {
Subroutine checksums_p: called CC=1 SCAR=0.0
Pod undocumented
61 21 my ($self, $id, $format, %options) = @_;
62 21 _assert_dataset('checksums', $id, $format);
63 18 return $self->_body_p(
64 'checksums', \%options, '/api/v1/database/checksum', id => $id, format => $format,
65 );
66 }
67  
68 # Your organization's recent download attempts, newest first.
69 42 ▶sub downloads {
Subroutine downloads: called CC=1 SCAR=0.0
Pod documented
70 42 my $self = shift;
71 42 $self->_assert_blocking_ok('downloads');
72 42 return $self->{client}->_wait($self->downloads_p(@_));
73 }
74  
75 42 ▶sub downloads_p {
Subroutine downloads_p: called CC=2 SCAR=7.1
Pod undocumented
76 42 my ($self, %options) = @_;
77 42 my $limit = delete $options{limit};
78 42 ▶ return $self->_body_p(
Branch: 1 branch
BranchTrueFalseTotal
defined $limit ? : 0 42 42
79 'downloads', \%options, '/api/v1/database/downloads',
80 defined $limit ? (limit => $limit) : (),
81 );
82 }
83  
84 # The time-limited URL for one dataset file.
85 #
86 # The URL is returned rather than the bytes, so the caller decides how to
87 # transfer a file that routinely runs to gigabytes. The link authorizes the START
88 # of a transfer, so one already running is not interrupted when it lapses.
89 17 ▶sub download_url {
Subroutine download_url: called CC=1 SCAR=0.0
Pod documented
90 17 my $self = shift;
91 17 $self->_assert_blocking_ok('download_url');
92 17 return $self->{client}->_wait($self->download_url_p(@_));
93 }
94  
95 34 ▶sub download_url_p {
Subroutine download_url_p: called CC=3 SCAR=11.0
Pod undocumented
96 34 my ($self, $id, $format, %options) = @_;
97 34 _assert_dataset('download_url', $id, $format);
98 31 my $client = $self->{client};
99 31 $client->_check_options('database->download_url', \%options, 'build', 'retries', 'timeout');
100 my $url = $client->_url(
101 '/api/v1/database/download', id => $id, format => $format,
102 24 ▶ defined $options{build} ? (build => $options{build}) : (),
Branch: 1 branch
BranchTrueFalseTotal
defined $options{'build'} ? : 4 20 24
103 );
104 24 ▶ my $retries = defined $options{retries} ? $options{retries} : $client->{retries};
Branch: 1 branch
BranchTrueFalseTotal
defined $options{'retries'} ? : 0 24 24
105 24 ▶ return $client->_retry_p($retries, sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
106 22 ▶ $client->_get_p($url, $options{timeout})->then(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
107 22 my $res = shift->res;
108 22 ▶ return _location($res) if $res->code == 302;
Branch: 1 branch
BranchTrueFalseTotal
if $res->code == 302 19 3 22
109 # A 2xx here means the user agent followed the redirect and read the
110 # dataset into memory. Naming the cause beats reporting a shape
111 # mismatch a caller cannot act on.
112 3 ▶ die VPNDetection::Error->new(
Branch: 1 branch
BranchTrueFalseTotal
if $res->is_success 0 3 3
113 kind => 'server_error', status => $res->code,
114 message => 'expected a redirect to object storage but got '
115 . $res->code . '; the user agent must not follow redirects',
116 ) if $res->is_success;
117 3 die VPNDetection::Error->from_response($res->code, $res->headers, $res->json);
118 24 });
119 24 });
120 }
121  
122 # Stream one dataset file to a path, and return the bytes written.
123 25 ▶sub download {
Subroutine download: called CC=1 SCAR=0.0
Pod documented
124 25 my $self = shift;
125 25 $self->_assert_blocking_ok('download');
126 25 return $self->{client}->_wait($self->download_p(@_));
127 }
128  
129 26 ▶sub download_p {
Subroutine download_p: called CC=4 SCAR=13.9
Pod undocumented
130 26 my ($self, $id, $format, $path, %options) = @_;
131 # Everything a caller can get wrong is refused before the file is opened, so
132 # a mistyped ID cannot leave a stray .part behind.
133 26 _assert_dataset('download', $id, $format);
134 22 $self->{client}->_check_options('database->download', \%options, 'build', 'retries');
135 14 ▶ Carp::croak('database->download: expected a destination path')
Branch: 1 branch
BranchTrueFalseTotal
unless defined $path and length $path 1 13 14
Condition66%2/3
defined $path and length $path
!ll&&!rl&&r
1013
MC/DC50%1/2
defined $path and length $path
defined $path length $path
Truth table66%2/3
A and B
A= defined $pathB= length $path
ABresult
0X0
100
111
136 if !defined $path || !length $path;
137  
138 # The bytes land beside the destination and are renamed into place, so a
139 # transfer that dies half way leaves no short file that reads as a whole
140 # dataset. Opened BEFORE the request: an unwritable path costs no quota.
141 13 my $partial = "$path.part";
142 13 ▶ open my $handle, '>', $partial
Branch: 1 branch
BranchTrueFalseTotal
open my $handle, ">", $partial or Carp::croak("database->download: cannot open ${partial}: $!") 12 1 13
143 or Carp::croak("database->download: cannot open $partial: $!");
144 12 binmode $handle;
145  
146 204 ▶ return $self->_transfer_p('download', $id, $format, \%options, sub {
Subroutine __ANON__: called CC=2 SCAR=7.2
147 # A failure writing is the caller's to read rather than ours to retry: a
148 # full disk and a reset socket are different problems.
149 204 ▶ print {$handle} $_[0] or die "could not write the dataset to $partial: $!";
Branch: 1 branch
BranchTrueFalseTotal
print {$handle;} $_[0] or die "could not write the dataset to ${partial}: $!" 204 0 204
150 9 ▶ })->then(sub {
Subroutine __ANON__: called CC=3 SCAR=11.4
151 9 my $written = shift;
152 9 ▶ close $handle or die "could not write the dataset to $partial: $!";
Branch: 1 branch
BranchTrueFalseTotal
close $handle or die "could not write the dataset to ${partial}: $!" 9 0 9
153 9 ▶ rename $partial, $path or die "could not move the dataset into place at $path: $!";
Branch: 1 branch
BranchTrueFalseTotal
rename $partial, $path or die "could not move the dataset into place at ${path}: $!" 9 0 9
154 9 return $written;
155 3 ▶ })->catch(sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
156 3 my $error = shift;
157 3 close $handle;
158 3 unlink $partial;
159 3 die $error;
160 12 });
161 }
162  
163 # One dataset file's bytes, in memory.
164 17 ▶sub download_bytes {
Subroutine download_bytes: called CC=1 SCAR=0.0
Pod documented
165 17 my $self = shift;
166 17 $self->_assert_blocking_ok('download_bytes');
167 17 return $self->{client}->_wait($self->download_bytes_p(@_));
168 }
169  
170 18 ▶sub download_bytes_p {
Subroutine download_bytes_p: called CC=1 SCAR=0.0
Pod undocumented
171 18 my ($self, $id, $format, %options) = @_;
172 18 _assert_dataset('download_bytes', $id, $format);
173 14 my $bytes = '';
174 3 ▶ return $self->_transfer_p('download_bytes', $id, $format, \%options, sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
175 3 $bytes .= $_[0];
176 14 ▶ })->then(sub { return $bytes });
Subroutine __ANON__: called CC=1 SCAR=0.0
177 }
178  
179 191 ▶sub _new {
Subroutine _new: called CC=1 SCAR=0.0
180 191 my ($class, $client) = @_;
181 191 return bless { client => $client }, $class;
182 }
183  
184 # The 302 is followed as a SECOND request. `retries` covers it only until the
185 # first byte reaches the caller: object storage failing before that is retried
186 # like any 5xx, but a transfer that dies part way is not repeated, or the second
187 # copy would append to the bytes already written. A per-call `timeout` is refused
188 # rather than spent on the link call alone, where a caller would read it as
189 # bounding the transfer, which nothing does.
190 26 ▶sub _transfer_p {
Subroutine _transfer_p: called CC=2 SCAR=6.9
191 26 my ($self, $method, $id, $format, $options, $on_chunk) = @_;
192 26 my $client = $self->{client};
193 26 $client->_check_options("database->$method", $options, 'build', 'retries');
194 17 ▶ my $retries = defined $options->{retries} ? $options->{retries} : $client->{retries};
Branch: 1 branch
BranchTrueFalseTotal
defined $options->{'retries'} ? : 0 17 17
195 17 my $delivered = 0;
196 207 ▶ my $count = sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
197 207 $delivered += length $_[0];
198 207 $on_chunk->(@_);
199 17 };
200 14 ▶ return $self->download_url_p($id, $format, %$options)->then(sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
201 14 my $url = shift;
202 14 ▶ return $client->_retry_p($retries, sub { $client->_stream_p($url, $count) }, sub { !$delivered });
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
203 17 });
204 }
205  
206 # The member each call returns from one level down, or undef for a call that
207 # returns the whole answer, and the shape the whole answer must have: the pinned
208 # spec's schemas, as VPNDetection's _nonconforming reads them. A member the spec
209 # requires and never sends as null is required, a nullable or optional one may be
210 # absent or null, and every one present has the spec's type at every depth, so a
211 # version served as "3" fails the call rather than reaching the caller as a
212 # string (3.8.0). A `date` or `date-time` member is RFC 3339's, as its `format`
213 # says, on a day that exists. `standing`, `license_type`, `format` and `outcome` stay
214 # strings, open sets as the spec documents them, and a sample row is a hash
215 # whatever its columns.
216 7 my $VERSION_SHAPE = [fields => [
217 [id => ['string'], 1], [version => ['integer'], 1], [summary => ['string']],
218 [formats => [list => [fields => [[format => ['string'], 1], [bytes => ['integer']]]]], 1],
219 [sample_formats => [list => ['string']]],
220 ]];
221 7 my $DATABASE_SHAPE = [fields => [
222 [base => ['string'], 1], [name => ['string'], 1], [summary => ['string'], 1],
223 [license_type => ['string']], [starts => ['date-time']], [expires => ['date-time']],
224 [renews_at => ['date-time']], [notice_due_at => ['date-time']], [in_term => ['boolean'], 1],
225 [standing => ['string'], 1], [open => ['boolean'], 1], [versions => [list => $VERSION_SHAPE], 1],
226 ]];
227 7 my $COLUMN_SHAPE = [fields => [[name => ['string'], 1], [type => ['string'], 1], [description => ['string']]]];
228 7 my $METADATA_SHAPE = [fields => [
229 [id => ['string'], 1], [update_freq => ['string']], [updated => ['date'], 1],
230 [entries => ['integer'], 1], [schema => [map_of => [list => $COLUMN_SHAPE]], 1],
231 [sample => [map_of => [list => ['object']]]], [size => [map_of => ['integer']]],
232 [sample_size => [map_of => ['integer']]], [sample_entries => ['integer']],
233 ]];
234 my $CHECKSUMS_SHAPE = [fields => [
235 [id => ['string'], 1], [format => ['string'], 1],
236 7 [checksums => [fields => [map { [$_ => ['string'], 1] } qw(md5 sha1 sha256 sha512)]], 1],
237 ]];
238 7 my $DOWNLOAD_SHAPE = [fields => [
239 [dataset_id => ['string'], 1], [format => ['string'], 1], [outcome => ['string'], 1],
240 [sample => ['boolean'], 1], [open => ['boolean'], 1], [bytes => ['integer']], [http_status => ['integer']],
241 [apikey_id => ['string']], [client_ip => ['string']], [user_agent => ['string']],
242 [created => ['date-time'], 1],
243 ]];
244 7 my %UNWRAP = (
245 list => [databases => [fields => [[databases => [list => $DATABASE_SHAPE], 1]]]],
246 metadata => [undef, $METADATA_SHAPE],
247 checksums => [checksums => $CHECKSUMS_SHAPE],
248 downloads => [downloads => [fields => [[downloads => [list => $DOWNLOAD_SHAPE], 1]]]],
249 );
250  
251 229 ▶sub _body_p {
Subroutine _body_p: called CC=3 SCAR=11.1
252 229 my ($self, $method, $options, $path, @query) = @_;
253 229 my $client = $self->{client};
254 229 $client->_check_options("database->$method", $options, 'retries', 'timeout');
255 199 my $url = $client->_url($path, @query);
256 199 ▶ my $retries = defined $options->{retries} ? $options->{retries} : $client->{retries};
Branch: 1 branch
BranchTrueFalseTotal
defined $options->{'retries'} ? : 0 199 199
257 199 ▶ my @unwrap = @{ $UNWRAP{$method} || [] };
Condition50%1/2
$UNWRAP{$method} || []
l!l
1990
MC/DC0%0/1
$UNWRAP{$method} || []
$UNWRAP{$method}
Truth table50%1/2
A
A= $UNWRAP{$method}
Aresult
11
00
258 199 ▶ return $client->_retry_p($retries, sub { $client->_json_p($url, undef, $options->{timeout}, @unwrap) });
Subroutine __ANON__: called CC=1 SCAR=0.0
259 }
260  
261 99 ▶sub _assert_dataset {
Subroutine _assert_dataset: called CC=6 SCAR=18.0
262 99 my ($method, $id, $format) = @_;
263 99 ▶ Carp::croak("database->$method: expected a dataset ID") if !defined $id || !length $id;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id and length $id 1 98 99
Condition66%2/3
defined $id and length $id
!ll&&!rl&&r
0198
MC/DC50%1/2
defined $id and length $id
defined $id length $id
Truth table66%2/3
A and B
A= defined $idB= length $id
ABresult
0X0
100
111
264 98 ▶ Carp::croak("database->$method: expected a format") if !defined $format || !length $format;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $format and length $format 1 97 98
Condition66%2/3
defined $format and length $format
!ll&&!rl&&r
1097
MC/DC50%1/2
defined $format and length $format
defined $format length $format
Truth table66%2/3
A and B
A= defined $formatB= length $format
ABresult
0X0
100
111
265 Carp::croak("database->$method: '$format' is not a published format; expected one of "
266 97 ▶ . join(', ', FORMATS)) unless $FORMAT{$format};
Branch: 1 branch
BranchTrueFalseTotal
unless $FORMAT{$format} 12 85 97
267 }
268  
269 19 ▶sub _location {
Subroutine _location: called CC=3 SCAR=12.0
270 19 my ($res) = @_;
271 19 my $location = $res->headers->location;
272 19 ▶ die VPNDetection::Error->new(
Branch: 1 branch
BranchTrueFalseTotal
unless defined $location and length $location 0 19 19
Condition33%1/3
defined $location and length $location
!ll&&!rl&&r
0019
MC/DC0%0/2
defined $location and length $location
defined $location length $location
Truth table33%1/3
A and B
A= defined $locationB= length $location
ABresult
0X0
100
111
273 kind => 'server_error', status => $res->code,
274 message => 'the API redirected without a Location header',
275 ) if !defined $location || !length $location;
276 19 return $location;
277 }
278  
279 291 ▶sub _assert_blocking_ok {
Subroutine _assert_blocking_ok: called CC=1 SCAR=0.0
280 291 my ($self, $method) = @_;
281 291 $self->{client}->_assert_blocking_ok("database->$method");
282 }
283  
284 7 1;
285  
286 __END__
« VPNDetection/Bogon.pm ↑ Summary VPNDetection/OauthError.pm »