NAME
AnyEvent::FCP - freenet client protocol 2.0
SYNOPSIS
use AnyEvent::FCP;
my $fcp = new AnyEvent::FCP;
# transactions return condvars
my $lp_cv = $fcp->list_peers;
my $pr_cv = $fcp->list_persistent_requests;
my $peers = $lp_cv->recv;
my $reqs = $pr_cv->recv;
DESCRIPTION
This module implements the freenet client protocol version 2.0, as used
by freenet 0.7. See Net::FCP for the earlier freenet 0.5 version.
See <http://wiki.freenetproject.org/FreenetFCPSpec2Point0> for a
description of what the messages do.
The module uses AnyEvent to find a suitable event module.
Only very little is implemented, ask if you need more, and look at the
example program later in this section.
EXAMPLE
This example fetches the download list and sets the priority of all
files with "a" in their name to "emergency":
use AnyEvent::FCP;
my $fcp = new AnyEvent::FCP;
$fcp->watch_global (1, 0);
my $req = $fcp->list_persistent_requests;
TODO for my $req (values %$req) { if ($req->{filename} =~ /a/) {
$fcp->modify_persistent_request (1, $req->{identifier}, undef, 0); } }
IMPORT TAGS
Nothing much can be "imported" from this module right now.
THE AnyEvent::FCP CLASS
$fcp = new AnyEvent::FCP [host => $host][, port => $port][, name =>
$name]
Create a new FCP connection to the given host and port (default
127.0.0.1:9481, or the environment variables "FREDHOST" and
"FREDPORT").
If no "name" was specified, then AnyEvent::FCP will generate a
(hopefully) unique client name for you.
FCP REQUESTS
The following methods implement various requests. Most of them map
directory to the FCP message of the same name. The added benefit of
these over sending requests yourself is that they handle the necessary
serialisation, protocol quirks, and replies.
All of them exist in two versions, the variant shown in this manpage,
and a variant with an extra "_" at the end, and an extra $cb argument.
The version as shown is *synchronous* - it will wait for any replies,
and either return the reply, or croak with an error. The underscore
variant returns immediately and invokes one or more callbacks or
condvars later.
For example, the call
$info = $fcp->get_plugin_info ($name, $detailed);
Also comes in this underscore variant:
$fcp->get_plugin_info_ ($name, $detailed, $cb);
You can thinbk of the underscore as a kind of continuation indicator -
the normal function waits and returns with the data, the "_" indicates
that you pass the continuation yourself, and the continuation will be
invoked with the results.
This callback/continuation argument ($cb) can come in three forms
itself:
A code reference (or rather anything not matching some other
alternative)
This code reference will be invoked with the result on success. On
an error, it will die (in the event loop) with a backtrace of the
call site.
This is a popular choice, but it makes handling errors hard - make
sure you never generate protocol errors!
A condvar (as returned by e.g. "AnyEvent->condvar")
When a condvar is passed, it is sent ("$cv->send ($results)") the
results when the request has finished. Should an error occur, the
error will instead result in "$cv->croak ($error)".
This is also a popular choice.
An array with two callbacks "[$success, $failure]"
The $success callback will be invoked with the results, while the
$failure callback will be invoked on any errors.
"undef"
This is the same thing as specifying "sub { }" as callback, i.e. on
success, the results are ignored, while on failure, you the module
dies with a backtrace.
This is good for quick scripts, or when you really aren't interested
in the results.
$peers = $fcp->list_peers ([$with_metdata[, $with_volatile]])
$notes = $fcp->list_peer_notes ($node_identifier)
$fcp->watch_global ($enabled[, $verbosity_mask])
$reqs = $fcp->list_persistent_requests
$sync = $fcp->modify_persistent_request ($global, $identifier[,
$client_token[, $priority_class]])
Update either the "client_token" or "priority_class" of a request
identified by $global and $identifier, depending on which of
$client_token and $priority_class are not "undef".
$info = $fcp->get_plugin_info ($name, $detailed)
$status = $fcp->client_get ($uri, $identifier, %kv)
%kv can contain (<http://wiki.freenetproject.org/FCP2p0ClientGet>).
ignore_ds, ds_only, verbosity, max_size, max_temp_size, max_retries,
priority_class, persistence, client_token, global, return_type,
binary_blob, allowed_mime_types, filename, temp_filename
$status = $fcp->remove_request ($identifier[, $global])
Remove the request with the given isdentifier. Returns true if
successful, false on error.
($can_read, $can_write) = $fcp->test_dda ($local_directory,
$remote_directory, $want_read, $want_write))
The DDA test in FCP is probably the single most broken protocol -
only one directory test can be outstanding at any time, and some
guessing and heuristics are involved in mangling the paths.
This function combines "TestDDARequest" and "TestDDAResponse" in one
request, handling file reading and writing as well, and tries very
hard to do the right thing.
Both $local_directory and $remote_directory must specify the same
directory - $local_directory is the directory path on the client
(where AnyEvent::FCP runs) and $remote_directory is the directory
path on the server (where the freenet node runs). When both are
running on the same node, the paths are generally identical.
$want_read and $want_write should be set to a true value when you
want to read (get) files or write (put) files, respectively.
On error, an exception is thrown. Otherwise, $can_read and
$can_write indicate whether you can reaqd or write to freenet via
the directory.
REQUEST CACHE
The "AnyEvent::FCP" class keeps a request cache, where it caches all
information from requests.
For these messages, it will store a copy of the key-value pairs,
together with a "type" slot, in "$fcp->{req}{$identifier}":
persistent_get
persistent_put
persistent_put_dir
This message updates the stored data:
persistent_request_modified
This message will remove this entry:
persistent_request_removed
These messages get merged into the cache entry, under their type, i.e. a
"simple_progress" message will be stored in
"$fcp->{req}{$identifier}{simple_progress}":
simple_progress # get/put
uri_generated # put
generated_metadata # put
started_compression # put
finished_compression # put
put_failed # put
put_fetchable # put
put_successful # put
sending_to_network # get
compatibility_mode # get
expected_hashes # get
expected_mime # get
expected_data_length # get
get_failed # get
data_found # get
enter_finite_cooldown # get
In addition, an event (basically a fake message) of type
"request_changed" is generated on every change, which will be called as
"$cb->($fcp, $kv, $type)", where $type is the type of the original
message triggering the change,
To fill this cache with the global queue and keep it updated, call
"watch_global" to subscribe to updates, followed by
"list_persistent_requests_sync".
$fcp->watch_global_sync_; # do not wait
$fcp->list_persistent_requests; # wait
To get a better idea of what is stored in the cache, here is an example
of what might be stored in "$fcp->{req}{"Frost-gpl.txt"}":
{
identifier => "Frost-gpl.txt",
uri => 'CHK@Fnx5kzdrfE,EImdzaVyEWl,AAIC--8/gpl.txt',
binary_blob => "false",
global => "true",
max_retries => -1,
max_size => 9223372036854775807,
persistence => "forever",
priority_class => 3,
real_time => "false",
return_type => "direct",
started => "true",
type => "persistent_get",
verbosity => 2147483647,
sending_to_network => {
identifier => "Frost-gpl.txt",
global => "true",
},
compatibility_mode => {
identifier => "Frost-gpl.txt",
definitive => "true",
dont_compress => "false",
global => "true",
max => "COMPAT_1255",
min => "COMPAT_1255",
},
expected_hashes => {
identifier => "Frost-gpl.txt",
global => "true",
hashes => {
ed2k => "d83596f5ee3b7...",
md5 => "e0894e4a2a6...",
sha1 => "...",
sha256 => "...",
sha512 => "...",
tth => "...",
},
},
expected_mime => {
identifier => "Frost-gpl.txt",
global => "true",
metadata => { content_type => "application/rar" },
},
expected_data_length => {
identifier => "Frost-gpl.txt",
data_length => 37576,
global => "true",
},
simple_progress => {
identifier => "Frost-gpl.txt",
failed => 0,
fatally_failed => 0,
finalized_total => "true",
global => "true",
last_progress => 1438639282628,
required => 372,
succeeded => 102,
total => 747,
},
data_found => {
identifier => "Frost-gpl.txt",
completion_time => 1438663354026,
data_length => 37576,
global => "true",
metadata => { content_type => "image/jpeg" },
startup_time => 1438657196167,
},
}
EXAMPLE PROGRAM
use AnyEvent::FCP;
my $fcp = new AnyEvent::FCP;
# let us look at the global request list
$fcp->watch_global_ (1);
# list them, synchronously
my $req = $fcp->list_persistent_requests;
# go through all requests
TODO
for my $req (values %$req) {
# skip jobs not directly-to-disk
next unless $req->{return_type} eq "disk";
# skip jobs not issued by FProxy
next unless $req->{identifier} =~ /^FProxy:/;
if ($req->{data_found}) {
# file has been successfully downloaded
... move the file away
(left as exercise)
# remove the request
$fcp->remove_request (1, $req->{identifier});
} elsif ($req->{get_failed}) {
# request has failed
if ($req->{get_failed}{code} == 11) {
# too many path components, should restart
} else {
# other failure
}
} else {
# modify priorities randomly, to improve download rates
$fcp->modify_persistent_request (1, $req->{identifier}, undef, int 6 - 5 * (rand) ** 1.7)
if 0.1 > rand;
}
}
# see if the dummy plugin is loaded, to ensure all previous requests have finished.
$fcp->get_plugin_info_sync ("dummy");
SEE ALSO
<http://wiki.freenetproject.org/FreenetFCPSpec2Point0>, Net::FCP.
BUGS
AUTHOR
Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/