Untitled

TWINK SPECIFICATION v.1.0
-------------------------

by John Hoffman, 2004.

Twink is a P2P-amplified web page service system, designed to assist overloaded
("Slashdotted") web servers.  It requires a browser plug-in or proxy on the
client side, and a few easy-to-automate arrangements on the server side.
It provides a large amount of control over the caching, allowing static
portions of pages containing active content to be buffered without disruption.


SERVER SIDE:
------------

* "twink.txt"

The Twink protocol is controlled by a text file in the same directory as the
web page being fetched.  For instance, a Twink-enabled browser that was being
used to surf to "http://somewhere.com/dir/index.html" would first attempt to
read "http://somewhere.com/dir/twink.txt".  If this failed, the browser would
then read the index page normally.

The format of the text file is similar to that of robots.txt:  Any line
beginning with # is considered a comment.  The format of a line is:
<field> ":" <value>.  Currently, there are only three fields used (and
required) for a twink.txt file: "hash", "tracker", and "archive".

"hash" is the SHA1 hash in hexadecimal format for a .tar.bz2 file containing
a mirror of the directory the twink.txt file resides in, including
subdirectories.  The next step is for the browser to obtain a copy of this
file and extract it into its cache area.  Further pages fetched from within
the same directory should also be read from this cache.

"tracker" is the URL for a script that assists the browser in connecting to
other peers; see below for more details.

"archive" is a URL from which the browser may download a copy of the .tar.bz2
mirror file.  This may simply be a copy of the archive available via http, or
it may point to a script designed to moderate access to the archive and so
prevent the server from becoming overloaded.  If the http response to this
request is 503, the body of the return may consist of an ASCII integer value
specifying how long the browser should wait before retrying the download.
(If the body of the return differs from this, then it should be considered
to be a standard 503 return.)  In the meantime, the browser may continue to
attempt to obtain the data via the P2P network.

Example:

#---- sample twink.txt file
hash: 0123456789ABCDEF0123456789ABCDEF01234567
tracker: http://somewhere.com/tracker.php
archive: http://somewhere.com/archive.php?source=dir
#---- end of sample


* the tracker

The Twink-enabled browser should contact the tracker script with the
following format:

<script url>?hash=<hexadecimal hash>&port=<listening port>
Where the hexadecimal hash is the same one provided in twink.txt, and the
listening port is the port where the Twink-enabled browser is open for
incoming peer connections.

Example:

http://somewhere.com/tracker.php?hash=0123456789ABCDEF0123456789ABCDEF01234567&port=6221

Normally, the tracker should return a status 200 and a bencoded(1) dict
object with the following possible keys:  "ip", and "ip6".  If the tracker
returns a status 101 (switching protocols) or 404 (not found), the browser
should then attempt to fetch the page via standard http.  The browser
should directly display any other response.

Both the "ip" and "ip6" keys contain strings which themselves contain
binary-encoded blocks of data specifying peer addresses and ports.  For
"ip", each peer entry is 6 bytes, 4 bytes containing the IP and 2 bytes
containing the port in big-endian format.  For "ip6" each peer entry is
18 bytes, with 16 containing an IPv6 address and 2 containing the port as
above.  The client should support gzipped responses, though this is only
likely to help for IPv6 data.  The tracker should return the last 20
peers which accessed it in the last 60 seconds for that particular
archive.


<!--#include virtual="data.html" -->


(1) http://fx.saintjoe.edu/pub/CPAN/authors/id/O/OR/ORCLEV/Convert-Bencode-1.03.readme