--- cvsroot/Net-FCP/FCP.pm 2003/09/10 05:20:48 1.16 +++ cvsroot/Net-FCP/FCP.pm 2003/09/12 03:28:45 1.17 @@ -37,6 +37,30 @@ You should specify the event module to use only in the main program. +=head2 FREENET BASICS + +Ok, this section will not explain any freenet basics to you, just some +problems I found that you might want to avoid: + +=over 4 + +=item freenet URIs are _NOT_ URIs + +Whenever a "uri" is required by the protocol, freenet expects a kind of +URI prefixed with the "freenet:" scheme, e.g. "freenet:CHK...". However, +these are not URIs, as freeent fails to parse them correctly, that is, you +must unescape an escaped characters ("%2c" => ",") yourself. Maybe in the +future this library will do it for you, so watch out for this incompatible +change. + +=item Numbers are in HEX + +Virtually every number in the FCP protocol is in hex. Be sure to use +C on all such numbers, as the module (currently) does nothing to +convert these for you. + +=back + =head2 THE Net::FCP CLASS =over 4 @@ -95,18 +119,18 @@ version => { revision => 1 }, document => [ { - "info.format" => "image/jpeg", + info => { format" => "image/jpeg" }, name => "background.jpg", - "redirect.target" => "freenet:CHK\@ZcagI,ra726bSw" + redirect => { target => "freenet:CHK\@ZcagI,ra726bSw" }, }, { - "info.format" => "text/html", + info => { format" => "text/html" }, name => ".next", - "redirect.target" => "freenet:SSK\@ilUPAgM/TFEE/3" + redirect => { target => "freenet:SSK\@ilUPAgM/TFEE/3" }, }, { - "info.format" => "text/html", - "redirect.target" => "freenet:CHK\@8M8Po8ucwI,8xA" + info => { format" => "text/html" }, + redirect => { target => "freenet:CHK\@8M8Po8ucwI,8xA" }, } ] ) @@ -133,12 +157,12 @@ if ($data =~ /\GEndPart\015?\012/gc) { # nop - } elsif ($data =~ /\GEnd\015?\012/gc) { + } elsif ($data =~ /\GEnd(\015?\012|$)/gc) { last; } elsif ($data =~ /\G([A-Za-z0-9.\-]+)\015?\012/gcs) { push @{$meta->{tolc $1}}, $hdr = {}; } elsif ($data =~ /\G(.*)/gcs) { - die "metadata format error ($1)"; + die "metadata format error ($1), please report this string: <<$data>>"; } } } @@ -154,9 +178,15 @@ 127.0.0.1:8481, or the environment variables C and C). Connections are virtual because no persistent physical connection is -established. However, the existance of the node is checked by executing a +established. + +=begin comment + +However, the existance of the node is checked by executing a C transaction. +=end + =cut sub new { @@ -215,11 +245,13 @@ $txn; } -sub _txn($&) { +{ # transactions + +my $txn = sub { my ($name, $sub) = @_; - *{"$name\_txn"} = $sub; + *{"txn_$name"} = $sub; *{$name} = sub { $sub->(@_)->result }; -} +}; =item $txn = $fcp->txn_client_hello @@ -235,11 +267,11 @@ =cut -_txn client_hello => sub { +$txn->(client_hello => sub { my ($self) = @_; $self->txn ("client_hello"); -}; +}); =item $txn = $fcp->txn_client_info @@ -273,11 +305,11 @@ =cut -_txn client_info => sub { +$txn->(client_info => sub { my ($self) = @_; $self->txn ("client_info"); -}; +}); =item $txn = $fcp->txn_generate_chk ($metadata, $data) @@ -287,11 +319,11 @@ =cut -_txn generate_chk => sub { +$txn->(generate_chk => sub { my ($self, $metadata, $data) = @_; - $self->txn (generate_chk => data => "$data$metadata", metadata_length => length $metadata); -}; + $self->txn (generate_chk => data => "$metadata$data", metadata_length => length $metadata); +}); =item $txn = $fcp->txn_generate_svk_pair @@ -306,19 +338,19 @@ =cut -_txn generate_svk_pair => sub { +$txn->(generate_svk_pair => sub { my ($self) = @_; $self->txn ("generate_svk_pair"); -}; +}); =item $txn = $fcp->txn_insert_private_key ($private) -=item $uri = $fcp->insert_private_key ($private) +=item $public = $fcp->insert_private_key ($private) Inserts a private key. $private can be either an insert URI (must start -with freenet:SSK@) or a raw private key (i.e. the private value you get back -from C). +with C) or a raw private key (i.e. the private value you get +back from C). Returns the public key. @@ -326,11 +358,11 @@ =cut -_txn insert_private_key => sub { +$txn->(insert_private_key => sub { my ($self, $privkey) = @_; $self->txn (invert_private_key => private => $privkey); -}; +}); =item $txn = $fcp->txn_get_size ($uri) @@ -343,11 +375,11 @@ =cut -_txn get_size => sub { +$txn->(get_size => sub { my ($self, $uri) = @_; $self->txn (get_size => URI => $uri); -}; +}); =item $txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]]) @@ -367,13 +399,38 @@ =cut -_txn client_get => sub { +$txn->(client_get => sub { my ($self, $uri, $htl, $removelocal) = @_; - $self->txn (client_get => URI => $uri, hops_to_live => ($htl || 15), remove_local_key => $removelocal ? "true" : "false"); -}; + $self->txn (client_get => URI => $uri, hops_to_live => (defined $htl ? $htl :15), + remove_local_key => $removelocal ? "true" : "false"); +}); + +=item $txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal) + +=item my $uri = $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal); + +Insert a new key. If the client is inserting a CHK, the URI may be +abbreviated as just CHK@. In this case, the node will calculate the +CHK. + +C<$meta> can be a reference or a string (ONLY THE STRING CASE IS IMPLEMENTED!). + +THIS INTERFACE IS UNTESTED AND SUBJECT TO CHANGE. -=item MISSING: ClientPut +=cut + +$txn->(client_put => sub { + my ($self, $uri, $meta, $data, $htl, $removelocal) = @_; + + $self->txn (client_put => URI => $uri, hops_to_live => (defined $htl ? $htl :15), + remove_local_key => $removelocal ? "true" : "false", + data => "$meta$data", metadata_length => length $meta); +}); + +} # transactions + +=item MISSING: (ClientPut), InsretKey =back @@ -487,6 +544,22 @@ $self; } +=item $txn->cancel (%attr) + +Cancels the operation with a C exception anf the given attributes +(consider at least giving the attribute C). + +UNTESTED. + +=cut + +sub cancel { + my ($self, %attr) = @_; + $self->throw (Net::FCP::Exception->new (cancel => { %attr })); + $self->set_result; + $self->eof; +} + sub fh_ready_w { my ($self) = @_; @@ -534,14 +607,6 @@ } } -sub rcv_data { - my ($self, $chunk) = @_; - - $self->{data} .= $chunk; - - $self->progress ("data", { chunk => length $chunk, total => length $self->{data}, end => $self->{datalength} }); -} - sub rcv { my ($self, $type, $attr) = @_; @@ -569,7 +634,7 @@ my ($self, $exc) = @_; $self->{exception} = $exc; - $self->set_result (1); + $self->set_result; $self->eof; # must be last to avoid loops } @@ -591,7 +656,11 @@ delete $self->{fcp}{txn}{$self}; - $self->set_result; # just in case + unless (exists $self->{result}) { + $self->throw (Net::FCP::Exception->new (short_data => { + reason => "unexpected eof or internal node error", + })); + } } sub progress { @@ -654,17 +723,15 @@ sub rcv_success { my ($self, $attr) = @_; - $self->set_result ([$attr->{PublicKey}, $attr->{PrivateKey}]); } -package Net::FCP::Txn::InvertPrivateKey; +package Net::FCP::Txn::InsertPrivateKey; use base Net::FCP::Txn; sub rcv_success { my ($self, $attr) = @_; - $self->set_result ($attr->{PublicKey}); } @@ -674,7 +741,6 @@ sub rcv_success { my ($self, $attr) = @_; - $self->set_result ($attr->{Length}); } @@ -703,32 +769,30 @@ *rcv_data_not_found = \&Net::FCP::Txn::rcv_throw_exception; -sub rcv_data_found { - my ($self, $attr, $type) = @_; - - $self->progress ($type, $attr); +sub rcv_data { + my ($self, $chunk) = @_; - $self->{datalength} = hex $attr->{data_length}; - $self->{metalength} = hex $attr->{metadata_length}; -} + $self->{data} .= $chunk; -sub eof { - my ($self) = @_; + $self->progress ("data", { chunk => length $chunk, total => length $self->{data}, end => $self->{datalength} }); if ($self->{datalength} == length $self->{data}) { my $data = delete $self->{data}; my $meta = Net::FCP::parse_metadata substr $data, 0, $self->{metalength}, ""; $self->set_result ([$meta, $data]); - } elsif (!exists $self->{result}) { - $self->throw (Net::FCP::Exception->new (short_data => { - reason => "unexpected eof or internal node error", - received => length $self->{data}, - expected => $self->{datalength}, - })); } } +sub rcv_data_found { + my ($self, $attr, $type) = @_; + + $self->progress ($type, $attr); + + $self->{datalength} = hex $attr->{data_length}; + $self->{metalength} = hex $attr->{metadata_length}; +} + package Net::FCP::Txn::ClientPut; use base Net::FCP::Txn::GetPut; @@ -746,6 +810,20 @@ $self->set_result ($attr); } +=back + +=head2 The Net::FCP::Exception CLASS + +Any unexpected (non-standard) responses that make it impossible to return +the advertised result will result in an exception being thrown when the +C method is called. + +These exceptions are represented by objects of this class. + +=over 4 + +=cut + package Net::FCP::Exception; use overload @@ -753,12 +831,50 @@ "Net::FCP::Exception<<$_[0][0]," . (join ":", %{$_[0][1]}) . ">>\n"; }; +=item $exc = new Net::FCP::Exception $type, \%attr + +Create a new exception object of the given type (a string like +C), and a hashref containing additional attributes +(usually the attributes of the message causing the exception). + +=cut + sub new { my ($class, $type, $attr) = @_; bless [Net::FCP::tolc $type, { %$attr }], $class; } +=item $exc->type([$type]) + +With no arguments, returns the exception type. Otherwise a boolean +indicating wether the exception is of the given type is returned. + +=cut + +sub type { + my ($self, $type) = @_; + + @_ >= 2 + ? $self->[0] eq $type + : $self->[0]; +} + +=item $exc->attr([$attr]) + +With no arguments, returns the attributes. Otherwise the named attribute +value is returned. + +=cut + +sub attr { + my ($self, $attr) = @_; + + @_ >= 2 + ? $self->[1]{$attr} + : $self->[1]; +} + =back =head1 SEE ALSO