Here is a document I just finished - comments are welcome: Freenet Client Protocol Layer #3 : Stacks Draft
Introduction ------------ This document is an informal description of the third layer of the Freenet Client Protocol (FCP). It allows higher level operations involving Freenet inserts and requests, which are of a time-consuming nature. The idea is to allow a client to initiate a lenghtly operation, which the server will execute, allowing the client to terminate. Notation -------- I will adopt a Java-like syntax to describe the functionality exposed by FCP#3. This is only approximate, a more formal specification will be required prior to implementation. A simple example: [Reading stacks, buckets, and callbacks] --------------------------------------------------------------------- : The simplest example of such an operation would be finding the last item on a stack. To do this the following method would be called: void getLast(String stackPrefix, String bucket); stackPrefix is the name of the stack, it may be the first part of a SSK if a private stack, or a KSK if a public stack. For example, if the stack was called "freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/" then the entries or "slots" in the stack would be: freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/0 freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/1 freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/2 freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/3 freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/4 etc... "bucket" is a string representing a place where the result may be stored on completion. To retrieve the contents of a bucket a client uses the following function: String readBucket(String bucket); This will return the contents of "bucket", or null if bucket is empty. The implementation will also allow the client to request a callback when the bucket is filled, using the following function: void requestCallback(String bucket, int timeout, int port); If bucket is filled before timeout (an integer value expressed in seconds), then a TCP connection is opened to the client on port "port", and the name of the bucket, a carriage return, followed by the contents of "bucket" are sent down the pipe, before closing it. If the bucket is already full then this will occur immediately, so the listening port should be setup prior to calling this function. Appending to a Stack -------------------- There are two types of stack, verified, and unverified. To append to an unverified stack, it is simply nescessary to append to the next available slot. This can be achieved using the following method: void appendUnv(String stack, String data [, String bucket]); This will append the data in "data" to the stack "stack". If there is a bucket parameter, then the value "success" will be placed in the bucket on success, or "failure: xxx" on failure, where xxx is a human-readable reason for the failure. To append to a verified stack, use this function: void appendVer(String stack, String data [, String bucket]); In this case, the server will first obtain the name of a "verify" stack, which will be under the key stack+"verify", such as: freenet:SSK at enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/verify This will probably be an SSK so that only the intended recepient can verify receipt of data. After inserting data to the next available slot, the server will periodically check for a confirmation, which will be data inserted in the corresponding position in the verify stack, which will contain a SHA1 hash in Freenet's base-64 representation (as used in CHKs) of the inserted data. If this is not forthcoming within a given time period (maybe 1 hour), then the data will be inserted in the next slot, but with a metadata key of "repost" where the data will be the position of the original reposted item. A server reading this should verify both this data, and the reposted version by inserting the string "timeout" in the original slot which it obviously didn't receive. Other operations ---------------- There are a number of other possible operations, for example, it may be desirable to download items other than the last item in the stack: void getNth(String stack, int n, String bucket); This command operates in a similar manner to "getLast" but instead gets the Nth item in the stack, where n=0 refers to the first item. If the item cannot be retrieved, then an empty string is placed in the bucket. -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 232 bytes Desc: not available URL: <https://emu.freenetproject.org/pipermail/devl/attachments/20010430/78302f50/attachment.pgp>
