[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
    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.

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. There are,
    however, certain "import tags" that can be used to select the event
    model to be used.

    Event models are implemented as modules under the "Net::FCP::Event::xyz"
    class, where "xyz" is the event model to use. The default is "Event" (or
    later "Auto").

    The import tag to use is named "event=xyz", e.g. "event=Event",
    "event=Glib" etc.

    You should specify the event module to use only in the main program.

    If no event model has been specified, FCP tries to autodetect it on
    first use (e.g. first transaction), in this order: Coro, Event, Glib,
    Tk.

  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 anf 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 <pcg@goof.com>
     http://www.goof.com/pcg/marc/

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