The clack-static-asset-middleware Reference Manual

Table of Contents

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 2.3 "Robert April" on Tue Feb 20 08:23:23 2018 GMT+0.


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

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.


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

2 Systems

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


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

2.1 clack-static-asset-middleware

Author

Matt Novenstern

License

MIT

Description

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

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
Source

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

Component

src (module)


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

3 Modules

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


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

3.1 clack-static-asset-middleware/src

Parent

clack-static-asset-middleware (system)

Location

src/

Component

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


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

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


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 clack-static-asset-middleware.asd

Location

clack-static-asset-middleware.asd

Systems

clack-static-asset-middleware (system)

Packages

clack-static-asset-middleware-asd


Previous: , Up: Lisp files   [Contents][Index]

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

Parent

src (module)

Location

src/clack-static-asset-middleware.lisp

Packages

clack-static-asset-middleware

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 clack-static-asset-middleware-asd

Source

clack-static-asset-middleware.asd

Use List

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

5.2 clack-static-asset-middleware

Source

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

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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

clack-static-asset-middleware

Source

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

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 (file)

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

Function to undo the cache busting.

Package

clack-static-asset-middleware

Source

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

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 (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 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 (file)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [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 (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 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 (file)

Function: inventory-files PATHNAMES PATH ROOT &key FILTER-FUNCTION CACHE-BUSTER-FUNCTION
Package

clack-static-asset-middleware

Source

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

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 (file)

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 (file)

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 (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
clack-static-asset-middleware.asd: The clack-static-asset-middleware<dot>asd file
clack-static-asset-middleware/src: The clack-static-asset-middleware/src module
clack-static-asset-middleware/src/clack-static-asset-middleware.lisp: The clack-static-asset-middleware/src/clack-static-asset-middleware<dot>lisp file

F
File, Lisp, clack-static-asset-middleware.asd: The clack-static-asset-middleware<dot>asd file
File, Lisp, clack-static-asset-middleware/src/clack-static-asset-middleware.lisp: The clack-static-asset-middleware/src/clack-static-asset-middleware<dot>lisp file

L
Lisp File, clack-static-asset-middleware.asd: The clack-static-asset-middleware<dot>asd file
Lisp File, clack-static-asset-middleware/src/clack-static-asset-middleware.lisp: The clack-static-asset-middleware/src/clack-static-asset-middleware<dot>lisp file

M
Module, clack-static-asset-middleware/src: The clack-static-asset-middleware/src module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   A   B   F   I   M   R   W  
Index Entry  Section

A
asset-response: Internal functions

B
busted-uri-for-path: Exported functions

F
Function, asset-response: Internal functions
Function, busted-uri-for-path: Exported functions
Function, inventory-files: Internal functions
Function, md5-file: Internal functions
Function, root-relative-path: Internal functions
Function, walk-directory: Internal functions

I
inventory-files: Internal functions

M
md5-file: Internal functions

R
root-relative-path: Internal functions

W
walk-directory: Internal functions

Jump to:   A   B   F   I   M   R   W  

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

A.3 Variables

Jump to:   *   +  
S  
Index Entry  Section

*
*asset-lookup-table*: Exported special variables
*base-path*: Internal special variables
*clack-static-asset-middleware*: Exported special variables

+
+default-cache-buster-function+: Exported special variables
+default-cache-unbuster-function+: Exported special variables
+default-filter-function+: Exported special variables

S
Special Variable, *asset-lookup-table*: Exported special variables
Special Variable, *base-path*: Internal special variables
Special Variable, *clack-static-asset-middleware*: Exported special variables
Special Variable, +default-cache-buster-function+: Exported special variables
Special Variable, +default-cache-unbuster-function+: Exported special variables
Special Variable, +default-filter-function+: Exported special variables

Jump to:   *   +  
S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
clack-static-asset-middleware: The clack-static-asset-middleware system
clack-static-asset-middleware: The clack-static-asset-middleware package
clack-static-asset-middleware-asd: The clack-static-asset-middleware-asd package

P
Package, clack-static-asset-middleware: The clack-static-asset-middleware package
Package, clack-static-asset-middleware-asd: The clack-static-asset-middleware-asd package

S
System, clack-static-asset-middleware: The clack-static-asset-middleware system

Jump to:   C   P   S