The http-get-cache Reference Manual

This is the http-get-cache Reference Manual, version 0.1.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:16:29 2020 GMT+0.

1 Introduction

http-get-cache

http-get-cache is a Common Lisp library based on the Drakma HTTP client for caching HTTP GET responses.

http-get-cache depends on Drakma and Bordeaux Threads.

http-get-cache is being developed with SBCL, CCL, and LispWorks on OS X. http-get-cache is being deployed with SBCL on FreeBSD/AMD64 and Linux/AMD64.

Installation

(ql:quickload "http-get-cache")

Example

(defvar *cache* (http-get-cache:make-cache 60))

(http-get-cache:http-get "http://planet.lisp.org/" *cache*)

#S(HTTP-GET-CACHE:RESPONSE
   :STATUS-CODE 200
   :HEADERS ((:SERVER . "nginx/1.9.0")
             (:DATE . "Thu, 16 Mar 2017 04:56:47 GMT")
             (:CONTENT-TYPE . "text/html") (:CONTENT-LENGTH . "128383")
             (:LAST-MODIFIED . "Thu, 16 Mar 2017 04:15:56 GMT")
             (:CONNECTION . "close") (:ETAG . "\"58ca117c-1f57f\"")
             (:ACCEPT-RANGES . "bytes"))
   :BODY "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\">

<html>

<head>
<title>Planet Lisp</title>
...
</html>
"
   :TIMESTAMP 3698629006)

License

http-get-cache is distributed under the MIT license. See LICENSE.

2 Systems

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

2.1 `http-get-cache`

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Description

Common Lisp library for caching HTTP GET responses

Version

0.1.1

Dependency

drakma

Source

http-get-cache.asd (file)

Components

package.lisp (file)
http-get-cache.lisp (file)

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.asd`

Location: http-get-cache.asd
Systems: http-get-cache (system)

3.1.2 `http-get-cache/package.lisp`

Parent: http-get-cache (system)
Location: package.lisp
Packages: http-get-cache

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

Dependency

package.lisp (file)

Parent

http-get-cache (system)

Location

http-get-cache.lisp

Exported Definitions

cache (structure)
cache-ttl (function)
(setf cache-ttl) (function)
http-get (function)
http-get-error (condition)
http-get-not-found (condition)
make-cache (function)
response (structure)
response-body (function)
(setf response-body) (function)
response-headers (function)
(setf response-headers) (function)
response-status-code (function)
(setf response-status-code) (function)
response-timestamp (function)
(setf response-timestamp) (function)

Internal Definitions

%make-cache (function)
+http-not-modified+ (constant)
+http-ok+ (constant)
cache-mutex (function)
(setf cache-mutex) (function)
cache-p (function)
cache-responses (function)
(setf cache-responses) (function)
copy-cache (function)
copy-response (function)
http-get-not-found-uri (method)
make-response (function)
response-fresh-p (function)
response-p (function)
uri-key (function)

4 Packages

Packages are listed by definition order.

4.1 `http-get-cache`

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

cache (structure)
cache-ttl (function)
(setf cache-ttl) (function)
http-get (function)
http-get-error (condition)
http-get-not-found (condition)
make-cache (function)
response (structure)
response-body (function)
(setf response-body) (function)
response-headers (function)
(setf response-headers) (function)
response-status-code (function)
(setf response-status-code) (function)
response-timestamp (function)
(setf response-timestamp) (function)

Internal Definitions

%make-cache (function)
+http-not-modified+ (constant)
+http-ok+ (constant)
cache-mutex (function)
(setf cache-mutex) (function)
cache-p (function)
cache-responses (function)
(setf cache-responses) (function)
copy-cache (function)
copy-response (function)
http-get-not-found-uri (generic function)
http-get-not-found-uri (method)
make-response (function)
response-fresh-p (function)
response-p (function)
uri-key (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: cache-ttl INSTANCE

Function: (setf cache-ttl) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

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 (file)

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 (file)

Function: response-body INSTANCE

Function: (setf response-body) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: response-headers INSTANCE

Function: (setf response-headers) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: response-status-code INSTANCE

Function: (setf response-status-code) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: response-timestamp INSTANCE

Function: (setf response-timestamp) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

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 (file)
Direct superclasses: error (condition)
Direct subclasses: http-get-not-found (condition)

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 (file)

Direct superclasses

http-get-error (condition)

Direct methods

http-get-not-found-uri (method)

Direct slots

Slot: uri

Initargs: :uri
Readers: http-get-not-found-uri (generic function)

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 (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: responses

Initform: (make-hash-table :test (function equal))
Readers: cache-responses (function)
Writers: (setf cache-responses) (function)

Slot: mutex

Initform: (bordeaux-threads:make-lock "http-get-cache")
Readers: cache-mutex (function)
Writers: (setf cache-mutex) (function)

Slot: ttl

Readers: cache-ttl (function)
Writers: (setf cache-ttl) (function)

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 (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: status-code

Readers: response-status-code (function)
Writers: (setf response-status-code) (function)

Slot: headers

Readers: response-headers (function)
Writers: (setf response-headers) (function)

Slot: body

Readers: response-body (function)
Writers: (setf response-body) (function)

Slot: timestamp

Readers: response-timestamp (function)
Writers: (setf response-timestamp) (function)

5.2 Internal definitions

5.2.1 Constants

Constant: +http-not-modified+

Package: http-get-cache
Source: http-get-cache.lisp (file)

Constant: +http-ok+

Package: http-get-cache
Source: http-get-cache.lisp (file)

5.2.2 Functions

Function: %make-cache &key (RESPONSES RESPONSES) (MUTEX MUTEX) (TTL TTL)

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: cache-mutex INSTANCE

Function: (setf cache-mutex) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: cache-p OBJECT

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: cache-responses INSTANCE

Function: (setf cache-responses) VALUE INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: copy-cache INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: copy-response INSTANCE

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: make-response &key (STATUS-CODE STATUS-CODE) (HEADERS HEADERS) (BODY BODY) (TIMESTAMP TIMESTAMP)

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: response-fresh-p RESPONSE TTL NOW

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: response-p OBJECT

Package: http-get-cache
Source: http-get-cache.lisp (file)

Function: uri-key URI

Package: http-get-cache
Source: http-get-cache.lisp (file)

5.2.3 Generic functions

Generic Function: http-get-not-found-uri CONDITION

Package

http-get-cache

Methods

Method: http-get-not-found-uri (CONDITION http-get-not-found)

Source: http-get-cache.lisp (file)

Appendix A Indexes

A.1 Concepts

Jump to:	F H L

	Index Entry	Section

F
	File, Lisp, `http-get-cache.asd`:	The http-get-cache․asd file
	File, Lisp, `http-get-cache/http-get-cache.lisp`:	The http-get-cache/http-get-cache․lisp file
	File, Lisp, `http-get-cache/package.lisp`:	The http-get-cache/package․lisp file

H
	`http-get-cache.asd`:	The http-get-cache․asd file
	`http-get-cache/http-get-cache.lisp`:	The http-get-cache/http-get-cache․lisp file
	`http-get-cache/package.lisp`:	The http-get-cache/package․lisp file

L
	Lisp File, `http-get-cache.asd`:	The http-get-cache․asd file
	Lisp File, `http-get-cache/http-get-cache.lisp`:	The http-get-cache/http-get-cache․lisp file
	Lisp File, `http-get-cache/package.lisp`:	The http-get-cache/package․lisp file

Jump to:	F H L

A.2 Functions

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

	Index Entry	Section

%
	`%make-cache`:	Internal functions

(
	`(setf cache-mutex)`:	Internal functions
	`(setf cache-responses)`:	Internal functions
	`(setf cache-ttl)`:	Exported functions
	`(setf response-body)`:	Exported functions
	`(setf response-headers)`:	Exported functions
	`(setf response-status-code)`:	Exported functions
	`(setf response-timestamp)`:	Exported functions

C
	`cache-mutex`:	Internal functions
	`cache-p`:	Internal functions
	`cache-responses`:	Internal functions
	`cache-ttl`:	Exported functions
	`copy-cache`:	Internal functions
	`copy-response`:	Internal functions

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

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

H
	`http-get`:	Exported functions
	`http-get-not-found-uri`:	Internal generic functions
	`http-get-not-found-uri`:	Internal generic functions

M
	`make-cache`:	Exported functions
	`make-response`:	Internal functions
	`Method, http-get-not-found-uri`:	Internal generic functions

R
	`response-body`:	Exported functions
	`response-fresh-p`:	Internal functions
	`response-headers`:	Exported functions
	`response-p`:	Internal functions
	`response-status-code`:	Exported functions
	`response-timestamp`:	Exported functions

U
	`uri-key`:	Internal functions

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

A.3 Variables

Jump to:	+ B C H M R S T U

	Index Entry	Section

+
	`+http-not-modified+`:	Internal constants
	`+http-ok+`:	Internal constants

B
	`body`:	Exported structures

C
	`Constant, +http-not-modified+`:	Internal constants
	`Constant, +http-ok+`:	Internal constants

H
	`headers`:	Exported structures

M
	`mutex`:	Exported structures

R
	`responses`:	Exported structures

S
	`Slot, body`:	Exported structures
	`Slot, headers`:	Exported structures
	`Slot, mutex`:	Exported structures
	`Slot, responses`:	Exported structures
	`Slot, status-code`:	Exported structures
	`Slot, timestamp`:	Exported structures
	`Slot, ttl`:	Exported structures
	`Slot, uri`:	Exported conditions
	`status-code`:	Exported structures

T
	`timestamp`:	Exported structures
	`ttl`:	Exported structures

U
	`uri`:	Exported conditions

Jump to:	+ B C H M R S T U

A.4 Data types

Jump to:	C H P R S

	Index Entry	Section

C
	`cache`:	Exported structures
	`Condition, http-get-error`:	Exported conditions
	`Condition, http-get-not-found`:	Exported conditions

H
	`http-get-cache`:	The http-get-cache system
	`http-get-cache`:	The http-get-cache package
	`http-get-error`:	Exported conditions
	`http-get-not-found`:	Exported conditions

P
	`Package, http-get-cache`:	The http-get-cache package

R
	`response`:	Exported structures

S
	`Structure, cache`:	Exported structures
	`Structure, response`:	Exported structures
	`System, http-get-cache`:	The http-get-cache system

Jump to:	C H P R S

• Introduction		What http-get-cache is all about
• Systems		The systems documentation
• Files		The files documentation
• Packages		The packages documentation
• Definitions		The symbols documentation
• Indexes		Concepts, functions, variables and data types

• Concept index
• Function index
• Variable index
• Data type index

• The http-get-cache.asd file
• The http-get-cache/package.lisp file
• The http-get-cache/http-get-cache.lisp file

• Exported functions
• Exported conditions
• Exported structures

• Internal constants
• Internal functions
• Internal generic functions

The http-get-cache Reference Manual

Table of Contents

The http-get-cache Reference Manual

1 Introduction

http-get-cache

Installation

Example

License

2 Systems

2.1 http-get-cache

3 Files

3.1 Lisp

3.1.1 http-get-cache.asd

3.1.2 http-get-cache/package.lisp

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

4 Packages

4.1 http-get-cache

5 Definitions

5.1 Exported definitions

5.1.1 Functions

5.1.2 Conditions

5.1.3 Structures

5.2 Internal definitions

5.2.1 Constants

5.2.2 Functions

5.2.3 Generic functions

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `http-get-cache`

3.1.1 `http-get-cache.asd`

3.1.2 `http-get-cache/package.lisp`

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

4.1 `http-get-cache`