--- cvsroot/Net-FCP/FCP.pm	2003/09/10 05:06:16	1.13
+++ cvsroot/Net-FCP/FCP.pm	2003/09/16 07:00:59	1.21
@@ -37,6 +37,33 @@
 
 You should specify the event module to use only in the main program.
 
+If no event model has been specified, FCP tries to autodetect it on first
+use (e.g. first transaction), in this order: Coro, Event, Glib, Tk.
+
+=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<hex()> on all such numbers, as the module (currently) does nothing to
+convert these for you.
+
+=back
+
 =head2 THE Net::FCP CLASS
 
 =over 4
@@ -47,12 +74,11 @@
 
 use Carp;
 
-$VERSION = 0.05;
+$VERSION = 0.08;
 
 no warnings;
 
 our $EVENT = Net::FCP::Event::Auto::;
-$EVENT = Net::FCP::Event::Event;#d#
 
 sub import {
    shift;
@@ -60,9 +86,9 @@
    for (@_) {
       if (/^event=(\w+)$/) {
          $EVENT = "Net::FCP::Event::$1";
+         eval "require $EVENT";
       }
    }
-   eval "require $EVENT";
    die $@ if $@;
 }
 
@@ -83,30 +109,32 @@
 
 Parse a metadata string and return it.
 
-The metadata will be a hashref with key C<version> (containing
-the mandatory version header entries).
+The metadata will be a hashref with key C<version> (containing the
+mandatory version header entries) and key C<raw> containing the original
+metadata string.
 
 All other headers are represented by arrayrefs (they can be repeated).
 
-Since this is confusing, here is a rather verbose example of a parsed
-manifest:
+Since this description is confusing, here is a rather verbose example of a
+parsed manifest:
 
    (
+      raw => "Version...",
       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" },
                     }
                   ]
    )
@@ -114,9 +142,9 @@
 =cut
 
 sub parse_metadata {
-   my $meta;
-
    my $data = shift;
+   my $meta = { raw => $data };
+
    if ($data =~ /^Version\015?\012/gc) {
       my $hdr = $meta->{version} = {};
 
@@ -127,18 +155,19 @@
 
             $hdr->{$p[0]}               = $v if @p == 1; # lamest code I ever wrote
             $hdr->{$p[0]}{$p[1]}        = $v if @p == 2;
-            $hdr->{$p[0]}{$p[1]}{$p[3]} = $v if @p == 3;
+            $hdr->{$p[0]}{$p[1]}{$p[2]} = $v if @p == 3;
             die "FATAL: 4+ dot metadata"     if @p >= 4;
          }
 
          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)";
+            print STDERR "metadata format error ($1), please report this string: <<$data>>";
+            die "metadata format error";
          }
       }
    }
@@ -154,9 +183,15 @@
 127.0.0.1:8481, or the environment variables C<FREDHOST> and C<FREDPORT>).
 
 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<ClientHello> transaction.
 
+=end
+
 =cut
 
 sub new {
@@ -174,7 +209,7 @@
 
 sub progress {
    my ($self, $txn, $type, $attr) = @_;
-   warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
+   #warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
 }
 
 =item $txn = $fcp->txn(type => attr => val,...)
@@ -215,11 +250,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 +272,11 @@
 
 =cut
 
-_txn client_hello => sub {
+$txn->(client_hello => sub {
    my ($self) = @_;
 
    $self->txn ("client_hello");
-};
+});
 
 =item $txn = $fcp->txn_client_info
 
@@ -273,25 +310,29 @@
 
 =cut
 
-_txn client_info => sub {
+$txn->(client_info => sub {
    my ($self) = @_;
 
    $self->txn ("client_info");
-};
+});
 
-=item $txn = $fcp->txn_generate_chk ($metadata, $data)
+=item $txn = $fcp->txn_generate_chk ($metadata, $data[, $cipher])
 
-=item $uri = $fcp->generate_chk ($metadata, $data)
+=item $uri = $fcp->generate_chk ($metadata, $data[, $cipher])
 
-Creates a new CHK, given the metadata and data. UNTESTED.
+Calculcates a CHK, given the metadata and data. C<$cipher> is either
+C<Rijndael> or C<Twofish>, with the latter being the default.
 
 =cut
 
-_txn generate_chk => sub {
-   my ($self, $metadata, $data) = @_;
+$txn->(generate_chk => sub {
+   my ($self, $metadata, $data, $cipher) = @_;
 
-   $self->txn (generate_chk => data => "$data$metadata", metadata_length => length $metadata);
-};
+   $self->txn (generate_chk =>
+                  data => "$metadata$data",
+                  metadata_length => length $metadata,
+                  cipher => $cipher || "Twofish");
+});
 
 =item $txn = $fcp->txn_generate_svk_pair
 
@@ -306,19 +347,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<generate_svk_pair>).
+with C<freenet:SSK@>) or a raw private key (i.e. the private value you get
+back from C<generate_svk_pair>).
 
 Returns the public key.
 
@@ -326,11 +367,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 +384,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 +408,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
 
@@ -419,7 +485,7 @@
    }
 
    if (defined $data) {
-      $attr .= "DataLength=" . (length $data) . "\012";
+      $attr .= sprintf "DataLength=%x\012", length $data;
       $data = "Data\012$data";
    } else {
       $data = "EndMessage\012";
@@ -436,10 +502,10 @@
 
    $self->{sbuf} = 
       "\x00\x00\x00\x02"
-      . Net::FCP::touc $self->{type}
+      . (Net::FCP::touc $self->{type})
       . "\012$attr$data";
 
-   #$fh->shutdown (1); # freenet buggy?, well, it's java...
+   #shutdown $fh, 1; # freenet buggy?, well, it's java...
    
    $self->{fh} = $fh;
    
@@ -487,6 +553,22 @@
    $self;
 }
 
+=item $txn->cancel (%attr)
+
+Cancels the operation with a C<cancel> exception anf the given attributes
+(consider at least giving the attribute C<reason>).
+
+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 +616,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) = @_;
 
@@ -559,7 +633,7 @@
 # used as a default exception thrower
 sub rcv_throw_exception {
    my ($self, $attr, $type) = @_;
-   $self->throw (new Net::FCP::Exception $type, $attr);
+   $self->throw (Net::FCP::Exception->new ($type, $attr));
 }
 
 *rcv_failed       = \&Net::FCP::Txn::rcv_throw_exception;
@@ -569,7 +643,7 @@
    my ($self, $exc) = @_;
 
    $self->{exception} = $exc;
-   $self->set_result (1);
+   $self->set_result;
    $self->eof; # must be last to avoid loops
 }
 
@@ -591,7 +665,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 {
@@ -645,7 +723,7 @@
 sub rcv_success {
    my ($self, $attr) = @_;
 
-   $self->set_result ($attr);
+   $self->set_result ($attr->{uri});
 }
 
 package Net::FCP::Txn::GenerateSVKPair;
@@ -654,17 +732,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 +750,6 @@
 
 sub rcv_success {
    my ($self, $attr) = @_;
-
    $self->set_result ($attr->{Length});
 }
 
@@ -703,32 +778,30 @@
 
 *rcv_data_not_found = \&Net::FCP::Txn::rcv_throw_exception;
 
-sub rcv_data_found {
-   my ($self, $attr, $type) = @_;
+sub rcv_data {
+   my ($self, $chunk) = @_;
 
-   $self->progress ($type, $attr);
+   $self->{data} .= $chunk;
 
-   $self->{datalength} = hex $attr->{data_length};
-   $self->{metalength} = hex $attr->{metadata_length};
-}
-
-sub eof {
-   my ($self) = @_;
+   $self->progress ("data", { chunk => length $chunk, received => length $self->{data}, total => $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 +819,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<result> method is called.
+
+These exceptions are represented by objects of this class.
+
+=over 4
+
+=cut
+
 package Net::FCP::Exception;
 
 use overload
@@ -753,12 +840,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<route_not_found>), 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
@@ -774,5 +899,37 @@
 
 =cut
 
+package Net::FCP::Event::Auto;
+
+my @models = (
+      [Coro  => Coro::Event:: ],
+      [Event => Event::],
+      [Glib  => Glib:: ],
+      [Tk    => Tk::],
+);
+
+sub AUTOLOAD {
+   $AUTOLOAD =~ s/.*://;
+
+   for (@models) {
+      my ($model, $package) = @$_;
+      if (defined ${"$package\::VERSION"}) {
+         $EVENT = "Net::FCP::Event::$model";
+         eval "require $EVENT"; die if $@;
+         goto &{"$EVENT\::$AUTOLOAD"};
+      }
+   }
+
+   for (@models) {
+      my ($model, $package) = @$_;
+      $EVENT = "Net::FCP::Event::$model";
+      if (eval "require $EVENT") {
+         goto &{"$EVENT\::$AUTOLOAD"};
+      }
+   }
+
+   die "No event module selected for Net::FCP and autodetect failed. Install any of these: Coro, Event, Glib or Tk.";
+}
+
 1;