Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 160 lines (91 sloc) 9.458 kb
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
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
e9574c23 » Jeremy Bornstein
2011-12-05 better explanation, mention etag
6 Additionally, bastard will automatically generate cryptographic fingerprints for all files it serves, and return this fingerprint as the value of the Etag header in its responses. Files are available at fingerprinted URLs so that they can be cached indefinitely by client browsers. 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.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
7
e9574c23 » Jeremy Bornstein
2011-12-05 better explanation, mention etag
8 CSS, Javascript, and HTML are minified. Files of other types are not modified, though they will be compressed for transmission if they're not image files. (Image files are never compressed by this software.) Note that in some rare cases, HTML minification can cause problems. In bastard, the HTML minification is not extremely aggressive and so will probably be fine. You can turn it off with a future config option if you are worried or actually find a problem in practice.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
9
10
11 Installing
12 ==========
13
411e7e88 » Jeremy Bornstein
2011-12-04 formatting
14 npm install bastard
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
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
411e7e88 » Jeremy Bornstein
2011-12-04 formatting
22 npm config bastard:base /path/with/good/intentions
23 npm start bastard
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
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
411e7e88 » Jeremy Bornstein
2011-12-04 formatting
33 var bastard = require ('bastard');
34 var Bastard = bastard.Bastard;
35 var bastardObj = new Bastard (config);
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
36
411e7e88 » Jeremy Bornstein
2011-12-04 formatting
37 // if you want to load every file into the cache before you get started:
38 bastardObj.preload (callback);
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
39
40 2. Create your own HttpServer object and pass requests to it from within the associated handler:
41
411e7e88 » Jeremy Bornstein
2011-12-04 formatting
42 var handled = bastardObj.possiblyHandleRequest (request, response);
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
43
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
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.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
45
46
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
47 To find out the current fingerprint of a file
48 ---------------------------------------------
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
49
9d052418 » Jeremy Bornstein
2011-12-05 more
50 bastardObj.getFingerprint (filePath, basePath, function (err, fingerprint) {});
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
51
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
52 * `filePath`: full path to the file
53 * `basePath`: path to the file within the base directory (may be the same as the URL path for the file)
54 * `callback`: if present, will be called with the first argument being any error (or null) and the second argument being the fingerprint
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
55
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
56 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.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
57
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
58 You only need to specify one of filePath and basePath.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
59
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
60 For an example of how to run bastard from your own code, examine the file start.js in the bastard package.
61
62 To preload the entire base directory
63 ------------------------------------
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
64
9d052418 » Jeremy Bornstein
2011-12-05 more
65
66 bastardObj.preload (function (err) {});
67
661b6e6b » Jeremy Bornstein
2011-12-05 tidy
68 Calling this function and waiting until the callback is invoked will ensure that all fingerprints have been precalculated before any user requests are seen. It does not load all files into memory, but does load all information about each file, and ensure that each file has been minified (where possible) and compressed (when appropriate).
9d052418 » Jeremy Bornstein
2011-12-05 more
69
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
70
71 Configuration
72 =============
73
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
74 The following configuration variables may be set with `npm config bastard:xxx yyy` where `xxx` is the name of the parameter and `yyy` is the desired value. More help on configuration variables may be obtained via `npm`. These variables also correspond to keys which may be present in single argument to the `Bastard` object's constructor. (In the constructor, however, the URL patterns all default to null--that is, not checked.)
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
75
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
76 Note that there are some not-too-complicated subtleties in URL matching. The raw prefix, if defined, is checked first, followed by the fingerprint prefix (if defined), and then only the regular prefix (if defined)--and the first match is considered to be definitive. This means that with the default values provided in the standalone server, if you have a directory called "raw" in your base directory, those files will never be served except as raw or fingerprinted.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
77
78
a972eab1 » Jeremy Bornstein
2011-12-04 clarification and format improvements
79 `base` Directory where files to be served reside. (Default: empty)
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
80
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
81 `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/)
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
82
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
83 `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/)
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
84
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
85 `urlPrefix` The prefix for URLs from which non-fingerprinted files should be served. (Default: /)
83b7461d » Jeremy Bornstein
2011-12-04 add new configuration variable to documentation
86
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
87 `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)
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
88
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
89 `debug` If true, turns on some debugging functionality. (Default: false)
90
91 `directories` If true, will generate directory listings. (Not yet implemented.) (Default: false)
a972eab1 » Jeremy Bornstein
2011-12-04 clarification and format improvements
92
93
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
94 Standalone Server
95 -----------------
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
96
9d052418 » Jeremy Bornstein
2011-12-05 more
97 In addition, the following configuration parameters are used only by the standalone server and do not correspond to constructor arguments:
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
98
c803b793 » Jeremy Bornstein
2011-12-05 clarify and fix
99 `host` Hostname or IP address at which to listen. If empty, will bind to all available IP addresses. (Default: empty)
100
101 `port` Port number at which to listen. (Default: 80)
102
103 `preload` If true, a cache record will be created for each available file before the server begins. This will not load all data from disk, but will calculate all new fingerprints necessary.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
104
105
106
107 Limitations
108 ===========
109
110 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.
111
5de10f12 » Jeremy Bornstein
2011-12-04 clarification
112 Does not do virtual hosting. If you want virtual hosting, create a new Bastard object for each host.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
113
114
115 Project Status
116 ==============
117
118 This is a project built by the author for his own use. Contributions are welcomed.
119
b0fce15a » Jeremy Bornstein
2011-12-03 update project repository url
120 The public repository for the project is found at: https://github.com/unprolix/bastard
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
121
3dba96d8 » Jeremy Bornstein
2011-12-03 Update documentation and bump version
122 Future features:
123
124 * Ability to use an API, instead of the filesystem, as the source of files to be served. This would allow serving data from (e.g.) key/value stores.
125
a972eab1 » Jeremy Bornstein
2011-12-04 clarification and format improvements
126 * Ability to use an API to upload processed files from base directory to a key/value store--including fingerprinted URLs. This would allow bastard to front for a CDN.
3dba96d8 » Jeremy Bornstein
2011-12-03 Update documentation and bump version
127
25e3726d » Jeremy Bornstein
2011-12-05 new future feature described
128 * Minify CSS and Javascript embedded in HTML.
3dba96d8 » Jeremy Bornstein
2011-12-03 Update documentation and bump version
129
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
130
131 License
132 =======
133
134 Copyright 2011, Jeremy Bornstein <jeremy@jeremy.org>
135 All rights reserved.
136
137 Redistribution and use in source and binary forms, with or without
138 modification, are permitted provided that the following conditions are met:
139
140 * Redistributions of source code must retain the above copyright
141 notice, this list of conditions and the following disclaimer.
142
143 * Redistributions in binary form must reproduce the above copyright
144 notice, this list of conditions and the following disclaimer in the
145 documentation and/or other materials provided with the distribution.
146
78e0c03e » Jeremy Bornstein
2011-12-03 tidy
147 * Neither the name of the project nor the names of its contributors may
148 be used to endorse or promote products derived from this software
149 without specific prior written permission.
f5abbf89 » Jeremy Bornstein
2011-12-03 initial version
150
151 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
152 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
153 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
154 DISCLAIMED. IN NO EVENT SHALL JEREMY BORNSTEIN BE LIABLE FOR ANY
155 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
156 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
157 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
158 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
159 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
160 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Something went wrong with that request. Please try again.