/** * Copyright 2015 Paul Querna * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * */ package cacheobject import ( "net/http" "time" ) // LOW LEVEL API: Represents a potentially cachable HTTP object. // // This struct is designed to be serialized efficiently, so in a high // performance caching server, things like Date-Strings don't need to be // parsed for every use of a cached object. type Object struct { CacheIsPrivate bool RespDirectives *ResponseCacheDirectives RespHeaders http.Header RespStatusCode int RespExpiresHeader time.Time RespDateHeader time.Time RespLastModifiedHeader time.Time ReqDirectives *RequestCacheDirectives ReqHeaders http.Header ReqMethod string NowUTC time.Time } // LOW LEVEL API: Represents the results of examining an Object with // CachableObject and ExpirationObject. // // TODO(pquerna): decide if this is a good idea or bad type ObjectResults struct { OutReasons []Reason OutWarnings []Warning OutExpirationTime time.Time OutErr error } // LOW LEVEL API: Check if a request is cacheable. // This function doesn't reset the passed ObjectResults. func CachableRequestObject(obj *Object, rv *ObjectResults) { switch obj.ReqMethod { case "GET": break case "HEAD": break case "POST": // Responses to POST requests can be cacheable if they include explicit freshness information break case "PUT": rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodPUT) case "DELETE": rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodDELETE) case "CONNECT": rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodCONNECT) case "OPTIONS": rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodOPTIONS) case "TRACE": rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodTRACE) // HTTP Extension Methods: http://www.iana.org/assignments/http-methods/http-methods.xhtml // // To my knowledge, none of them are cachable. Please open a ticket if this is not the case! // default: rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodUnknown) } if obj.ReqDirectives != nil && obj.ReqDirectives.NoStore { rv.OutReasons = append(rv.OutReasons, ReasonRequestNoStore) } } // LOW LEVEL API: Check if a response is cacheable. // This function doesn't reset the passed ObjectResults. func CachableResponseObject(obj *Object, rv *ObjectResults) { /** POST: http://tools.ietf.org/html/rfc7231#section-4.3.3 Responses to POST requests are only cacheable when they include explicit freshness information (see Section 4.2.1 of [RFC7234]). However, POST caching is not widely implemented. For cases where an origin server wishes the client to be able to cache the result of a POST in a way that can be reused by a later GET, the origin server MAY send a 200 (OK) response containing the result and a Content-Location header field that has the same value as the POST's effective request URI (Section 3.1.4.2). */ if obj.ReqMethod == http.MethodPost && !hasFreshness(obj.RespDirectives, obj.RespHeaders, obj.RespExpiresHeader, obj.CacheIsPrivate) { rv.OutReasons = append(rv.OutReasons, ReasonRequestMethodPOST) } // Storing Responses to Authenticated Requests: http://tools.ietf.org/html/rfc7234#section-3.2 if obj.ReqHeaders.Get("Authorization") != "" { if obj.RespDirectives.MustRevalidate || obj.RespDirectives.Public || obj.RespDirectives.SMaxAge != -1 { // Expires of some kind present, this is potentially OK. } else { rv.OutReasons = append(rv.OutReasons, ReasonRequestAuthorizationHeader) } } if obj.RespDirectives.PrivatePresent && !obj.CacheIsPrivate { rv.OutReasons = append(rv.OutReasons, ReasonResponsePrivate) } if obj.RespDirectives.NoStore { rv.OutReasons = append(rv.OutReasons, ReasonResponseNoStore) } /* the response either: * contains an Expires header field (see Section 5.3), or * contains a max-age response directive (see Section 5.2.2.8), or * contains a s-maxage response directive (see Section 5.2.2.9) and the cache is shared, or * contains a Cache Control Extension (see Section 5.2.3) that allows it to be cached, or * has a status code that is defined as cacheable by default (see Section 4.2.2), or * contains a public response directive (see Section 5.2.2.5). */ if obj.RespHeaders.Get("Expires") != "" || obj.RespDirectives.MaxAge != -1 || (obj.RespDirectives.SMaxAge != -1 && !obj.CacheIsPrivate) || cachableStatusCode(obj.RespStatusCode) || obj.RespDirectives.Public { /* cachable by default, at least one of the above conditions was true */ return } rv.OutReasons = append(rv.OutReasons, ReasonResponseUncachableByDefault) } // LOW LEVEL API: Check if a object is cachable. func CachableObject(obj *Object, rv *ObjectResults) { rv.OutReasons = nil rv.OutWarnings = nil rv.OutErr = nil CachableRequestObject(obj, rv) CachableResponseObject(obj, rv) } var twentyFourHours = time.Duration(24 * time.Hour) const debug = false // LOW LEVEL API: Update an objects expiration time. func ExpirationObject(obj *Object, rv *ObjectResults) { /** * Okay, lets calculate Freshness/Expiration now. woo: * http://tools.ietf.org/html/rfc7234#section-4.2 */ /* o If the cache is shared and the s-maxage response directive (Section 5.2.2.9) is present, use its value, or o If the max-age response directive (Section 5.2.2.8) is present, use its value, or o If the Expires response header field (Section 5.3) is present, use its value minus the value of the Date response header field, or o Otherwise, no explicit expiration time is present in the response. A heuristic freshness lifetime might be applicable; see Section 4.2.2. */ var expiresTime time.Time if obj.RespDirectives.SMaxAge != -1 && !obj.CacheIsPrivate { expiresTime = obj.NowUTC.Add(time.Second * time.Duration(obj.RespDirectives.SMaxAge)) } else if obj.RespDirectives.MaxAge != -1 { expiresTime = obj.NowUTC.UTC().Add(time.Second * time.Duration(obj.RespDirectives.MaxAge)) } else if !obj.RespExpiresHeader.IsZero() { serverDate := obj.RespDateHeader if serverDate.IsZero() { // common enough case when a Date: header has not yet been added to an // active response. serverDate = obj.NowUTC } expiresTime = obj.NowUTC.Add(obj.RespExpiresHeader.Sub(serverDate)) } else if !obj.RespLastModifiedHeader.IsZero() { // heuristic freshness lifetime rv.OutWarnings = append(rv.OutWarnings, WarningHeuristicExpiration) // http://httpd.apache.org/docs/2.4/mod/mod_cache.html#cachelastmodifiedfactor // CacheMaxExpire defaults to 24 hours // CacheLastModifiedFactor: is 0.1 // // expiry-period = MIN(time-since-last-modified-date * factor, 24 hours) // // obj.NowUTC since := obj.RespLastModifiedHeader.Sub(obj.NowUTC) since = time.Duration(float64(since) * -0.1) if since > twentyFourHours { expiresTime = obj.NowUTC.Add(twentyFourHours) } else { expiresTime = obj.NowUTC.Add(since) } if debug { println("Now UTC: ", obj.NowUTC.String()) println("Last-Modified: ", obj.RespLastModifiedHeader.String()) println("Since: ", since.String()) println("TwentyFourHours: ", twentyFourHours.String()) println("Expiration: ", expiresTime.String()) } } else { // TODO(pquerna): what should the default behavior be for expiration time? } rv.OutExpirationTime = expiresTime } // Evaluate cachability based on an HTTP request, and parts of the response. func UsingRequestResponse(req *http.Request, statusCode int, respHeaders http.Header, privateCache bool) ([]Reason, time.Time, error) { reasons, time, _, _, err := UsingRequestResponseWithObject(req, statusCode, respHeaders, privateCache) return reasons, time, err } // Evaluate cachability based on an HTTP request, and parts of the response. // Returns the parsed Object as well. func UsingRequestResponseWithObject(req *http.Request, statusCode int, respHeaders http.Header, privateCache bool) ([]Reason, time.Time, []Warning, *Object, error) { var reqHeaders http.Header var reqMethod string var reqDir *RequestCacheDirectives = nil respDir, err := ParseResponseCacheControl(respHeaders.Get("Cache-Control")) if err != nil { return nil, time.Time{}, nil, nil, err } if req != nil { reqDir, err = ParseRequestCacheControl(req.Header.Get("Cache-Control")) if err != nil { return nil, time.Time{}, nil, nil, err } reqHeaders = req.Header reqMethod = req.Method } var expiresHeader time.Time var dateHeader time.Time var lastModifiedHeader time.Time if respHeaders.Get("Expires") != "" { expiresHeader, err = http.ParseTime(respHeaders.Get("Expires")) if err != nil { // sometimes servers will return `Expires: 0` or `Expires: -1` to // indicate expired content expiresHeader = time.Time{} } expiresHeader = expiresHeader.UTC() } if respHeaders.Get("Date") != "" { dateHeader, err = http.ParseTime(respHeaders.Get("Date")) if err != nil { return nil, time.Time{}, nil, nil, err } dateHeader = dateHeader.UTC() } if respHeaders.Get("Last-Modified") != "" { lastModifiedHeader, err = http.ParseTime(respHeaders.Get("Last-Modified")) if err != nil { return nil, time.Time{}, nil, nil, err } lastModifiedHeader = lastModifiedHeader.UTC() } obj := Object{ CacheIsPrivate: privateCache, RespDirectives: respDir, RespHeaders: respHeaders, RespStatusCode: statusCode, RespExpiresHeader: expiresHeader, RespDateHeader: dateHeader, RespLastModifiedHeader: lastModifiedHeader, ReqDirectives: reqDir, ReqHeaders: reqHeaders, ReqMethod: reqMethod, NowUTC: time.Now().UTC(), } rv := ObjectResults{} CachableObject(&obj, &rv) if rv.OutErr != nil { return nil, time.Time{}, nil, nil, rv.OutErr } ExpirationObject(&obj, &rv) if rv.OutErr != nil { return nil, time.Time{}, nil, nil, rv.OutErr } return rv.OutReasons, rv.OutExpirationTime, rv.OutWarnings, &obj, nil } // calculate if a freshness directive is present: http://tools.ietf.org/html/rfc7234#section-4.2.1 func hasFreshness(respDir *ResponseCacheDirectives, respHeaders http.Header, respExpires time.Time, privateCache bool) bool { if !privateCache && respDir.SMaxAge != -1 { return true } if respDir.MaxAge != -1 { return true } if !respExpires.IsZero() || respHeaders.Get("Expires") != "" { return true } return false } func cachableStatusCode(statusCode int) bool { /* Responses with status codes that are defined as cacheable by default (e.g., 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, and 501 in this specification) can be reused by a cache with heuristic expiration unless otherwise indicated by the method definition or explicit cache controls [RFC7234]; all other status codes are not cacheable by default. */ switch statusCode { case 200: return true case 203: return true case 204: return true case 206: return true case 300: return true case 301: return true case 404: return true case 405: return true case 410: return true case 414: return true case 501: return true default: return false } }