view README.txt @ 47:9eb5c502df01

hgbundler init new CHANGES file
author Georges Racinet on <>
date Sat, 21 Jan 2012 22:23:52 +0100
line source
1 Tramline
2 ========
4 Introduction
5 ------------
7 Tramline is a upload and download accelerator that plugs into Apache,
8 using mod_python. Its aim is to make downloading and uploading large
9 media to an application server easy and fast, without overloading the
10 application server with large amounts of binary data.
12 Tramline integrates into Apache using mod_python. The application
13 server is assumed to sit behind Apache, for instance hooked up using
14 mod_proxy or mod_rewrite.
16 Tramline takes over uploading and downloading files, handling these
17 within Apache. Only a small configuration change in Apache should be
18 necessary to enable tramline.
20 The application server remains in complete control over security, page
21 and form rendering, and everything else. Minimal changes are necessary
22 to any application to enable it to work with tramline; in fact it's
23 just setting two response headers in a few places in the code.
25 How it works
26 ------------
28 Given a 'tramline_data' directory that's accessible to Apache (and the
29 appserver if it needs to), there are two subdirectories, 'upload' and
30 'repository'. 'upload' will only contain temporary files currently
31 being uploaded, while 'repository' contains the files successfully
32 uploaded.
34 Tramline makes sure uploaded files (in a form POST) don't appear at
35 the appserver but go directly into the filesystem. The only thing the
36 appserver sees is a unique identifier of the uploaded file, so that
37 the appserver can access it when needed. The binary data is gone at
38 the time the POST reaches the appserver. You can check whether
39 tramline is in use by checking the 'tramline' header in the request,
40 though frequently there's no need to do so.
42 The appserver can control whether it accepts the uploaded file(s) in
43 the output response header; if a 'tramline_ok' header is present, the
44 uploaded files will be moved into the repository, 'committing' the
45 upload. If it's absent, the uploaded files will be removed, 'aborting'
46 the upload.
48 Tramline also can handle downloads. The appserver can signal in the
49 response headers that tramline should push a file out of the
50 filesystem to the end user, by adding a 'tramline_file' response
51 header. The data of the file body as received during upload,
52 containing the unique identifier of the file, should be sent back as
53 the response body. Again the appserver does not see the binary data
54 but only sends out an identifier to make the file be served by Apache.
56 Tramline makes it relatively easy to make an application that handled
57 large file uploads correctly without tramline installed as well. After
58 all, the application handles a tramline id just like it would handle
59 an uploaded file; the data is stored and served again. Of course
60 mixing tramline uploaded files and appserver uploaded files in the
61 same setup of your application would get complicated, but this feature
62 does make it nice to be able to test your application without tramline
63 available.
65 So:
67 * to handle upload:
69 - file contents will contain the unique file id.
71 - send out 'tramline_ok' header if file is accepted. Failure
72 to send out this header will cause the file to be rejected.
74 * to detect whether tramline took care of an upload:
76 - look for a 'tramline' header in the request.
78 * to handle download:
80 - send out 'tramline_file' header in response if the file can
81 be downloaded.
83 - send out response body with unique file id.