Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the clack-static-asset-middleware Reference Manual, version 1.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:29:06 2018 GMT+0.
| • Introduction: | What clack-static-asset-middleware is all about | |
| • Systems: | The systems documentation | |
| • Modules: | The modules documentation | |
| • Files: | The files documentation | |
| • Packages: | The packages documentation | |
| • Definitions: | The symbols documentation | |
| • Indexes: | Concepts, functions, variables and data types |
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.
Use by wrapping your clack app in clack-static-asset-middleware:*clack-static-asset-middleware*.
(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 templating language below.
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.
clack-static-asset-middleware is not yet in quicklisp, so clone it into your quicklisp local-projects directory. Then, run
(ql:quickload :clack-static-asset-middleware)
or refer to it in your system definition
(asdf:defsystem my-great-webapp
...
:depends-on (#:clack-static-asset-middleware)
..
)
Right now, there is a helper package, clack-static-asset-djula-helpers, which provides extensions to the Djula 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">
Copyright (c) 2016 Matt Novenstern (fisxoj@gmail.com)
Licensed under the MIT License.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The clack-static-asset-middleware system: |
Matt Novenstern
MIT
A cache busting static file middleware for the clack web framework.
# 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
src (module)
Modules are listed depth-first from the system components tree.
| • The clack-static-asset-middleware/src module: |
clack-static-asset-middleware (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files: |
| • The clack-static-asset-middleware.asd file: | ||
| • The clack-static-asset-middleware/src/clack-static-asset-middleware.lisp file: |
Next: The clack-static-asset-middleware/src/clack-static-asset-middleware<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
clack-static-asset-middleware.asd
clack-static-asset-middleware (system)
Previous: The clack-static-asset-middleware<dot>asd file, Up: Lisp files [Contents][Index]
src (module)
src/clack-static-asset-middleware.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The clack-static-asset-middleware-asd package: | ||
| • The clack-static-asset-middleware package: |
Next: The clack-static-asset-middleware package, Previous: Packages, Up: Packages [Contents][Index]
clack-static-asset-middleware.asd
Previous: The clack-static-asset-middleware-asd package, Up: Packages [Contents][Index]
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions: | ||
| • Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables: | ||
| • Exported functions: |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
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 ‘#.‘.
Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Lookup the busted resource uri for a given path. Returns the given path if none is found.
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables: | ||
| • Internal functions: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Base path of the assets on the server. Maybe something like "static/".
Previous: Internal special variables, Up: Internal definitions [Contents][Index]
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‘.
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index: | ||
| • Function index: | ||
| • Variable index: | ||
| • Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L M |
|---|
| Jump to: | C F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A B F I M R W |
|---|
| Jump to: | A B F I M R W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
S |
|---|
| Jump to: | *
+
S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C P S |
|---|
| Jump to: | C P S |
|---|