| 1 |
NAME |
| 2 |
Net::FCP - http://freenet.sf.net client protocol |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Net::FCP; |
| 6 |
|
| 7 |
my $fcp = new Net::FCP; |
| 8 |
|
| 9 |
my $ni = $fcp->txn_node_info->result; |
| 10 |
my $ni = $fcp->node_info; |
| 11 |
|
| 12 |
DESCRIPTION |
| 13 |
This module implements the first version of the freenet client protocol, |
| 14 |
for use with freenet versions 0.5. For freenet protocol version 2.0 |
| 15 |
support (as used by freenet 0.7), see the AnyEvent::FCP module. |
| 16 |
|
| 17 |
See <http://freenet.sourceforge.net/index.php?page=fcp> for a |
| 18 |
description of what the messages do. |
| 19 |
|
| 20 |
The module uses AnyEvent to find a suitable Event module. |
| 21 |
|
| 22 |
IMPORT TAGS |
| 23 |
Nothing much can be "imported" from this module right now. |
| 24 |
|
| 25 |
FREENET BASICS |
| 26 |
Ok, this section will not explain any freenet basics to you, just some |
| 27 |
problems I found that you might want to avoid: |
| 28 |
|
| 29 |
freenet URIs are _NOT_ URIs |
| 30 |
Whenever a "uri" is required by the protocol, freenet expects a kind |
| 31 |
of URI prefixed with the "freenet:" scheme, e.g. "freenet:CHK...". |
| 32 |
However, these are not URIs, as freeent fails to parse them |
| 33 |
correctly, that is, you must unescape an escaped characters ("%2c" |
| 34 |
=> ",") yourself. Maybe in the future this library will do it for |
| 35 |
you, so watch out for this incompatible change. |
| 36 |
|
| 37 |
Numbers are in HEX |
| 38 |
Virtually every number in the FCP protocol is in hex. Be sure to use |
| 39 |
"hex()" on all such numbers, as the module (currently) does nothing |
| 40 |
to convert these for you. |
| 41 |
|
| 42 |
THE Net::FCP CLASS |
| 43 |
$fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb] |
| 44 |
Create a new virtual FCP connection to the given host and port |
| 45 |
(default 127.0.0.1:8481, or the environment variables "FREDHOST" and |
| 46 |
"FREDPORT"). |
| 47 |
|
| 48 |
Connections are virtual because no persistent physical connection is |
| 49 |
established. |
| 50 |
|
| 51 |
You can install a progress callback that is being called with the |
| 52 |
Net::FCP object, a txn object, the type of the transaction and the |
| 53 |
attributes. Use it like this: |
| 54 |
|
| 55 |
sub progress_cb { |
| 56 |
my ($self, $txn, $type, $attr) = @_; |
| 57 |
|
| 58 |
warn "progress<$txn,$type," . (join ":", %$attr) . ">\n"; |
| 59 |
} |
| 60 |
|
| 61 |
$txn = $fcp->txn (type => attr => val,...) |
| 62 |
The low-level interface to transactions. Don't use it unless you |
| 63 |
have "special needs". Instead, use predefiend transactions like |
| 64 |
this: |
| 65 |
|
| 66 |
The blocking case, no (visible) transactions involved: |
| 67 |
|
| 68 |
my $nodehello = $fcp->client_hello; |
| 69 |
|
| 70 |
A transaction used in a blocking fashion: |
| 71 |
|
| 72 |
my $txn = $fcp->txn_client_hello; |
| 73 |
... |
| 74 |
my $nodehello = $txn->result; |
| 75 |
|
| 76 |
Or shorter: |
| 77 |
|
| 78 |
my $nodehello = $fcp->txn_client_hello->result; |
| 79 |
|
| 80 |
Setting callbacks: |
| 81 |
|
| 82 |
$fcp->txn_client_hello->cb( |
| 83 |
sub { my $nodehello => $_[0]->result } |
| 84 |
); |
| 85 |
|
| 86 |
$txn = $fcp->txn_client_hello |
| 87 |
$nodehello = $fcp->client_hello |
| 88 |
Executes a ClientHello request and returns it's results. |
| 89 |
|
| 90 |
{ |
| 91 |
max_file_size => "5f5e100", |
| 92 |
node => "Fred,0.6,1.46,7050" |
| 93 |
protocol => "1.2", |
| 94 |
} |
| 95 |
|
| 96 |
$txn = $fcp->txn_client_info |
| 97 |
$nodeinfo = $fcp->client_info |
| 98 |
Executes a ClientInfo request and returns it's results. |
| 99 |
|
| 100 |
{ |
| 101 |
active_jobs => "1f", |
| 102 |
allocated_memory => "bde0000", |
| 103 |
architecture => "i386", |
| 104 |
available_threads => 17, |
| 105 |
datastore_free => "5ce03400", |
| 106 |
datastore_max => "2540be400", |
| 107 |
datastore_used => "1f72bb000", |
| 108 |
estimated_load => 52, |
| 109 |
free_memory => "5cc0148", |
| 110 |
is_transient => "false", |
| 111 |
java_name => "Java HotSpot(_T_M) Server VM", |
| 112 |
java_vendor => "http://www.blackdown.org/", |
| 113 |
java_version => "Blackdown-1.4.1-01", |
| 114 |
least_recent_timestamp => "f41538b878", |
| 115 |
max_file_size => "5f5e100", |
| 116 |
most_recent_timestamp => "f77e2cc520" |
| 117 |
node_address => "1.2.3.4", |
| 118 |
node_port => 369, |
| 119 |
operating_system => "Linux", |
| 120 |
operating_system_version => "2.4.20", |
| 121 |
routing_time => "a5", |
| 122 |
} |
| 123 |
|
| 124 |
$txn = $fcp->txn_generate_chk ($metadata, $data[, $cipher]) |
| 125 |
$uri = $fcp->generate_chk ($metadata, $data[, $cipher]) |
| 126 |
Calculates a CHK, given the metadata and data. $cipher is either |
| 127 |
"Rijndael" or "Twofish", with the latter being the default. |
| 128 |
|
| 129 |
$txn = $fcp->txn_generate_svk_pair |
| 130 |
($public, $private, $crypto) = @{ $fcp->generate_svk_pair } |
| 131 |
Creates a new SVK pair. Returns an arrayref with the public key, the |
| 132 |
private key and a crypto key, which is just additional entropy. |
| 133 |
|
| 134 |
[ |
| 135 |
"acLx4dux9fvvABH15Gk6~d3I-yw", |
| 136 |
"cPoDkDMXDGSMM32plaPZDhJDxSs", |
| 137 |
"BH7LXCov0w51-y9i~BoB3g", |
| 138 |
] |
| 139 |
|
| 140 |
A private key (for inserting) can be constructed like this: |
| 141 |
|
| 142 |
SSK@<private_key>,<crypto_key>/<name> |
| 143 |
|
| 144 |
It can be used to insert data. The corresponding public key looks |
| 145 |
like this: |
| 146 |
|
| 147 |
SSK@<public_key>PAgM,<crypto_key>/<name> |
| 148 |
|
| 149 |
Watch out for the "PAgM"-part! |
| 150 |
|
| 151 |
$txn = $fcp->txn_invert_private_key ($private) |
| 152 |
$public = $fcp->invert_private_key ($private) |
| 153 |
Inverts a private key (returns the public key). $private can be |
| 154 |
either an insert URI (must start with "freenet:SSK@") or a raw |
| 155 |
private key (i.e. the private value you get back from |
| 156 |
"generate_svk_pair"). |
| 157 |
|
| 158 |
Returns the public key. |
| 159 |
|
| 160 |
$txn = $fcp->txn_get_size ($uri) |
| 161 |
$length = $fcp->get_size ($uri) |
| 162 |
Finds and returns the size (rounded up to the nearest power of two) |
| 163 |
of the given document. |
| 164 |
|
| 165 |
$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]]) |
| 166 |
($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal) |
| 167 |
Fetches a (small, as it should fit into memory) key content block |
| 168 |
from freenet. $meta is a "Net::FCP::Metadata" object or "undef"). |
| 169 |
|
| 170 |
The $uri should begin with "freenet:", but the scheme is currently |
| 171 |
added, if missing. |
| 172 |
|
| 173 |
my ($meta, $data) = @{ |
| 174 |
$fcp->client_get ( |
| 175 |
"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w" |
| 176 |
) |
| 177 |
}; |
| 178 |
|
| 179 |
$txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal) |
| 180 |
my $uri = $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal); |
| 181 |
Insert a new key. If the client is inserting a CHK, the URI may be |
| 182 |
abbreviated as just CHK@. In this case, the node will calculate the |
| 183 |
CHK. If the key is a private SSK key, the node will calculcate the |
| 184 |
public key and the resulting public URI. |
| 185 |
|
| 186 |
$meta can be a hash reference (same format as returned by |
| 187 |
"Net::FCP::parse_metadata") or a string. |
| 188 |
|
| 189 |
The result is an arrayref with the keys "uri", "public_key" and |
| 190 |
"private_key". |
| 191 |
|
| 192 |
THE Net::FCP::Txn CLASS |
| 193 |
All requests (or transactions) are executed in a asynchronous way. For |
| 194 |
each request, a "Net::FCP::Txn" object is created (worse: a tcp |
| 195 |
connection is created, too). |
| 196 |
|
| 197 |
For each request there is actually a different subclass (and it's |
| 198 |
possible to subclass these, although of course not documented). |
| 199 |
|
| 200 |
The most interesting method is "result". |
| 201 |
|
| 202 |
new arg => val,... |
| 203 |
Creates a new "Net::FCP::Txn" object. Not normally used. |
| 204 |
|
| 205 |
$txn = $txn->cb ($coderef) |
| 206 |
Sets a callback to be called when the request is finished. The |
| 207 |
coderef will be called with the txn as it's sole argument, so it has |
| 208 |
to call "result" itself. |
| 209 |
|
| 210 |
Returns the txn object, useful for chaining. |
| 211 |
|
| 212 |
Example: |
| 213 |
|
| 214 |
$fcp->txn_client_get ("freenet:CHK....") |
| 215 |
->userdata ("ehrm") |
| 216 |
->cb(sub { |
| 217 |
my $data = shift->result; |
| 218 |
}); |
| 219 |
|
| 220 |
$txn = $txn->userdata ([$userdata]) |
| 221 |
Set user-specific data. This is useful in progress callbacks. The |
| 222 |
data can be accessed using "$txn->{userdata}". |
| 223 |
|
| 224 |
Returns the txn object, useful for chaining. |
| 225 |
|
| 226 |
$txn->cancel (%attr) |
| 227 |
Cancels the operation with a "cancel" exception and the given |
| 228 |
attributes (consider at least giving the attribute "reason"). |
| 229 |
|
| 230 |
UNTESTED. |
| 231 |
|
| 232 |
$result = $txn->result |
| 233 |
Waits until a result is available and then returns it. |
| 234 |
|
| 235 |
This waiting is (depending on your event model) not very efficient, |
| 236 |
as it is done outside the "mainloop". The biggest problem, however, |
| 237 |
is that it's blocking one thread of execution. Try to use the |
| 238 |
callback mechanism, if possible, and call result from within the |
| 239 |
callback (or after is has been run), as then no waiting is |
| 240 |
necessary. |
| 241 |
|
| 242 |
The Net::FCP::Exception CLASS |
| 243 |
Any unexpected (non-standard) responses that make it impossible to |
| 244 |
return the advertised result will result in an exception being thrown |
| 245 |
when the "result" method is called. |
| 246 |
|
| 247 |
These exceptions are represented by objects of this class. |
| 248 |
|
| 249 |
$exc = new Net::FCP::Exception $type, \%attr |
| 250 |
Create a new exception object of the given type (a string like |
| 251 |
"route_not_found"), and a hashref containing additional attributes |
| 252 |
(usually the attributes of the message causing the exception). |
| 253 |
|
| 254 |
$exc->type([$type]) |
| 255 |
With no arguments, returns the exception type. Otherwise a boolean |
| 256 |
indicating wether the exception is of the given type is returned. |
| 257 |
|
| 258 |
$exc->attr([$attr]) |
| 259 |
With no arguments, returns the attributes. Otherwise the named |
| 260 |
attribute value is returned. |
| 261 |
|
| 262 |
SEE ALSO |
| 263 |
<http://freenet.sf.net>. |
| 264 |
|
| 265 |
BUGS |
| 266 |
AUTHOR |
| 267 |
Marc Lehmann <schmorp@schmorp.de> |
| 268 |
http://home.schmorp.de/ |
| 269 |
|
