Using file modification dates during update and caching operations

Timestamps

Preliminaries

This note documents where and how timestamps are used by the server, and their role in file updates and caching.

The use of timestamps in headers is part of the core HTTP protocol. Every message sends a date header in its response, indicating the time at which the request was fulfilled by the server.

Dates are specified using the Gregorian calendar and Coordinated Universal Time (UTC). The expression of dates always uses English abbreviations for the month and the day of week. Timezones are never part of the expression. Accuracy is limited to one second. See RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content Section 7.1.1.1 for details.

Dates are also used in the accept-datetime, retry-after, expires, last-modified, if-modified-since and if-unmodified-since headers.

Conditional requests

The server can determine whether a browser's cached duplicate is still valid by comparing timestamps during a conditional request. When a request for a resource is originally fulfilled by the server, it sends a last-modified header in the response, which is stored by the browser in its cache together with the resource itself.

When a conditional GET request is made for a resource, the browser sends a if-modified-since header containing the saved value. The server compares the two values and decides whether to honor the request and return 200, or deny the request and respond with 304.

When a conditional PUT request is made for a resource, the browser sends a if-unmodified-since header containing the saved value. The server compares the two values and decides whether to honor the request and return 204, or deny the request and respond with 304.

The use of timestamps for conditional requests is not perfect, because the server and browser may not have their clocks precisely synchronized, or because a file may have its modification date changed even though its binary contents are identical. The preferred solution to this problem is the use of etag headers. Refer to the separate note regarding the Etag Handler for an explanation of how it can remove the need for timestamps.

Conditional timestamps are only applicable to HEAD, GET and PUT requests.

Configuration

The use of timestamps does not require any server configuration. Just be sure the device running the server software has an accurate time. Use the Network Time Protocol service on port 123 for best results. See RFC 5905 Network Time Protocol Version 4: Protocol and Algorithms Specification.

EBNF

SP ::= U+20
COLON ::= U+3A
COMMA ::= U+2C
day-name ::= 'Mon' | 'Tue' | 'Wed' | 'Thu' | 'Fri' | 'Sat' | 'Sun'
month ::= 'Jan' | 'Feb' | 'Mar' | 'Apr' | 'May' | 'Jun' | 'Jul' | 'Aug' | 'Sep' | 'Oct' | 'Nov' | 'Dec'
year ::= [0-9][0-9][0-9][0-9]
day ::= [0-9][0-9]
hour ::= [0-9][0-9]
minute ::= [0-9][0-9]
second ::= [0-9][0-9]
date ::= day SP month SP year
time-of-day ::= hour COLON minute COLON second
imf-fixdate ::= day-name COMMA SP date SP time-of-day SP 'GMT'

Review

Key points to remember:

  • The use of timestamps for version control is a relic of HTTP/1.0 and has been deprecated in favor of Etags.

Using file modification dates during update and caching operations