[ViewVC] Annotation of: cvs/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
    This module implements the first version of the freenet client protocol,
    for use with freenet versions 0.5. For freenet protocol version 2.0
    support (as used by freenet 0.7), see the AnyEvent::FCP module.

    See <http://freenet.sourceforge.net/index.php?page=fcp> for a
    description of what the messages do.

    The module uses AnyEvent to find a suitable Event module.

  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.14
Committed:	Thu May 1 15:30:34 2008 UTC (16 years ago) by root
Branch:	MAIN
CVS Tags:	rel-1_2, HEAD
Changes since 1.13:	+5 -7 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.14	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	root	1.2	See <http://freenet.sourceforge.net/index.php?page=fcp> for a
18	root	1.14	description of what the messages do.
19	root	1.2
20	root	1.13	The module uses AnyEvent to find a suitable Event module.
21
22	root	1.5	IMPORT TAGS
23	root	1.13	Nothing much can be "imported" from this module right now.
24	root	1.8
25	root	1.7	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	root	1.2	THE Net::FCP CLASS
43	root	1.10	$fcp = new Net::FCP [host => $host][, port => $port][, progress => \&cb]
44	root	1.2	Create a new virtual FCP connection to the given host and port
45	root	1.3	(default 127.0.0.1:8481, or the environment variables "FREDHOST" and
46			"FREDPORT").
47	root	1.2
48			Connections are virtual because no persistent physical connection is
49	root	1.7	established.
50	root	1.2
51	root	1.10	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	root	1.11	$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	root	1.6
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	root	1.2	$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	root	1.3	node => "Fred,0.6,1.46,7050"
93	root	1.2	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	root	1.3	datastore_free => "5ce03400",
106			datastore_max => "2540be400",
107	root	1.2	datastore_used => "1f72bb000",
108	root	1.3	estimated_load => 52,
109			free_memory => "5cc0148",
110	root	1.2	is_transient => "false",
111	root	1.3	java_name => "Java HotSpot(_T_M) Server VM",
112	root	1.2	java_vendor => "http://www.blackdown.org/",
113	root	1.3	java_version => "Blackdown-1.4.1-01",
114			least_recent_timestamp => "f41538b878",
115			max_file_size => "5f5e100",
116	root	1.2	most_recent_timestamp => "f77e2cc520"
117	root	1.3	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	root	1.2	}
123
124	root	1.8	$txn = $fcp->txn_generate_chk ($metadata, $data[, $cipher])
125			$uri = $fcp->generate_chk ($metadata, $data[, $cipher])
126	root	1.10	Calculates a CHK, given the metadata and data. $cipher is either
127	root	1.8	"Rijndael" or "Twofish", with the latter being the default.
128	root	1.2
129			$txn = $fcp->txn_generate_svk_pair
130	root	1.11	($public, $private, $crypto) = @{ $fcp->generate_svk_pair }
131	root	1.10	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	root	1.2
134			[
135	root	1.10	"acLx4dux9fvvABH15Gk6~d3I-yw",
136			"cPoDkDMXDGSMM32plaPZDhJDxSs",
137			"BH7LXCov0w51-y9i~BoB3g",
138	root	1.2	]
139
140	root	1.10	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	root	1.2
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	root	1.3	$txn = $fcp->txn_client_get ($uri [, $htl = 15 [, $removelocal = 0]])
166	root	1.4	($metadata, $data) = @{ $fcp->client_get ($uri, $htl, $removelocal)
167	root	1.11	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	root	1.3
170	root	1.10	The $uri should begin with "freenet:", but the scheme is currently
171			added, if missing.
172	root	1.3
173	root	1.4	my ($meta, $data) = @{
174	root	1.3	$fcp->client_get (
175			"freenet:CHK@hdXaxkwZ9rA8-SidT0AN-bniQlgPAwI,XdCDmBuGsd-ulqbLnZ8v~w"
176			)
177			};
178
179	root	1.7	$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	root	1.10	CHK. If the key is a private SSK key, the node will calculcate the
184			public key and the resulting public URI.
185	root	1.7
186	root	1.10	$meta can be a hash reference (same format as returned by
187			"Net::FCP::parse_metadata") or a string.
188	root	1.7
189	root	1.10	The result is an arrayref with the keys "uri", "public_key" and
190			"private_key".
191	root	1.2
192			THE Net::FCP::Txn CLASS
193	root	1.9	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	root	1.2
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	root	1.1
202	root	1.2	new arg => val,...
203			Creates a new "Net::FCP::Txn" object. Not normally used.
204	root	1.5
205	root	1.6	$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	root	1.1
226	root	1.7	$txn->cancel (%attr)
227	root	1.12	Cancels the operation with a "cancel" exception and the given
228	root	1.7	attributes (consider at least giving the attribute "reason").
229
230			UNTESTED.
231
232	root	1.2	$result = $txn->result
233			Waits until a result is available and then returns it.
234	root	1.1
235	root	1.3	This waiting is (depending on your event model) not very efficient,
236	root	1.9	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	root	1.7
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	root	1.1
262	root	1.2	SEE ALSO
263			<http://freenet.sf.net>.
264	root	1.1
265	root	1.2	BUGS
266	root	1.1	AUTHOR
267	root	1.12	Marc Lehmann <schmorp@schmorp.de>
268			http://home.schmorp.de/
269	root	1.1