The http-get-cache Reference Manual

This is the http-get-cache Reference Manual, version 0.1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 21:39:40 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 http-get-cache

Common Lisp library for caching HTTP GET responses

Author

Michael J. Forster <>

License

MIT

Version

0.1.1

Dependency

drakma (system).

Source

http-get-cache.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 http-get-cache/http-get-cache.asd

Source

http-get-cache.asd.

Parent Component

http-get-cache (system).

ASDF Systems

http-get-cache.


3.1.2 http-get-cache/package.lisp

Source

http-get-cache.asd.

Parent Component

http-get-cache (system).

Packages

http-get-cache.


3.1.3 http-get-cache/http-get-cache.lisp

Dependency

package.lisp (file).

Source

http-get-cache.asd.

Parent Component

http-get-cache (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 http-get-cache

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Reader: cache-ttl (instance)
Writer: (setf cache-ttl) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

ttl.

Function: http-get (uri cache)

Return the RESPONSE for the supplied URI. If a fresh RESPONSE for the URI exists in the CACHE then return that RESPONSE. If a stale RESPONSE for the URI exists in the CACHE then attempt to validate the RESPONSE with the origin server using the "If-None-Match" request header and the "Etag" header of the RESPONSE and, if successful, update the headers of the cached RESPONSE and return it. If no RESPONSE for the URI exists in the CACHE then make an HTTP GET request for the URI and, if successful, cache and return the RESPONSE; otherwise, signal an error of type HTTP-GET-NOT-FOUND>

If URI is neither a PURI:URI nor a STRING, signal an error of type TYPE-ERROR. If CACHE is not a CACHE, signal an error of type TYPE-ERROR.

Unlike an RFC 7234 compliant HTTP cache, HTTP-GET-CACHE expires a stored RESPONSE according to the time the RESPONSE was received and the CACHE TTL. HTTP-GET-CACHE ignores the "Expires" header field and the "max-age" cache directive of the HTTP request and response.

Package

http-get-cache.

Source

http-get-cache.lisp.

Function: make-cache (&optional ttl)

Create and return a CACHE with the optionally supplied TTL. TTL defaults to 300.

Package

http-get-cache.

Source

http-get-cache.lisp.

Reader: response-body (instance)
Writer: (setf response-body) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

body.

Reader: response-headers (instance)
Writer: (setf response-headers) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

headers.

Reader: response-status-code (instance)
Writer: (setf response-status-code) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

status-code.

Reader: response-timestamp (instance)
Writer: (setf response-timestamp) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

timestamp.


5.1.2 Conditions

Condition: http-get-error

Superclass for all errors signaled by HTTP-GET.

Package

http-get-cache.

Source

http-get-cache.lisp.

Direct superclasses

error.

Direct subclasses

http-get-not-found.

Condition: http-get-not-found

Signalled by HTTP-GET when a RESPONSE for the URI
is neither cached nor available via an HTTP GET request.

Package

http-get-cache.

Source

http-get-cache.lisp.

Direct superclasses

http-get-error.

Direct methods

http-get-not-found-uri.

Direct slots
Slot: uri
Initargs

:uri

Readers

http-get-not-found-uri.

Writers

This slot is read-only.


5.1.3 Structures

Structure: cache

A CACHE is an object that stores successful responses to HTTP GET requests. A response is stored until its TTL–time to live, in seconds–expires.

Package

http-get-cache.

Source

http-get-cache.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: responses
Initform

(make-hash-table :test (function equal))

Readers

cache-responses.

Writers

(setf cache-responses).

Slot: mutex
Initform

(bordeaux-threads:make-lock "http-get-cache")

Readers

cache-mutex.

Writers

(setf cache-mutex).

Slot: ttl
Readers

cache-ttl.

Writers

(setf cache-ttl).

Structure: response

A RESPONSE ia an object that stores the status code, headers, and body of an HTTP response, as well as the timestamp at which the response was received.

Package

http-get-cache.

Source

http-get-cache.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: status-code
Readers

response-status-code.

Writers

(setf response-status-code).

Slot: headers
Readers

response-headers.

Writers

(setf response-headers).

Slot: body
Readers

response-body.

Writers

(setf response-body).

Slot: timestamp
Readers

response-timestamp.

Writers

(setf response-timestamp).


5.2 Internals


5.2.1 Constants

Constant: +http-not-modified+
Package

http-get-cache.

Source

http-get-cache.lisp.

Constant: +http-ok+
Package

http-get-cache.

Source

http-get-cache.lisp.


5.2.2 Ordinary functions

Function: %make-cache (&key responses mutex ttl)
Package

http-get-cache.

Source

http-get-cache.lisp.

Reader: cache-mutex (instance)
Writer: (setf cache-mutex) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

mutex.

Function: cache-p (object)
Package

http-get-cache.

Source

http-get-cache.lisp.

Reader: cache-responses (instance)
Writer: (setf cache-responses) (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Target Slot

responses.

Function: copy-cache (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Function: copy-response (instance)
Package

http-get-cache.

Source

http-get-cache.lisp.

Function: make-response (&key status-code headers body timestamp)
Package

http-get-cache.

Source

http-get-cache.lisp.

Function: response-fresh-p (response ttl now)
Package

http-get-cache.

Source

http-get-cache.lisp.

Function: response-p (object)
Package

http-get-cache.

Source

http-get-cache.lisp.

Function: uri-key (uri)
Package

http-get-cache.

Source

http-get-cache.lisp.


5.2.3 Generic functions

Generic Reader: http-get-not-found-uri (condition)
Package

http-get-cache.

Methods
Reader Method: http-get-not-found-uri ((condition http-get-not-found))
Source

http-get-cache.lisp.

Target Slot

uri.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
C   F   G   H   M   R   U  
Index Entry  Section

%
%make-cache: Private ordinary functions

(
(setf cache-mutex): Private ordinary functions
(setf cache-responses): Private ordinary functions
(setf cache-ttl): Public ordinary functions
(setf response-body): Public ordinary functions
(setf response-headers): Public ordinary functions
(setf response-status-code): Public ordinary functions
(setf response-timestamp): Public ordinary functions

C
cache-mutex: Private ordinary functions
cache-p: Private ordinary functions
cache-responses: Private ordinary functions
cache-ttl: Public ordinary functions
copy-cache: Private ordinary functions
copy-response: Private ordinary functions

F
Function, %make-cache: Private ordinary functions
Function, (setf cache-mutex): Private ordinary functions
Function, (setf cache-responses): Private ordinary functions
Function, (setf cache-ttl): Public ordinary functions
Function, (setf response-body): Public ordinary functions
Function, (setf response-headers): Public ordinary functions
Function, (setf response-status-code): Public ordinary functions
Function, (setf response-timestamp): Public ordinary functions
Function, cache-mutex: Private ordinary functions
Function, cache-p: Private ordinary functions
Function, cache-responses: Private ordinary functions
Function, cache-ttl: Public ordinary functions
Function, copy-cache: Private ordinary functions
Function, copy-response: Private ordinary functions
Function, http-get: Public ordinary functions
Function, make-cache: Public ordinary functions
Function, make-response: Private ordinary functions
Function, response-body: Public ordinary functions
Function, response-fresh-p: Private ordinary functions
Function, response-headers: Public ordinary functions
Function, response-p: Private ordinary functions
Function, response-status-code: Public ordinary functions
Function, response-timestamp: Public ordinary functions
Function, uri-key: Private ordinary functions

G
Generic Function, http-get-not-found-uri: Private generic functions

H
http-get: Public ordinary functions
http-get-not-found-uri: Private generic functions
http-get-not-found-uri: Private generic functions

M
make-cache: Public ordinary functions
make-response: Private ordinary functions
Method, http-get-not-found-uri: Private generic functions

R
response-body: Public ordinary functions
response-fresh-p: Private ordinary functions
response-headers: Public ordinary functions
response-p: Private ordinary functions
response-status-code: Public ordinary functions
response-timestamp: Public ordinary functions

U
uri-key: Private ordinary functions