Use a web cache on the file system

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 7a1b6ea..5269330 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -48,6 +48,7 @@ Free Documentation License''
 @menu
 * Decentralized Authentication on the Web::
 * The Json Web Token::
+* Caching on server side::
 * Exceptional conditions::
 * GNU Free Documentation License::
 * Index::
@@ -149,6 +150,44 @@ exception.
 Encode the JWT and sign it with @var{key}.
 @end deffn
 
+@node Caching on server side
+@chapter Caching on server side
+
+Both the identity provider and the resource server need to cache
+things. The identity provider will cache application webids, and the
+resource server will cache the identity provider keys, for instance.
+
+The solution is to use a file-system cache. Every response (except
+those that have a cache-control policy of no-store) are stored to a
+sub-directory of @emph{XDG_CACHE_HOME}. Each store has a 5% chance of
+triggering a cleanup of the cache. When a cleanup occurs, each cached
+response has a 5% chance of being dropped, including responses that
+are indicated as valid. This way, a malicious cache response that has
+a maliciously long validity will not stay too long in the cache. A log
+line will indicate which items are dropped.
+
+The @emph{(webid-oidc cache)} module exports two functions to deal
+with the cache.
+
+@deffn function clean-cache @var{[#percents]} @var{[#dir]}
+Drop @var{percents}% of the cache right now, in @var{dir} (defaults to
+some place within @emph{XDG_CACHE_HOME}).
+@end deffn
+
+@deffn function with-cache @var{[#current-time]} @var{[#http-get]} @var{[#dir]}
+Return a function acting as @emph{http-get} from @emph{(web client)}
+(takes an URI as the first parameter, and an optional @var{#:headers}
+set, and returns 2 values, the response and its body).
+
+The cache will be read and written in @var{dir} (defaults to some
+place within @emph{XDG_CACHE_HOME}), and the @var{current-time} number
+of seconds, SRFI-19 time or date, or time-returning thunk will be used
+to check for the validity of responses.
+
+The back-end function, @var{http-get}, defaults to that of
+@emph{(web client)}.
+@end deffn
+
 @node Exceptional conditions
 @chapter Exceptional conditions