| Title: | Query Cache for HTTP Clients |
|---|---|
| Description: | In order to improve performance for HTTP API clients, 'httpcache' provides simple tools for caching and invalidating cache. It includes the HTTP verb functions GET, PUT, PATCH, POST, and DELETE, which are drop-in replacements for those in the 'httr' package. These functions are cache-aware and provide default settings for cache invalidation suitable for RESTful APIs; the package also enables custom cache-management strategies. Finally, 'httpcache' includes a basic logging framework to facilitate the measurement of HTTP request time and cache performance. |
| Authors: | Neal Richardson [aut, cre] |
| Maintainer: | Neal Richardson <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.2.0 |
| Built: | 2024-10-22 04:15:31 UTC |
| Source: | https://github.com/nealrichardson/httpcache |
This function encapsulates the logic of making a cache key, allowing other code or libraries to access the HTTP cache programmatically.
buildCacheKey(url, query = NULL, body = NULL, extras = c())buildCacheKey(url, query = NULL, body = NULL, extras = c())
url |
character request URL |
query |
Optional query parameters for the request |
body |
Optional request body |
extras |
character Optional additional annotations to include in the cache key. |
Character value, starting with url and including hashed query
and body values if provided, to be used as the cache key for this request.
These functions provide access to what's stored in the cache.
hitCache(key) getCache(key) setCache(key, value)hitCache(key) getCache(key) setCache(key, value)
key |
character, typically a URL or similar |
value |
For |
hitCache returns logical whether key exists in the
cache. getCache returns the value stored in the cache, or NULL
if there is nothing cached. setCache is called for its side effects.
These functions turn the cache on and off and clear the contents of the query cache.
cacheOn() cacheOff() clearCache()cacheOn() cacheOff() clearCache()
Nothing. Functions are run for their side effects.
These functions set, read from, and bust the HTTP query cache. They wrap the similarly named functions in the httr package and can be used as drop-in replacements for them.
GET(url, ...) PUT(url, ..., drop = dropCache(url)) POST(url, ..., drop = dropOnly(url)) PATCH(url, ..., drop = dropCache(url)) DELETE(url, ..., drop = dropCache(url))GET(url, ...) PUT(url, ..., drop = dropCache(url)) POST(url, ..., drop = dropOnly(url)) PATCH(url, ..., drop = dropCache(url)) DELETE(url, ..., drop = dropCache(url))
url |
character URL of the request |
... |
additional arguments passed to the httr functions |
drop |
For |
GET checks the cache before making an HTTP request, and if there is a cache
miss, it sets the response from the request into the cache for future
requests. The other verbs, assuming a more or less RESTful API, would be
assumed to modify server state, and thus they should trigger cache
invalidation. They have default cache-invalidation strategies, but you can
override them as desired.
The corresponding httr response object, potentially read from cache
Some APIs have resources where a POST is used to send a command that returns
content and doesn't modify state. In this case, it's more like a GET. This
may occur where one might normally GET but the request URI would be too long
for the server to accept. cachedPOST thus behaves more like
GET, checking for a cached response before performing the request and
setting cache if the request is successful. It does no cache dropping, unlike
POST().
cachedPOST(url, ...)cachedPOST(url, ...)
url |
character URL of the request |
... |
additional arguments passed to the httr functions |
The corresponding httr response object, potentially read from cache
Summarize cache performance from a log
cacheLogSummary(logdf)cacheLogSummary(logdf)
logdf |
A logging data.frame, as loaded by |
A list containing counts of cache hit/set/drop events, plus a cache hit rate.
These functions let you control cache invalidation. dropOnly
invalidates cache only for the specified URL. dropPattern uses
regular expression matching to invalidate cache. dropCache is a
convenience wrapper around dropPattern that invalidates cache for
any resources that start with the given URL.
dropCache(x) dropOnly(x) dropPattern(x)dropCache(x) dropOnly(x) dropPattern(x)
x |
character URL or regular expression |
Nothing. Functions are run for their side effects.
Wrapper around base::stop() that logs the error message and then stops
with call. = FALSE by default.
halt(..., call. = FALSE)halt(..., call. = FALSE)
... |
arguments passed to |
call. |
logical: print the call? Default is |
Nothing. Raises an error.
Read in a httpcache log file
loadLogfile(filename, scope = c("CACHE", "HTTP"))loadLogfile(filename, scope = c("CACHE", "HTTP"))
filename |
character name of the log file, passed to
|
scope |
character optional means of selecting only certain log
messages. By default, only "CACHE" and "HTTP" log messages are kept. Other
logged messages, such as "ERROR" messages from |
A data.frame of log results.
Log a message
logMessage(...)logMessage(...)
... |
Strings to pass to |
Nothing
Summarize HTTP requests from a log
requestLogSummary(logdf)requestLogSummary(logdf)
logdf |
A logging data.frame, as loaded by |
A list containing counts of HTTP requests by verb, as well as summaries of time spent waiting on HTTP requests.
Warm your query cache from a previous session by saving out the cache and loading it back in.
saveCache(file) loadCache(file)saveCache(file) loadCache(file)
file |
character file path to write the cache data to, in |
Nothing; called for side effects.
Enable logging
startLog(filename = "", append = FALSE)startLog(filename = "", append = FALSE)
filename |
character: a filename/path where the log can be written out.
If |
append |
logical: if the file already exists, append to it? Default
is |
Nothing.
If you don't want to store the response of a GET request in the cache,
wrap it in uncached(). It will neither read from nor write to cache.
uncached(...)uncached(...)
... |
Things to evaluate with caching off |
uncached will not invalidate cache records, if present. It only ignores
them.
Whatever ... returns.
uncached(GET("http://httpbin.org/get"))uncached(GET("http://httpbin.org/get"))