Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 133 lines (77 sloc) 6.931 kB
f5abbf8 initial version
Jeremy Bornstein authored
1 BASTARD
2 =======
3
4 The purpose of bastard is to serve static content over the web quickly, according to best practices, in a way that is easy to set up, run, and administer. It is implemented as a module intended to be run from within node.js. It may be invoked as part of another server process, serving only URLs with a given set of prefixes, or it may be the entire server all on its own. It will automatically minify and compress data, cache the data on disk, and verify the validity of its cached data on startup. While running, it keeps cached data in memory and does not expire data from the cache. Restarts should be relatively quick and easy because minified/compressed data will be read from the disk cache on the first request for that item.
5
6 Additionally, bastard will automatically generate cryptographic fingerprints for all files it serves. You can programmatically ask it for the current fingerprinted URL for a file so that you can use that URL in HTML you generate external to the server. When bastard serves fingerprinted files, they are served with very long cache times because those URLs should always serve the same content.
7
8 Both CSS and Javascript are minified, and HTML will probably be added soon. Files of other types are not touched, though they will be compressed if they're not image files. (Image files are never gzipped by this software.)
9
10
11 Installing
12 ==========
13
14 npm install bastard
15
16
17 Running Standalone
18 ==================
19
20 Configure the settings via npm. There are reasonable defaults but you definitely need to specify the base directory where your files are:
21
22 npm config bastard:base /path/with/good/intentions
23 npm start bastard
24
25 If you are running the standalone server and want to programmatically find out the current fingerprint for a file, make a request for the file with an incorrect fingerprint such as "BASTARD". The server's response will contain the valid fingerprint, which you may then parse out and use in your own externally-generated HTML.
26
27
28 Running from your own code
29 ==========================
30
31 1. Create the bastard object:
32
33 var bastard = require ('bastard');
34 var Bastard = bastard.Bastard;
35 var bastardObj = new Bastard (config);
36
37 // if you want to load every file into the cache before you get started:
38 bastardObj.loadEveryFile (callback);
39
40 2. Create your own HttpServer object and pass requests to it from within the associated handler:
41
42 var handled = bastardObj.possiblyHandleRequest (request, response);
43
44 If the above function returns true, the request has been handled and you don't need to do anything else. Depending on how you want to structure your server, you can check bastard before or after your own URLs.
45
46
47 3. To find out the current fingerprint of a file:
48
49 bastardObj.getFingerprint (filePath, basePath, callback);
50
51 * filePath: full path to the file
52 * basePath: path to the file within the base directory (may be the same as the URL path for the file)
53 * callback: if present, will be called with the first argument being any error (or null) and the second argument being the fingerprint
54
55 If callback is not present and the fingerprint is already known, it will be returned immediately as the result of the function call. If callback is not present and the fingerprint is not already known, the fingerprint will be internally calculated and null will be returned from the function call.
56
57 You only need to specify one of filePath and basePath.
58
59 For an example of how to run bastard from your own code, examine the file start.js in the bastard package.
60
61
62 Configuration
63 =============
64
65 host Hostname or IP address at which to listen. If empty, will bind to all available IP addresses. (Default: empty)
66
67 port Port number at which to listen. (Default: 80)
68
69 base Directory where files to be served reside. (Default: empty)
70
71 rawURLPrefix The prefix for URLs from which raw files should be served. These will be just as they are on disk: not minified, not compressed. (Default: /raw/)
72
73 fingerprintURLPrefix The prefix for URLs from which fingerprinted files should be served. The fingerprint will appear in the URLs after this prefix followed by the relative pathname to the file in the base directory. (Default: /f/)
74
75 urlPrefix The prefix for URLs from which non-fingerprinted files should be served.
76
77 workingDir The location for temporary files to be kept. This includes on-disk copies of minified and compressed files that originate in the base directory. (Default: /tmp/bastard.dat)
78
79 debug If true, turns on some debugging functionality. (Default: false)
80
81 directories If true, will generate directory listings. (Not yet implemented.) (Default: false)
82
83
84
85 Note that first the raw prefix is checked, then the fingerprint prefix, and then only the regular prefix--and the first match is considered to be definitive. This means that with the default values, if you have a directory called "raw" in your base directory, those files will never be served.
86
87
88 Limitations
89 ===========
90
91 If the mime type for a file begins with "image/", it will not be gzipped. All other files will be gzipped if the client indicates that it can understand gzipped data. This may not be the best choice for all file types.
92
93 Does not do virtual hosting.
94
95
96 Project Status
97 ==============
98
99 This is a project built by the author for his own use. Contributions are welcomed.
100
101 The public repository for the project is found at: TK
102
103
104 License
105 =======
106
107 Copyright 2011, Jeremy Bornstein <jeremy@jeremy.org>
108 All rights reserved.
109
110 Redistribution and use in source and binary forms, with or without
111 modification, are permitted provided that the following conditions are met:
112
113 * Redistributions of source code must retain the above copyright
114 notice, this list of conditions and the following disclaimer.
115
116 * Redistributions in binary form must reproduce the above copyright
117 notice, this list of conditions and the following disclaimer in the
118 documentation and/or other materials provided with the distribution.
119
120 * Neither the name of the <organization> nor the
121 names of its contributors may be used to endorse or promote products
122 derived from this software without specific prior written permission.
123
124 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
125 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
126 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
127 DISCLAIMED. IN NO EVENT SHALL JEREMY BORNSTEIN BE LIABLE FOR ANY
128 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
129 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
130 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
131 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
132 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
133 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Something went wrong with that request. Please try again.