internal and POD documentation update

parent 727d97ea
......@@ -37,7 +37,7 @@ L<Net::RDAP> - an interface to the Registration Data Access Protocol
$object = $rdap->ip(Net::IP->new('2001:DB8::/32'));
# get info about AS numbers:
$object = $rdap->ip(Net::ASN->new(65536));
$object = $rdap->autnum(Net::ASN->new(65536));
=head1 DESCRIPTION
......@@ -65,9 +65,8 @@ interface to information about all unique Internet identifiers.
$rdap = Net::RDAP->new(%OPTIONS);
Constructor method, returns a new object.
Supported options:
Constructor method, returns a new object. %OPTIONS is optional, but
may contain any of the following options:
=over
......@@ -107,6 +106,19 @@ domain (such as C<168.192.in-addr.arpa>).
If there was an error, this method will return a L<Net::RDAP::Error>.
=head3 Note on Internationalised Domain Names (IDNs)
Domain names which contain characters other than those from the ASCII-compatible
range must be encoded into "A-label" (or "Punycode") format before being passed
to C<Net::DNS::Domain>. You can use C<Net::LibIDN> or C<Net::LibIDN2> to
perform this encoding:
use Net::LibIDN;
my $name = "espécime.com";
my $domain = $rdap->domain->(Net::DNS::Domain->new(idn_to_ascii($name, 'UTF-8')));
=cut
sub domain {
......@@ -252,11 +264,11 @@ sub query {
=head2 Directly Fetching Known Resources
$object = $rdap->fetch($url);
$object = $rdap->fetch($url, %OPTIONS);
$object = $rdap->fetch($link);
$object = $rdap->fetch($link, %OPTIONS);
$object = $rdap->fetch($object);
$object = $rdap->fetch($object, %OPTIONS);
The first and second forms of the C<fetch()> method retrieve the
resource identified by C<$url> or C<$link> (which must be either a
......@@ -289,6 +301,10 @@ In order for this form to work, the object must have a C<self> link:
L<Net::RDAP> will auto-create one for objects that don't have one if it
can.
C<%OPTIONS> is an optional hash containing additional options for the query. At
the moment, only the C<user> and C<pass> options are supported; if provided,
they will be sent to the server in an HTTP Basic Authorization header field.
=cut
sub fetch {
......@@ -321,8 +337,14 @@ sub fetch {
);
}
#
# construct HTTP::Request object
#
my $request = GET($url);
#
# add Authorization header field if we have a username/password
#
$request->header('Authorization' => sprintf('Basic %s', encode_base64(join(':', ($args{'user'}, $args{'pass'}))))) if ($args{'user'} && $args{'pass'});
my $file = sprintf(
......@@ -331,6 +353,9 @@ sub fetch {
sha1_hex($url),
);
#
# we have a locally-cached copy, so add the If-Modified-Since header field
#
$request->header('If-Modified-Since' => HTTP::Date::time2str(stat($file)->mtime)) if (-e $file && $self->{'use_cache'});
#
......@@ -339,7 +364,8 @@ sub fetch {
my $response = $self->request($request);
#
# attempt to parse the JSON
# attempt to parse the JSON. The RDAP server *should* only ever send JSON, but
# this cannot be guaranteed:
#
my $data;
eval { $data = decode_json($response->decoded_content) };
......@@ -348,13 +374,21 @@ sub fetch {
# check and parse the response
#
if (-e $file && (304 == $response->code || ($response->code >= 500))) {
#
# 304 response, or some sort of network/server error, but we have a
# cached copy:
#
utime(undef, undef, $file) if (304 == $response->code);
return $self->object_from_response(decode_json(read_file($file)), $url);
} elsif ($response->is_error) {
#
# some other error:
#
if ($self->is_rdap($response) && defined($data->{'errorCode'})) {
#
# we got an RDAP response from the server which looks like it's an error, so convert it and return
# we got an RDAP response from the server which looks like
# it's an error, so convert it and return:
#
return Net::RDAP::Error->new($data, $url);
......@@ -370,6 +404,9 @@ sub fetch {
}
} elsif (!$self->is_rdap($response)) {
#
# we got something that isn't a valid RDAP response:
#
return $self->error(
'url' => $url,
'errorCode' => 500,
......@@ -378,6 +415,9 @@ sub fetch {
);
} elsif (!defined($data) || 'HASH' ne ref($data)) {
#
# response was not parseable as JSON:
#
return $self->error(
'url' => $url,
'errorCode' => 500,
......@@ -386,6 +426,9 @@ sub fetch {
);
} elsif (!defined($data->{'objectClassName'}) && scalar(grep { /^(domain|nameserver|entity)SearchResults$/ } keys(%{$data})) < 1) {
#
# response is missing the objectClassName property and is not a search result:
#
return $self->error(
'url' => $url,
'errorCode' => 500,
......@@ -394,9 +437,15 @@ sub fetch {
);
} else {
#
# update local cache
#
write_file($file, $response->decoded_content) if ($self->{'use_cache'});
chmod(0600, $file);
#
# return object
#
return $self->object_from_response($data, $url);
}
}
......@@ -476,12 +525,18 @@ strings, etc.
sub ua {
my $self = shift;
$self->{'ua'} = Net::RDAP::UA->new if (!defined($self->{'ua'}));
#
# inject our UA object into NET::RDAP::Registry so everything
# uses the same user agent
#
$NET::RDAP::Registry::UA = $self->{'ua'} if (!defined($NET::RDAP::Registry::UA));
return $self->{'ua'};
}
#
# generate an error
# construct an error. arguments: errorCode, title, description
#
sub error {
my ($self, %params) = @_;
......
......@@ -32,6 +32,7 @@ L<Net::RDAP::Registry> - an interface to the IANA RDAP registries.
$url = Net::RDAP::Registry->get_url(Net::IP->new('192.168.0.1'));
$url = Net::RDAP::Registry->get_url(Net::IP->new('2001:DB8::/32'));
$url = Net::RDAP::Registry->get_url(Net::ASN->new(65536));
$url = Net::RDAP::Registry->get_url("ABC123-TAG");
=head1 DESCRIPTION
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment