[ViewVC] Annotation of: cvs/cvsroot/Net-FCP/README

NAME
    Net::FCP - http://freenet.sf.net client protocol

SYNOPSIS
     use Net::FCP;

     my $fcp = new Net::FCP;

     my $ni = $fcp->txn_node_info->result;
     my $ni = $fcp->node_info;

DESCRIPTION
    See <http://freenet.sourceforge.net/index.php?page=fcp> for a
    description of what the messages do. I am too lazy to document all this
    here.

    The module uses AnyEvent to find a suitable Event module.

WARNING
    This module is alpha. While it probably won't destroy (much :) of your
    data, it currently falls short of what it should provide (intelligent
    uri following, splitfile downloads, healing...)

  IMPORT TAGS
    Nothing much can be "imported" from this module right now.

  FREENET BASICS
    Ok, this section will not explain any freenet basics to you, just some
    problems I found that you might want to avoid:

    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.

    Numbers are in HEX
        Virtually every number in the FCP protocol is in hex. Be sure to use
        "hex()" on all such numbers, as the module (currently) does nothing
        to convert these for you.

  THE Net::FCP CLASS
    $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 "FREDHOST" and
        "FREDPORT").

        Connections are virtual because no persistent physical connection is
        established.

        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:

           sub progress_cb {
              my ($self, $txn, $type, $attr) = @_;

              warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
           }

    $txn = $fcp->txn (type => attr => val,...)
        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:

           my $nodehello = $fcp->client_hello;

        A transaction used in a blocking fashion:

           my $txn = $fcp->txn_client_hello;
           ...
           my $nodehello = $txn->result;

        Or shorter:

           my $nodehello = $fcp->txn_client_hello->result;

        Setting callbacks:

           $fcp->txn_client_hello->cb(
              sub { my $nodehello => $_[0]->result }
           );

    $txn = $fcp->txn_client_hello
    $nodehello = $fcp->client_hello
        Executes a ClientHello request and returns it's results.

           {
             max_file_size => "5f5e100",
             node => "Fred,0.6,1.46,7050"
             protocol => "1.2",
           }

    $txn = $fcp->txn_client_info
    $nodeinfo = $fcp->client_info
        Executes a ClientInfo request and returns it's results.

           {
             active_jobs => "1f",
             allocated_memory => "bde0000",
             architecture => "i386",
             available_threads => 17,
             datastore_free => "5ce03400",
             datastore_max => "2540be400",
             datastore_used => "1f72bb000",
             estimated_load => 52,
             free_memory => "5cc0148",
             is_transient => "false",
             java_name => "Java HotSpot(_T_M) Server VM",
             java_vendor => "http://www.blackdown.org/",
             java_version => "Blackdown-1.4.1-01",
             least_recent_timestamp => "f41538b878",
             max_file_size => "5f5e100",
             most_recent_timestamp => "f77e2cc520"
             node_address => "1.2.3.4",
             node_port => 369,
             operating_system => "Linux",
             operating_system_version => "2.4.20",
             routing_time => "a5",
           }

    $txn = $fcp->txn_generate_chk ($metadata, $data[, $cipher])
    $uri = $fcp->generate_chk ($metadata, $data[, $cipher])
        Calculates a CHK, given the metadata and data. $cipher is either
        "Rijndael" or "Twofish", with the latter being the default.

    $txn = $fcp->txn_generate_svk_pair
    ($public, $private, $crypto) = @{ $fcp->generate_svk_pair }
        Creates a new SVK pair. Returns an arrayref with the public key, the
        private key and a crypto key, which is just additional entropy.

           [
             "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 "PAgM"-part!

    $txn = $fcp->txn_invert_private_key ($private)
    $public = $fcp->invert_private_key ($private)
        Inverts a private key (returns the public 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
        "generate_svk_pair").

        Returns the public key.

    $txn = $fcp->txn_get_size ($uri)
    $length = $fcp->get_size ($uri)
        Finds and returns the size (rounded up to the nearest power of two)
        of the given document.

    $txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
    ($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
        Fetches a (small, as it should fit into memory) key content block
        from freenet. $meta is a "Net::FCP::Metadata" object or "undef").

        The $uri should begin with "freenet:", but the scheme is currently
        added, if missing.

          my ($meta, $data) = @{
             $fcp->client_get (
                "freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
             )
          };

    $txn = $fcp->txn_client_put ($uri, $metadata, $data, $htl, $removelocal)
    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. If the key is a private SSK key, the node will calculcate the
        public key and the resulting public URI.

        $meta can be a hash reference (same format as returned by
        "Net::FCP::parse_metadata") or a string.

        The result is an arrayref with the keys "uri", "public_key" and
        "private_key".

  THE Net::FCP::Txn CLASS
    All requests (or transactions) are executed in a asynchronous way. For
    each request, a "Net::FCP::Txn" object is created (worse: a tcp
    connection is created, too).

    For each request there is actually a different subclass (and it's
    possible to subclass these, although of course not documented).

    The most interesting method is "result".

    new arg => val,...
        Creates a new "Net::FCP::Txn" object. Not normally used.

    $txn = $txn->cb ($coderef)
        Sets a callback to be called when the request is finished. The
        coderef will be called with the txn as it's sole argument, so it has
        to call "result" itself.

        Returns the txn object, useful for chaining.

        Example:

           $fcp->txn_client_get ("freenet:CHK....")
              ->userdata ("ehrm")
              ->cb(sub {
                 my $data = shift->result;
              });

    $txn = $txn->userdata ([$userdata])
        Set user-specific data. This is useful in progress callbacks. The
        data can be accessed using "$txn->{userdata}".

        Returns the txn object, useful for chaining.

    $txn->cancel (%attr)
        Cancels the operation with a "cancel" exception and the given
        attributes (consider at least giving the attribute "reason").

        UNTESTED.

    $result = $txn->result
        Waits until a result is available and then returns it.

        This waiting is (depending on your event model) not very efficient,
        as it is done outside the "mainloop". The biggest problem, however,
        is that it's blocking one thread of execution. Try to use the
        callback mechanism, if possible, and call result from within the
        callback (or after is has been run), as then no waiting is
        necessary.

  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 "result" method is called.

    These exceptions are represented by objects of this class.

    $exc = new Net::FCP::Exception $type, \%attr
        Create a new exception object of the given type (a string like
        "route_not_found"), and a hashref containing additional attributes
        (usually the attributes of the message causing the exception).

    $exc->type([$type])
        With no arguments, returns the exception type. Otherwise a boolean
        indicating wether the exception is of the given type is returned.

    $exc->attr([$attr])
        With no arguments, returns the attributes. Otherwise the named
        attribute value is returned.

SEE ALSO
    <http://freenet.sf.net>.

BUGS
AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

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