The clack-static-asset-middleware Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The clack-static-asset-middleware Reference Manual

This is the clack-static-asset-middleware Reference Manual, version 1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:20:08 2022 GMT+0.

Table of Contents


1 Introduction

Clack-Static-Asset-Middleware

Build Status Coverage StatusQuicklisp

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*.

(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:

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.

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.

Installation

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)
    ..
    )

Template Helpers

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.

Author

Copyright

Copyright (c) 2016 Matt Novenstern (fisxoj@gmail.com)

License

Licensed under the MIT License.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 clack-static-asset-middleware

A cache busting static file middleware for the clack web framework.

Author

Matt Novenstern

License

MIT

Long Description

# Clack-Static-Asset-Middleware
[![Build Status](https://travis-ci.org/fisxoj/clack-static-asset-middleware.svg?branch=master)](https://travis-ci.org/fisxoj/clack-static-asset-middleware) [![Coverage Status](https://coveralls.io/repos/github/fisxoj/clack-static-asset-middleware/badge.svg?branch=master)](https://coveralls.io/github/fisxoj/clack-static-asset-middleware?branch=master)[![Quicklisp](http://quickdocs.org/badge/clack-static-asset-middleware.svg)](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.

Version

1.1

Dependencies
  • alexandria (system).
  • uiop (system).
  • ironclad (system).
  • cl-ppcre (system).
  • local-time (system).
  • trivial-mimes (system).
Source

clack-static-asset-middleware.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 clack-static-asset-middleware/src

Source

clack-static-asset-middleware.asd.

Parent Component

clack-static-asset-middleware (system).

Child Component

clack-static-asset-middleware.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


4.1.1 clack-static-asset-middleware/clack-static-asset-middleware.asd

Source

clack-static-asset-middleware.asd.

Parent Component

clack-static-asset-middleware (system).

ASDF Systems

clack-static-asset-middleware.

Packages

clack-static-asset-middleware-asd.


4.1.2 clack-static-asset-middleware/src/clack-static-asset-middleware.lisp

Source

clack-static-asset-middleware.asd.

Parent Component

src (module).

Packages

clack-static-asset-middleware.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 clack-static-asset-middleware-asd

Source

clack-static-asset-middleware.asd.

Use List
  • asdf/interface.
  • common-lisp.

5.2 clack-static-asset-middleware

Source

clack-static-asset-middleware.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Public Interface


6.1.1 Special variables

Special Variable: *asset-lookup-table*

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

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Special Variable: *clack-static-asset-middleware*
Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Special Variable: +default-cache-buster-function+

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.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Special Variable: +default-cache-unbuster-function+

Function to undo the cache busting.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Special Variable: +default-filter-function+

Function to filter out files that would be hidden on a unix system. Namely, anything that starts with a ‘#.‘.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.


6.1.2 Ordinary functions

Function: busted-uri-for-path (path)

Lookup the busted resource uri for a given path. Returns the given path if none is found.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.


6.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

6.2.1 Special variables

Special Variable: *base-path*

Base path of the assets on the server. Maybe something like "static/".

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.


Previous: , Up: Internals   [Contents][Index]

6.2.2 Ordinary functions

Function: asset-response (relative-path root)

Generate the ‘clack‘ respone with an file or a 404. Expects ‘relative-path‘ to be a string with no leading ‘/‘.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Function: inventory-files (pathnames path root &key filter-function cache-buster-function)
Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Function: md5-file (pathname &key buffer digest)

Generate a string of hex digits for a given pathname.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Function: root-relative-path (pathname root)

Produces a relative pathname relative to the root of the asset directory. The string that might be specified in a template, for example.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.

Function: walk-directory (directory &key filter-function)

Collects all the files in ‘directory‘ except those excluded by ‘filter-function‘.

Package

clack-static-asset-middleware.

Source

clack-static-asset-middleware.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts