Source

streamtar / README.txt

================
streamtar README
================

Overview
========

``streamtar`` is a WSGI application that streams requested files and streams
tar files of requested directories.

When a directory is requested, a tar file of its contents is built on-the-fly
and streamed to the HTTP client--no intermediate files are made.


Authentication
--------------

``streamtar`` supports rudimentary token-based authentication. When enabled,
a remote HTTP service is queried in the following scenarios:


When a request is started
~~~~~~~~~~~~~~~~~~~~~~~~~

http://``{DL_AUTH_HOST}``/``{DL_AUTH_URI}``?token=``{token}``&mode=start is
queried. Any response that is not the string ``"ok"`` is considered an
authentication failure.


When a request is finished
~~~~~~~~~~~~~~~~~~~~~~~~~~

http://``{DL_AUTH_HOST}``/``{DL_AUTH_URI}``?token=``{token}``&mode=complete&\
time=``{start_time}``&filesize=``{bytes_served}`` is queried. The response is
ignored.


Statistics tracking
~~~~~~~~~~~~~~~~~~~

Authenticated requests can also be recorded to a second remote HTTP service.

When a request is finished, the following address is queried:
http://``{DL_STAT_HOST}``/``{DL_STAT_URI}``?token=``{token}``&mode=complete&\
path=``{b64_req_uri}``
The response is ignored.


XSPF Playlists
==============

When a diretory is requested and the HTTP parameter ``playlist`` is given,
an XSPF playlist of all MP3s in the directory is sent. The track list is
sorted by the order of the files' full paths alphabetically. No track
metadata is sent, other than the track title, which is the name of the file.

Note: If you have token-based authentication on, any token HTTP parameter
received will show up in the track URIs.

Usage
=====

``DL_PATHS``:
    A mapping of URI prefixes to system paths. Pairs are delimited by
    semicolons, prefixes and paths are delimited by commas.

    Examples::
        /dl,/var/dls
        /dl,/var/dls;/big-dls,/var/big-dls
        /dl,C:\dls
``DL_MAX_SIZE``:
    Forbids downloads of files or directories larger than the value in bytes.
``DL_AUTH_HOST``:
    The hostname to use for token-based authentication.

    Note: Authentication is disabled when this isn't set.
``DL_AUTH_URI``:
    The URI to query for token-based authentication.
    
    Note: Authentication is disabled when this isn't set.
``DL_STAT_HOST``:
    The hostname to use for the tracking of authenticated requests.
    
    Note: Statistics recording is disabled when this isn't set.
``DL_STAT_URI``:
    The URI to query for the tracking of authenticated requests.

    Note: Statistics recording is disabled when this isn't set.
``DL_BROKEN_URI``:
    If set, extra unescaping is done on requested URIs to compensate for
    ``mod_rewrite`` and PHP's crazy escaping behavior.
``DL_STANDALONE``:
    The hostname and port, delimited by a colon, to bind the CherryPy HTTP
    server to.

    Note: FastCGI is used instead when this isn't set.
``DL_LOG_FILE``:
    If set, redirects logging output to a file.
``DL_LOG_LEVEL``:
    Controls the level of logging. This may be one of the following:

        * ``CRITICAL``
        * ``ERROR``
        * ``WARNING``
        * ``INFO``
        * ``DEBUG``

    Note: ``WARNING`` is the default.