On this page:

2.13 Serving Files🔗

The web-server/dispatchers/dispatch-files module allows files to be served. It defines a dispatcher construction procedure.


  #:url->path url->path 
  [#:path->mime-type path->mime-type 
  #:path->headers path->headers 
  #:indices indices 
  #:cache-max-age cache-max-age 
  #:cache-smaxage cache-smaxage 
  #:cache-stale-while-revalidate cache-stale-while-revalidate 
  #:cache-stale-if-error cache-stale-if-error 
  #:cache-no-cache cache-no-cache 
  #:cache-no-store cache-no-store 
  #:cache-no-transform cache-no-transform 
  #:cache-must-revalidate cache-must-revalidate 
  #:cache-proxy-revalidate cache-proxy-revalidate 
  #:cache-must-understand cache-must-understand 
  #:cache-private cache-private 
  #:cache-public cache-public 
  #:cache-immutable cache-immutable]) 
  url->path : url->path/c
  path->mime-type : (path? . -> . (or/c false/c bytes?))
   = (lambda (path) #f)
  path->headers : (path? . -> . (listof header?))
   = (lambda (path) '())
  indices : (listof string?) = (list "index.html" "index.htm")
  cache-max-age : (or/c false/c (and/c exact-integer? positive?))
   = #f
  cache-smaxage : (or/c false/c (and/c exact-integer? positive?))
   = #f
  cache-stale-while-revalidate : (or/c false/c (and/c exact-integer? positive?))
   = #f
  cache-stale-if-error : (or/c false/c (and/c exact-integer? positive?))
   = #f
  cache-no-cache : boolean? = #f
  cache-no-store : boolean? = #f
  cache-no-transform : boolean? = #f
  cache-must-revalidate : boolean? = #f
  cache-proxy-revalidate : boolean? = #f
  cache-must-understand : boolean? = #f
  cache-private : boolean? = #f
  cache-public : boolean? = #f
  cache-immutable : boolean? = #f
Uses url->path to extract a path from the URL in the request object. If this path does not exist, then the dispatcher does not apply and next-dispatcher is invoked. If the path is a directory, then the indices are checked in order for an index file to serve. In that case, or in the case of a path that is a file already, path->mime-type is consulted for the MIME Type of the path. Similarly, path->headers is consulted for additional headers of the path. The file is then streamed out the connection object.

This dispatcher supports HTTP Range GET requests and HEAD requests. If the request’s method is neither HEAD nor GET, next-dispatcher will be called.

If the path works out to something on disk (either as a file, or, if the path refers to directory, one of the specified indices files in that directory), it needs to be readable by the process that is running the web server. Existing but unreadable files are handled as non-existing files.

The various keyword arguments that start with cache- (cache-public, cache-max-age and so on) all map straightforwardly to legal values that can appear in the standard Cache-Control response header. By default, all are #f, which has the effect that responses emitted by this dispatcher do not have a Cache-Control header. If any cache-related keyword has a non-#f value, a Cache-Control header will be present in the response. Thus, if cache-immutable is #t and cache-max-age is 12345, an Cache-Control header will be present in all responses and its value will be max-age=12345, immutable. For more information see RFC 2616 section 14.9 “Cache Control” and the Mozilla Developer Network documentation on Cache-Control. Note that some combinations of cache headers may lead to unintended behavior. Example: using #t for both #:cache-public and #:cache-private (those two are effectively antonyms). Beyond the contract for each of the keyword arguments, no additional checks are made by make to ensure that the supplied cache-related arguments are a meaningful combination or are suitable for your web application.

Changed in version 1.7 of package web-server-lib: Support for non-{GET,HEAD} requests.
Changed in version 1.7: Treat unreadable files as non-existing files.
Changed in version 1.9: Support a number of options for setting a Cache-Control response header
Changed in version 1.10: Support #:path->headers.