Package: omnibust
## Omnibust - A universal cachebusting scriptA language and framework agnostic cachbusting script.Omnibust will scan the files of your web project for static resources(js, css, png) and also for urls in your source code (html, js, css, py,rb, etc.) which reference these resources. It will add or update acachebust parameter on any such urls based on the static resources theyreference.Requires python >= 2.6 or python >= 3.2.[![Build Status](https://travis-ci.org/mbarkhau/omnibust.png)](https://travis-ci.org/mbarkhau/omnibust)### Installation$ pip install omnibustOr$ wget https://raw.github.com/mbarkhau/omnibust/master/omnibust.py$ chmod +x omnibust.py$ cp omnibust.py /usr/local/bin/omnibustCheck that it worked$ omnibust --help### UsageProject setup:$ cd your/project/directory$ omninust initThis will write the `.omnibust` file, which you can take a look at andupdate if some of your urls are not being found or scanning your projectfiles is taking too long.If this doesn't find all references to static files, or doesn't findthe static files themselves, you will have to adjust `static_dirs` and`code_dirs` in your `.omnibust` file (see below). Please also consideropening a ticket on [https://bitbucket.org/mbarkhau/omnibust], asomnibust should work out of the box for as many projects as reasonablypossible.The `rewrite` option will add a `_cb_` to every static url it canfind and associate with a static file in the project directory.CAUTION: Since `rewrite` will modify your source files, you shouldcommit or backup your files and run `omnibust status` first to makecertain it won't modify anything it shouldn't.$ omnibust status --querystring$ omnibust rewrite --querystringFrom now on you simply run omnibust rewrite on your project directoryand it will only update urls with an existing `_cb_` parameter.$ omnibust rewrite### Options and ConfigurationExplicitly specify filesTODO: parameter configuration### Dynamic URLs and MultibustSome URLs may not be found with `omnibust init`, esp. if they are not precededby something like `src=` or `url(`, and of course URLs which are dynamicallycreated during runtime cannot automatically be found at all.You can help omnibust find these by manually marking them with `_cb_`. Afterthis, you can run `omnibust update` will expand the marker to a full cachbustparameter.The `multibust` configuration option allows for a limited form of dynamic URLs.Omnibust will expand any URL using the configured `multibust` mapping. If amultibust key (typically a template variable) is found in an URL, it isexpanded using the corresponding associated multibust values. The search forstatic resources is then based on the expanded URLs.Given the configuration"multibust": {"{{ language }}": ["en", "de", "fr", "jp", "es"]}And the following URL<img src="i18n_image_{{ language }}_cb_0123abcd.png" />The following static resources may be matched for this URL/static/i18n_image_en.png/static/i18n_image_de.png...If any of these files is modified, the cachebust parameter will be updated.This method is safe (in that any change to the static resource results incache invalidation) and convenient (in that one url can be used to referencesemantically similar files), but it does mean that some cached files will beinvalidated that were still valid. If this is a problem for you, all staticfiles will have to be referenced explicitly. You could for example create amapping of the formi18n_images = {'en': "/static/i18n_image_en_cb_0123abcd.png",'de': "/static/i18n_image_de_cb_0123abcd.png",...}And reference it for example from a jinja2 template like this<img src="{{ i18n_image[language] }}" />### Webserver SetupIn order for browsers to cache and reuse your static resources, yourwebserver must set appropriate cache headers. Here are some exampleconfiguration directives for common webservers.### Filename Based CachbustingOmnibust defaults to query parameter `app.js?_cb_=0123abcd` basedcachbusting, but it can also rewrite the filenames in urls to the form`app_cb_0123abcd.js`. This is useful since URLs with query parameters are notcached by all browsers in all situations, even if all caching headers areprovided correctly [needs reference]. TODO: check if there are browsers wherea cached resource will be used even if the query string changes.Putting a cachebust parameter in the filename of a URL will guarantee that yourstatic resource is loaded when it has changed and it will be cached in moresituations. The downside is, that your urls now have filenames which referencefiles that don't actually exist! (Assuming you don't create them, which wouldbe quite laborious and error prone.) The sollution is to have your webserverrewrite the urls of requests it recieves, by stripping out the cachebustparameter, and serving the correct static resource. Here are someconfiguration directives for common webservers.# Nginxlocation ~* ^/static/(.+?)_cb_\w+(\.\w+)$ {alias /srv/www/static/$1$2;add_header Vary Accept-Encoding;expires max;}# ApacheRewriteRule ^/static/(.+?)_cb_\w+(\.\w+)$ /static/$1$2Copyright (c) 2012-2013 Manuel Barkhau, <mbarkhau@gmail.com>All rights reserved.Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditions are met:1. Redistributions of source code must retain the above copyright notice,this list of conditions and the following disclaimer.2. Redistributions in binary form must reproduce the above copyright notice,this list of conditions and the following disclaimer in the documentationand/or other materials provided with the distribution.THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSEARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BELIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;CONSEQUENTIAL DAMAGES LOSS OF USE, DATA, OR PROFITS; OR BUSINESSINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER INCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY OF SUCH DAMAGE.