--- cvsroot/Net-FCP/FCP.pm	2003/09/17 08:57:32	1.23
+++ cvsroot/Net-FCP/FCP.pm	2004/05/14 17:25:17	1.32
@@ -74,10 +74,13 @@
 
 use Carp;
 
-$VERSION = 0.5;
+$VERSION = 0.7;
 
 no warnings;
 
+use Net::FCP::Metadata;
+use Net::FCP::Util qw(tolc touc xeh);
+
 our $EVENT = Net::FCP::Event::Auto::;
 
 sub import {
@@ -92,97 +95,7 @@
    die $@ if $@;
 }
 
-sub touc($) {
-   local $_ = shift;
-   1 while s/((?:^|_)(?:svk|chk|uri)(?:_|$))/\U$1/;
-   s/(?:^|_)(.)/\U$1/g;
-   $_;
-}
-
-sub tolc($) {
-   local $_ = shift;
-   s/(?<=[a-z])(?=[A-Z])/_/g;
-   lc $_;
-}
-
-# the opposite of hex
-sub xeh($) {
-   sprintf "%x", $_[0];
-}
-
-=item $meta = Net::FCP::parse_metadata $string
-
-Parse a metadata string and return it.
-
-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 description is confusing, here is a rather verbose example of a
-parsed manifest:
-
-   (
-      raw => "Version...",
-      version => { revision => 1 },
-      document => [
-                    {
-                      info => { format" => "image/jpeg" },
-                      name => "background.jpg",
-                      redirect => { target => "freenet:CHK\@ZcagI,ra726bSw" },
-                    },
-                    {
-                      info => { format" => "text/html" },
-                      name => ".next",
-                      redirect => { target => "freenet:SSK\@ilUPAgM/TFEE/3" },
-                    },
-                    {
-                      info => { format" => "text/html" },
-                      redirect => { target => "freenet:CHK\@8M8Po8ucwI,8xA" },
-                    }
-                  ]
-   )
-
-=cut
-
-sub parse_metadata {
-   my $data = shift;
-   my $meta = { raw => $data };
-
-   if ($data =~ /^Version\015?\012/gc) {
-      my $hdr = $meta->{version} = {};
-
-      for (;;) {
-         while ($data =~ /\G([^=\015\012]+)=([^\015\012]*)\015?\012/gc) {
-            my ($k, $v) = ($1, $2);
-            my @p = split /\./, tolc $k, 3;
-
-            $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[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) {
-            last;
-         } elsif ($data =~ /\G([A-Za-z0-9.\-]+)\015?\012/gcs) {
-            push @{$meta->{tolc $1}}, $hdr = {};
-         } elsif ($data =~ /\G(.*)/gcs) {
-            print STDERR "metadata format error ($1), please report this string: <<$data>>";
-            die "metadata format error";
-         }
-      }
-   }
-
-   #$meta->{tail} = substr $data, pos $data;
-
-   $meta;
-}
-
-=item $fcp = new Net::FCP [host => $host][, port => $port]
+=item $fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb]
 
 Create a new virtual FCP connection to the given host and port (default
 127.0.0.1:8481, or the environment variables C<FREDHOST> and C<FREDPORT>).
@@ -190,12 +103,15 @@
 Connections are virtual because no persistent physical connection is
 established.
 
-=begin comment
+You can install a progress callback that is being called with the Net::FCP
+object, a txn object, the type of the transaction and the attributes. Use
+it like this:
 
-However, the existance of the node is checked by executing a
-C<ClientHello> transaction.
+   sub progress_cb {
+      my ($self, $txn, $type, $attr) = @_;
 
-=end
+      warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
+   }
 
 =cut
 
@@ -206,22 +122,20 @@
    $self->{host} ||= $ENV{FREDHOST} || "127.0.0.1";
    $self->{port} ||= $ENV{FREDPORT} || 8481;
 
-   #$self->{nodehello} = $self->client_hello
-   #   or croak "unable to get nodehello from node\n";
-
    $self;
 }
 
 sub progress {
    my ($self, $txn, $type, $attr) = @_;
-   #warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
-}
 
-=item $txn = $fcp->txn(type => attr => val,...)
+   $self->{progress}->($self, $txn, $type, $attr)
+      if $self->{progress};
+}
 
-The low-level interface to transactions. Don't use it.
+=item $txn = $fcp->txn (type => attr => val,...)
 
-Here are some examples of using transactions:
+The low-level interface to transactions. Don't use it unless you have
+"special needs". Instead, use predefiend transactions like this:
 
 The blocking case, no (visible) transactions involved:
 
@@ -250,7 +164,7 @@
 
    $type = touc $type;
 
-   my $txn = "Net::FCP::Txn::$type"->new(fcp => $self, type => tolc $type, attr => \%attr);
+   my $txn = "Net::FCP::Txn::$type"->new (fcp => $self, type => tolc $type, attr => \%attr);
 
    $txn;
 }
@@ -325,7 +239,7 @@
 
 =item $uri = $fcp->generate_chk ($metadata, $data[, $cipher])
 
-Calculcates a CHK, given the metadata and data. C<$cipher> is either
+Calculates a CHK, given the metadata and data. C<$cipher> is either
 C<Rijndael> or C<Twofish>, with the latter being the default.
 
 =cut
@@ -333,23 +247,37 @@
 $txn->(generate_chk => sub {
    my ($self, $metadata, $data, $cipher) = @_;
 
+   $metadata = Net::FCP::Metadata::build_metadata $metadata;
+
    $self->txn (generate_chk =>
-                  data => "$metadata$data",
-                  metadata_length => xeh length $metadata,
-                  cipher => $cipher || "Twofish");
+               data => "$metadata$data",
+               metadata_length => xeh length $metadata,
+               cipher => $cipher || "Twofish");
 });
 
 =item $txn = $fcp->txn_generate_svk_pair
 
-=item ($public, $private) = @{ $fcp->generate_svk_pair }
+=item ($public, $private, $crypto) = @{ $fcp->generate_svk_pair }
 
-Creates a new SVK pair. Returns an arrayref.
+Creates a new SVK pair. Returns an arrayref with the public key, the
+private key and a crypto key, which is just additional entropy.
 
    [
-     "hKs0-WDQA4pVZyMPKNFsK1zapWY",
-     "ZnmvMITaTXBMFGl4~jrjuyWxOWg"
+     "acLx4dux9fvvABH15Gk6~d3I-yw",
+     "cPoDkDMXDGSMM32plaPZDhJDxSs",
+     "BH7LXCov0w51-y9i~BoB3g",
    ]
 
+A private key (for inserting) can be constructed like this:
+
+   SSK@<private_key>,<crypto_key>/<name>
+
+It can be used to insert data. The corresponding public key looks like this:
+
+   SSK@<public_key>PAgM,<crypto_key>/<name>
+
+Watch out for the C<PAgM>-part!
+
 =cut
 
 $txn->(generate_svk_pair => sub {
@@ -358,21 +286,19 @@
    $self->txn ("generate_svk_pair");
 });
 
-=item $txn = $fcp->txn_insert_private_key ($private)
+=item $txn = $fcp->txn_invert_private_key ($private)
 
-=item $public = $fcp->insert_private_key ($private)
+=item $public = $fcp->invert_private_key ($private)
 
-Inserts a private key. $private can be either an insert URI (must start
-with C<freenet:SSK@>) or a raw private key (i.e. the private value you get
-back from C<generate_svk_pair>).
+Inverts a private key (returns the public key). C<$private> can be either
+an insert URI (must start 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.
 
-UNTESTED.
-
 =cut
 
-$txn->(insert_private_key => sub {
+$txn->(invert_private_key => sub {
    my ($self, $privkey) = @_;
 
    $self->txn (invert_private_key => private => $privkey);
@@ -385,8 +311,6 @@
 Finds and returns the size (rounded up to the nearest power of two) of the
 given document.
 
-UNTESTED.
-
 =cut
 
 $txn->(get_size => sub {
@@ -399,11 +323,11 @@
 
 =item ($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
 
-Fetches a (small, as it should fit into memory) file from
-freenet. C<$meta> is the metadata (as returned by C<parse_metadata> or
-C<undef>).
+Fetches a (small, as it should fit into memory) key content block from
+freenet. C<$meta> is a C<Net::FCP::Metadata> object or C<undef>).
 
-Due to the overhead, a better method to download big files should be used.
+The C<$uri> should begin with C<freenet:>, but the scheme is currently
+added, if missing.
 
   my ($meta, $data) = @{
      $fcp->client_get (
@@ -416,6 +340,8 @@
 $txn->(client_get => sub {
    my ($self, $uri, $htl, $removelocal) = @_;
 
+   $uri =~ s/^freenet://; $uri = "freenet:$uri";
+
    $self->txn (client_get => URI => $uri, hops_to_live => xeh (defined $htl ? $htl : 15),
                remove_local_key => $removelocal ? "true" : "false");
 });
@@ -426,26 +352,30 @@
 
 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.
+CHK. If the key is a private SSK key, the node will calculcate the public
+key and the resulting public URI.
 
-C<$meta> can be a reference or a string (ONLY THE STRING CASE IS IMPLEMENTED!).
+C<$meta> can be a hash reference (same format as returned by
+C<Net::FCP::parse_metadata>) or a string.
 
-THIS INTERFACE IS UNTESTED AND SUBJECT TO CHANGE.
+The result is an arrayref with the keys C<uri>, C<public_key> and C<private_key>.
 
 =cut
 
 $txn->(client_put => sub {
-   my ($self, $uri, $meta, $data, $htl, $removelocal) = @_;
+   my ($self, $uri, $metadata, $data, $htl, $removelocal) = @_;
 
-   $self->txn (client_put => URI => $uri, xeh (defined $htl ? $htl : 15),
+   $metadata = Net::FCP::Metadata::build_metadata $metadata;
+   $uri =~ s/^freenet://; $uri = "freenet:$uri";
+
+   $self->txn (client_put => URI => $uri,
+               hops_to_live => xeh (defined $htl ? $htl : 15),
                remove_local_key => $removelocal ? "true" : "false",
-               data => "$meta$data", metadata_length => xeh length $meta);
+               data => "$metadata$data", metadata_length => xeh length $metadata);
 });
 
 } # transactions
 
-=item MISSING: (ClientPut), InsertKey
-
 =back
 
 =head2 THE Net::FCP::Txn CLASS
@@ -679,6 +609,7 @@
 
 sub progress {
    my ($self, $type, $attr) = @_;
+
    $self->{fcp}->progress ($self, $type, $attr);
 }
 
@@ -740,16 +671,16 @@
 
 sub rcv_success {
    my ($self, $attr) = @_;
-   $self->set_result ([$attr->{PublicKey}, $attr->{PrivateKey}]);
+   $self->set_result ([$attr->{public_key}, $attr->{private_key}, $attr->{crypto_key}]);
 }
 
-package Net::FCP::Txn::InsertPrivateKey;
+package Net::FCP::Txn::InvertPrivateKey;
 
 use base Net::FCP::Txn;
 
 sub rcv_success {
    my ($self, $attr) = @_;
-   $self->set_result ($attr->{PublicKey});
+   $self->set_result ($attr->{public_key});
 }
 
 package Net::FCP::Txn::GetSize;
@@ -758,7 +689,7 @@
 
 sub rcv_success {
    my ($self, $attr) = @_;
-   $self->set_result (hex $attr->{Length});
+   $self->set_result (hex $attr->{length});
 }
 
 package Net::FCP::Txn::GetPut;
@@ -767,8 +698,8 @@
 
 use base Net::FCP::Txn;
 
-*rcv_uri_error        = \&Net::FCP::Txn::rcv_throw_exception;
-*rcv_route_not_found  = \&Net::FCP::Txn::rcv_throw_exception;
+*rcv_uri_error       = \&Net::FCP::Txn::rcv_throw_exception;
+*rcv_route_not_found = \&Net::FCP::Txn::rcv_throw_exception;
 
 sub rcv_restarted {
    my ($self, $attr, $type) = @_;
@@ -795,7 +726,7 @@
 
    if ($self->{datalength} == length $self->{data}) {
       my $data = delete $self->{data};
-      my $meta = Net::FCP::parse_metadata substr $data, 0, $self->{metalength}, "";
+      my $meta = new Net::FCP::Metadata (substr $data, 0, $self->{metalength}, "");
 
       $self->set_result ([$meta, $data]);
       $self->eof;
@@ -816,7 +747,6 @@
 use base Net::FCP::Txn::GetPut;
 
 *rcv_size_error    = \&Net::FCP::Txn::rcv_throw_exception;
-*rcv_key_collision = \&Net::FCP::Txn::rcv_throw_exception;
 
 sub rcv_pending {
    my ($self, $attr, $type) = @_;
@@ -828,6 +758,11 @@
    $self->set_result ($attr);
 }
 
+sub rcv_key_collision {
+   my ($self, $attr, $type) = @_;
+   $self->set_result ({ key_collision => 1, %$attr });
+}
+
 =back
 
 =head2 The Net::FCP::Exception CLASS
@@ -911,9 +846,9 @@
 package Net::FCP::Event::Auto;
 
 my @models = (
-      [Coro  => Coro::Event:: ],
+      [Coro  => Coro::Event::],
       [Event => Event::],
-      [Glib  => Glib:: ],
+      [Glib  => Glib::],
       [Tk    => Tk::],
 );