Here's an outline and example section (metadata) for a Freenet RFC. Please subject it to an appropriate ammount of ridicule. Especially check my thinking on the BNF syntax and nroff formatting. Also, should this be one RFC or 2 or even 3? What about a definitions or glossary section? The text is mostly straight from the website, so expect the language and style to change to suite the "RFC style" later.
Any feedback at all is welcome.
rfc.nroff
Description: nroff source
Undecided Status
Freenet Project Bill Glover
Category: Experimental May 2002
Expires: November 2002 (TBD) others
Protocols for Freenet
(An Anonymous, Secure, Peer-to-Peer Network)
Status of this Memo
(TBD) Discover and relate the status of this document. ;) This
document is not an IETF document as yet. It has no status with IETF
and is not as yet a part of the Standards process. Every attempt has
been made to follow the IETF format for an Internet-Draft document in
order to facillitate possible later submission.
This document is being distributed to developers and interested
parties associated with the Freenet Project. Distribution is
Unlimited.
Copyright Notice
Copyright (C) Freenet Project Inc. All Rights Reserved.
Abstract
This document describes a protocol for communication between Freenet
nodes. Also described is a protocol for communication between a
Freenet node and a client application and a specification for the
representation of metadata within Freenet communications. (TBD) flesh
this out.
Glover [Page 1]
Undecided-Status May 2002
Table of Contents
Status of this Memo.......................................... 1
1. Introduction............................................. 2
2. Issues To Consider....................................... ?
3. Freenet Node Protocol.................................... ?
4. Freenet Client Protocol.................................. ?
5. Metadata Specification................................... ?
5.1 Overview............................................. ?
5.2 Part Specification................................... ?
5.2.1 Redirect [CDC]................................. ?
5.2.1 DateRidirect [CDC]............................. ?
5.2.1 SplitFile [CDC]................................ ?
5.2.1 Info [MC]...................................... ?
5.2.1 ExtInfo [MC]................................... ?
5.3 Examples............................................. ?
5.4 Handling Other Commands.............................. ?
6. References............................................... ?
7. Security Considerations.................................. ?
8. Contributors............................................. ?
9. Acknowledgements......................................... ?
10. Authors' Addresses....................................... ?
11. Full Copyright Statement................................. ?
1. Introduction
(TBD)
2. Issues to Consider
(TBD)
3. Freenet Node Protocol
(TBD)
4. Freenet Client Protocol
(TBD)
5. Metadata Specification
The metadata specification is for client metadata. The purpose of
this specification is to provide convenient functionality for
building web sites inside freenet.
Glover [Page 2]
Undecided-Status May 2002
5.1 Overview
Metadata is composed of a "Version" command, followed by set of "Parts."
A Part is composed of a name for the Part, followed by a number of fields,
followed by "EndPart" (or "End" for the last Part).
A "Version" command is composed of a Part with the name "Version" and a
field called "Revision" of type number. This is 1 for the current spec.
Following that an optional "Encoding" field allows for all non-version
parts to be gzipped.
The formal syntax:
<metadata> ::= <version_command> [{part} <last_part>] <binary_data>
<version_command> ::= Version "0
Revision "=" <number> "0
[ Encoding "=" <encoding_value> "0 ]
EndPart "0
<part> ::= Document "0 {field} End "0
<last_part> ::= Document "0 {field} End "0
<field> ::= <key> "=" <field_value> "0
<number> ::= {digit}
<binary_data> ::= a stream of bytes
<key> ::= <letter> {<letter> | <digit>}
<field_value> ::= {<letter> | <digit>}
<letter> ::= a-zA-Z
<digit> ::= a-fA-F0-9
<encoding_value> ::= gzip
Example 1. Abstract Metadata Format
Version
Revision=1
EndPart
Document
Key=value
EndPart
Document
Key1=value1
Key2=value2
End
Note
"//" in a URI is reserved for metadata processing. Document Names are the
string which comes after the "//". Each Part should have a field with key
"Name". The Part whose Name matches the Document Name should be acted upon.
The order of keys in a Part is not important, and if the same Key appears
Glover [Page 3]
Undecided-Status May 2002
twice in a part, only the last one's value is used.
Note
All numbers are base 16
Control Document Commands are denoted [CDC] and metadata commands as [MC]
There may only be one section with the same Name
5.2 Part Specification
Specification for document "Parts"
5.2.1 Redirect [CDC]
(TBD more narrative)
Redirect.Target=<URI:>
The Client should redirect to the given URI
5.2.2 DateRedirect [CDC]
[DateRedirect.Increment=<number: time-grain size in seconds, default=15180 (one
day)>]
[DateRedirect.Offset=<number
time-grain in seconds since unix epoch (January 1, 1970) to start increments,
default = 0>] DateRedirect?.Target=<URI:>
*
The date format is in UNIX format - seconds from the epoch
*
Only applies to KSKs and SSKs
*
The date must be taken UTC (TZ offset = 0)
The client should take the current time (GMT) and work out the last member
of the series of times (offset, offset + i, offset + 2i, offset + 3i, ...)
which occurred. The client then replaces the part of the URI after the final
slash (/string) with <DATE>-string where <DATE> is the hex encoded number of
seconds since the epoch.
Note
"freenet:" is speced otherwise someone could do something like "http://...";
In the case of KSKs, the human readable part is the whole key, so
freenet:KSK@style becomes freenet:KSK@3b4cf86e-style
Glover [Page 4]
Undecided-Status May 2002
In the case of SSKs, the human readable part is the document name, and
freenet:SSK@aabbccddee/style becomes freenet:SSK@aabbccddee/3b4cf86e-style
5.2.3 SplitFile [CDC]
SplitFile.Size=<hex file size>
SplitFile.BlockCount=<hex no. of data blocks>
[SplitFile.CheckBlockCount=<hex. no of check blocks>]
SplitFile.Block.<n>=<URI>
[SplitFile.Graph.<x>=a,b,c...]
*
0 <= n <= 65535
*
n must be sequential, starting with 1, in the metadata part
*
n is represented in base 16
The document is made up of a number of pieces, allowing swarming.
Note
thanks much to thelema, oierw, mjr and others for this
Size Required
This defines the final size of the original file.
BlockCount Required
This defines the number of pieces of data that there are.
CheckBlockCount Optional
This defines the number of check pieces that there are. If Omitted, should
default to 0.
Block.<n> Required
These are the block URIs, most likely CHKs. These must be numbered 1 to
BlockCount+CheckBlockCount. The first BlockCount blocks are the data blocks,
and the next CheckBlockCount are the check blocks.
From the above, a client can start a swarmed download of the file. Redundant
splitting is optional, and information is below.
Graph.<x> Optional
For each check Block.<x>, there must be a Graph.<x> listing the data blocks
Glover [Page 5]
Undecided-Status May 2002
that check block derives from. Graph entries for 1..BlockCount should not be
given, but for BlockCount+1..BlockCount+CheckBlockCount must be given. A
check block may also be derived from other check blocks, but only lower
numbered one
5.2.4 Info [MC]
[Info.Format=<string: MIME-type>]
[Info.Description=<string
freeform>]
The Info.* namespace is reserved for Dublin Core metadata. Prepend "Info."
to the keys you want to use to prevent collisions. See
http://www.freenetproject.org/doc/infometadata.html for details.
Format is the proper place to put the document's mime type. Description is
a Plain description of this data, not an abstract or TOC
5.2.5 ExtInfo [MC]
[ExtInfo.Trailing=yes]
[ExtInfo.URI=<URI>]
If ExtInfo.Trailing is set to yes, the metadata for this file will include
all data after the final "End" in the control document. If the ExtInfo.URI
parameter exists, the contents of the URI pointed to should be included in
the metadata for the current document
5.3 Examples
Example 2. Pseudo Website
Version
Revision=1
EndPart?
Document
Redirect.Target=CHK@aabbccddee
EndPart?
Document
Name=split
SplitFile?.Size=102400
SplitFile?.BlockCount=3
SplitFile?.Block.1=freenet:CHK@aabbccddee1
SplitFile?.Block.2=freenet:CHK@aabbccddee2
SplitFile?.Block.3=freenet:CHK@aabbccddee3
Info.Format=text/plain
Glover [Page 6]
Undecided-Status May 2002
EndPart?
Document
Name=date-redirect
DateRedirect?.Increment=93a80
DateRedirect?.Offset=a8c0
DateRedirect?.Target=SSK@aabbccddee/something
End
This would declare a sort of website. Assume it is inserted under
freenet:SSK@aabbccddee/mysite. Accessing freenet:SSK@aabbccddee/mysite or
freenet:SSK@aabbccddee/mysite// would cause the first redirect (without a Name) to be
processed.
If freenet:SSK@aabbccddee/mysite//split were accessed the SplitFile? section would
be processed, as would the Info section. This would (hopefully) swarm a file, with
some configurable concurrency. None of the CHKs being swarmed need any metadata
because it's included in the control document.
If freenet:SSK@aabbccddee/mysite//date-redirect were accessed the DateRedirect?
section would be processed. This would redirect to some other URI.
Example 3. TrailingInfo? example
Version
Revision=1
EndPart?
Document
Redirect.Target=CHK@aabbccddee
ExtInfo?.Trailing=yes
EndPart?
Document
Name=doc1
Redirect.Target=CHK@aabbccddee1
Info.Format=text/plain
ExtInfo?.Trailing=yes
EndPart?
Document
Name=doc2
DateRedirect?.Target=SSK@aabbccddee/something
ExtInfo?.URI=CHK@eeddccbbaa
End
<XML blah blah>
blah blah
</XML>
This describes the same website as above, but with metadata in a trailing field.
It's completely reasonable for multiple documents to share the same TrailingInfo?
metadata. (Since only one needs to be processed, this shouldn't be a problem)
6. References
(TBD)
7. Security Considerations
(TBD)
Glover [Page 7]
Undecided-Status May 2002
8. Contributors
(TBD)
9. Acknowledgements
(TBD)
10. Author's Addresses:
Bill Glover
Amarillo, Texas
[EMAIL PROTECTED]
(TBD) Others
11. Full Copyright Statement
(TBD)
Glover [Page 8]
