view release on metacpan or  search on metacpan

lib/Net/Whois/Object.pm  view on Meta::CPAN

Or even

    # Replace CPNY-MNT2 by REPL-MNT
    $person->mnt_by({mode => 'replace', value => {old => 'CPNY-MNT2', new => 'REPL-MNT'}});

From release 2.002 you can also use the 'delete' mode to remove a specific attribute value

    $person->mnt_by({mode => 'delete', value => {old => 'REPL-MNT'}});
    
    # Or if you want to remove all remarks (the regex '.' meaning any char, will match all remarks values)
    $person->remarks({mode => 'delete', value => {old => '.'}});


=head2 Dump the current state of the data

The dump() method, enable to print the object under the classic
text form, made of 'attribute:  value' lines.

    # Dump the modified data
    my $to_be_mailed = $person->dump();

dump() handle the 'align' parameter passed though a hash ref.

    my $to_be_mailed = $person->dump( { align => 15 });

=head2 Update the RIPE database

The RIPE database update is currently under heavy development.

B<*The update code is still to be considered as experimental.*>

We plan to offer several ways to update the RIPE database

=head3 Update through the web interface

RIPE provides several web interfaces

=head4 SyncUpdates (*Experimental*)

Although not the latest one, this simple interface is the first to be wrapped
by this module.

B<CAUTION: SyncUpdates features require LWP::UserAgent to be installed.>

=head4 Create

Once the object has been modified, locally, you can create it in the database
calling the syncupdates_create() method.

The parameters are passed through a hash ref, and can be the maintener
authentication credentials ('password' or 'pgpkey') and the 'align' parameter

    $object->person('John Doe');
    ...
    my $primary_key = $object->syncupdates_create( { password => $password } );
    # or
    my $primary_key = $object->syncupdates_create( { pgpkey   => $keyID, align => 8 } );

The pgp key must be an eight digit hexadecimal key ID known to the local
C<gpg> executable.

If the C<pgpkey> key is present in the hash reference passed to
syncupdates_create, you can also pass in the C<pgpexec> key to chose a program
to execute for signing (C<gpg> by default), and C<pgpopts>, which must be an
array reference of additional options to pass to the signing binary.

The primary key of the object created is returned.
The attribute used as primary key can be obtained through 
C<$object->attribute('primary')>

=head4 Update

An object existing in the RIPE database, can be retrieved, modified locally
and then updated through the syncupdates_update() method.

Parameters are passed through a hash ref, and can be the maintener
authentication credentials ('password' or 'pgpkey') and the 'align' parameter
See L</Create> for more information on the authentication methods.

    $object->person('John Doe');
    ...
    $object->syncupdates_update( { password => $password } );

=head4 Delete

An object existing in the RIPE database, can be retrieved, and deleted in
the databased through the syncupdates_delete() method.
Parameters are passed through a hash ref, and can be the maintener
authentication credentials ('password' or 'pgpkey') and the 'reason' parameter
See L</Create> for more information on the authentication methods.

    $object->syncupdates_delete( { pgpkey => $keyID } );

An additional parameter can be used as a reason for the deletion.

    $object->syncupdates_delete( { pgpkey => $keyID, reason =>  'Obsoleted by XXX' } );

If no reason is provided, a default one ('Not needed anymore') is used.
    
=head3 Update through email.

Not implemented yet.

=head1 SUBROUTINES/METHODS

=head2 B<new( @lines|$iterator )>

The constructor is a factory returning the appropriate Net::Whois::Objects
based on the first attribute of the block.
You can pass an array of lines or an iterator returned by Net::Whois::RIPE
as argument.

The two following ways of using the constructor are possible

    my $whois = Net::Whois::RIPE->new( %options );
    $iterator = $whois->query('AS30781');

    # Using the iterator way
    push @objects, Net::Whois::Object->new($iterator);

or

    # Using the previous (more circonvoluted) @lines way

lib/Net/Whois/Object.pm  view on Meta::CPAN

}

=head2 B<_init( @options )>

Initialize self with C<@options>

=cut

sub _init {
    my ( $self, @options ) = @_;

    while ( my ( $key, $val ) = splice( @options, 0, 2 ) ) {
        $self->$key($val);
    }
}

=head2 B<_syncupdates_submit( $text, \%options )>

Interact with the RIPE database through the web syncupdates interface.
Submit the text passed as parameter.
Use the password passed as parameter to authenticate.
The database used is chosen based on the 'source' attribute.

Return the HTML code of the returned page.
(This will change in a near future)

=cut

sub _syncupdates_submit {
    my ( $self, $text, $options ) = @_;

    if ( exists $options->{pgpkey} ) {
        $text = $self->_pgp_sign( $text, $options );
    } elsif ( exists $options->{password} ) {
        my $password = $options->{password};
        chomp $password;
        croak("Passwords containing newlines are not supported")
            if $password =~ /\n/;
        $text .= "password: $password\n";
    }

    croak "LWP::UserAgent required for updates" unless $LWP;

    my $url = $self->source eq 'RIPE' ? 'http://syncupdates.db.ripe.net/' : 'http://syncupdates-test.db.ripe.net';

    my $ua = LWP::UserAgent->new;

    my $response = $ua->post( $url, { DATA => $text } );
    my $response_text = $response->decoded_content;

    unless ( $response->is_success ) {
        croak "Can't sync object with RIPE database: $response_text";
    }

    return $response_text;
}

=head2 B<_pgp_sign( $text, $auth )>

Sign the C<$text> with the C<gpg> command and gpg information in C<$auth>
Returns the signed text.

=cut

sub _pgp_sign {
    my ( $self, $text, $auth ) = @_;

    my $binary = $auth->{pgpexec} || 'gpg';
    my $key_id = $auth->{pgpkey};
    my @opts   = @{ $auth->{pgpopts} || [] };

    $key_id =~ s/^0x//;
    my $pid = open2( my $child_out, my $child_in, $binary, "--local-user=$key_id", '--clearsign', @opts );
    print {$child_in} $text;
    close $child_in;

    $text = do { local $/; <$child_out> };
    close $child_out;

    waitpid( $pid, 0 );
    my $child_exit_status = $? >> 8;
    if ( $child_exit_status != 0 ) {
        croak "Error while launching $binary for signing the message: child process exited with status $child_exit_status";
    }

    return $text;
}

=head2 B<_TYPE>

Returns a hash ref that contains the attribute data for the class
of the object that the method was called on.

=end UNDOCUMENTED

=cut

my %TYPES;

sub _TYPE {
    $TYPES{ ref $_[0] || $_[0] } ||= {};
}

=head1 SEE ALSO

Please take a look at L<Net::Whois::Generic> the more generic whois client built on top of Net::Whois::RIPE.

=head1 TODO

The update part (in RIPE database) still needs a lot of work.

Enhance testing without network

Enhance test coverage

=head1 AUTHOR

Arnaud "Arhuman" Assad, C<< <arhuman at gmail.com> >>

=head1 ACKNOWLEDGEMENTS

Thanks to Jaguar Network for allowing me to work on this during some of my office
hours.

Thanks to Luis Motta Campos for his trust when allowing me to publish this
release.

Thanks to Moritz Lenz for all his contributions