This is the clack-static-asset-middleware Reference Manual, version 1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 05:35:31 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
clack-static-asset-middlewareA cache busting static file middleware for the clack web framework.
Matt Novenstern
MIT
# Clack-Static-Asset-Middleware
[](https://travis-ci.org/fisxoj/clack-static-asset-middleware) [](https://coveralls.io/github/fisxoj/clack-static-asset-middleware?branch=master)[](http://quickdocs.org/clack-static-asset-middleware/)
The static asset middleware is for handling versioned static assets. That means that, when the assets of your webapp change, it will be referred to by a different filename, allowing a browser to instantly know that it needs to download a new file. Assets are served with the maximum cache time headers set so browsers will never ask for them again.
It comes with the ‘clack-static-asset-djula-helpers‘ package which extends the djula templating language to allow inserting cache busted urls for your files easily.
## Usage
Use by wrapping your clack app in ‘clack-static-asset-middleware:*clack-static-asset-middleware*‘.
“‘lisp
(funcall clack-static-asset-middleware:*clack-static-asset-middleware*
clack-app
:root (asdf:system-relative-pathname :webapp #p"static/")
:path "static/")
“‘
It can be configured by specifying:
- ‘path‘: the path on your app that you want your assets to be served from. That is ‘https://my-webapp.com/{path}/images/some-sheep_12..532.png‘.
- ‘root‘: The root directory that your assets reside in on the filesystem.
- ‘cache-buster-function‘: A function of two arguments ‘(pathname cache-string)‘ that generates an appropriate, cache-busted name for a file. The default creates filenames like ‘images/some-sheep_12421345423fea543265cf43226512a6.png‘.
- ‘cache-unbuster-function‘: A function that takes a cache-busted url and resolves it to the un-busted filename.
- ‘filter-function‘: A function that identifies files that should not be served but are in the ‘root‘ directory anyway. It acceps a pathname and return a boolean where ‘t‘ means ’do not serve’ and ‘nil‘ means the file is good to serve. By default, it blocks files beginnig with a ‘.‘, which would be hidden on a UNIX filesystem.
Once you have done that, you can call ‘busted-uri-for-path‘ to convert a relative path on your system into an appropriate cache busted url suitable for inserting into templating and showing your friends. There is a helper package for accessing this functionality within the [Djula](https://github.com/mmontone/) templating language below.
### Real-World Usage
This middleware is not optimized to serve files. It should not be particularly slow, but it was not designed to be your CDN. In real-world situations, you should consider putting a CDN or nginx proxy in front of your app for best performance. I have not done this, yet, but it’s probably something I should work on.
Ideally, you might set this up behind an nginx reverse proxy and let it handle un-busting your URLs like so:
“‘
server {
# ...
location ~* ^/<YOUR PATH HERE>/(\w+)/([^/]+)_\d+\.(js|css|png|jpg|jpeg|gif|ico)$ {
alias <YOUR ROOT HERE>/$1/$2.$3;
add_header Vary Accept-Encoding;
expires max;
}
# ...
}
“‘
Example taken from the blog of [Ben Ripkens](http://blog.bripkens.de/2012/03/nginx-cache-busting/).
## Installation
‘clack-static-asset-middleware‘ is not yet in quicklisp, so clone it into your quicklisp ‘local-projects‘ directory. Then, run
“‘lisp
(ql:quickload :clack-static-asset-middleware)
“‘
or refer to it in your system definition
“‘lisp
(asdf:defsystem my-great-webapp
...
:depends-on (#:clack-static-asset-middleware)
..
)
“‘
## Template Helpers
Right now, there is a helper package, ‘clack-static-asset-djula-helpers‘, which provides extensions to the [Djula](https://github.com/mmontone/) templating language for inserting busted URLs into templates. Once you’ve loaded the system, there will be two new djula tags available.
- ‘asset-path‘: Inserts a busted url to the given path.
“‘
<img src="{% asset-path "images/gustywinds.jpg" %}" /> => <img src="/static/images/gustywinds_423534...a3.jpg" />
“‘
- ‘stylesheet-tag‘: Inserts a busted url conveniently inside a stylesheet tag.
“‘
{% stylesheet-tag "styles/cool.css" %} => <link rel="stylesheet" href="/static/styles/cool_a05b6...878f.css">
“‘
## Author
* Matt Novenstern (fisxoj@gmail.com)
## Copyright
Copyright (c) 2016 Matt Novenstern (fisxoj@gmail.com)
## License
Licensed under the MIT License.
1.1
alexandria (system).
uiop (system).
ironclad (system).
cl-ppcre (system).
local-time (system).
trivial-mimes (system).
src (module).
Modules are listed depth-first from the system components tree.
clack-static-asset-middleware/srcclack-static-asset-middleware (system).
Files are sorted by type and then listed depth-first from the systems components trees.
clack-static-asset-middleware/clack-static-asset-middleware.asdclack-static-asset-middleware/src/clack-static-asset-middleware.lispclack-static-asset-middleware/clack-static-asset-middleware.asdclack-static-asset-middleware (system).
clack-static-asset-middleware/src/clack-static-asset-middleware.lispsrc (module).
*asset-lookup-table* (special variable).
*clack-static-asset-middleware* (special variable).
+default-cache-buster-function+ (special variable).
+default-cache-unbuster-function+ (special variable).
+default-filter-function+ (special variable).
busted-uri-for-path (function).
*base-path* (special variable).
asset-response (function).
inventory-files (function).
md5-file (function).
root-relative-path (function).
walk-directory (function).
Packages are listed by definition order.
clack-static-asset-middlewarecommon-lisp.
*asset-lookup-table* (special variable).
*clack-static-asset-middleware* (special variable).
+default-cache-buster-function+ (special variable).
+default-cache-unbuster-function+ (special variable).
+default-filter-function+ (special variable).
busted-uri-for-path (function).
*base-path* (special variable).
asset-response (function).
inventory-files (function).
md5-file (function).
root-relative-path (function).
walk-directory (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Lookup table for files in the static asset directory. Maps relative filenames to cache-busted versions, e.g. ’style/homepage.css => style/homepage_2867f3f83a6a91ad4a19a6cd45536152.css
Function to make a new pathname with a cache-busting string appended. The default it to convert ‘style.css‘ to ‘style_[hex-string].css‘. You can override this by passing a different function to the middleware.
Function to undo the cache busting.
Function to filter out files that would be hidden on a unix system. Namely, anything that starts with a ‘#.‘.
Lookup the busted resource uri for a given path. Returns the given path if none is found.
Base path of the assets on the server. Maybe something like "static/".
Generate the ‘clack‘ respone with an file or a 404. Expects ‘relative-path‘ to be a string with no leading ‘/‘.
Generate a string of hex digits for a given pathname.
Produces a relative pathname relative to the root of the asset directory. The string that might be specified in a template, for example.
Collects all the files in ‘directory‘ except those excluded by ‘filter-function‘.
| Jump to: | A B F I M R W |
|---|
| Jump to: | A B F I M R W |
|---|
| Jump to: | *
+
S |
|---|
| Jump to: | *
+
S |
|---|
| Jump to: | C F M P S |
|---|
| Jump to: | C F M P S |
|---|