Use a web cache on the file system

1 files changed, 48 insertions, 0 deletions

diff --git a/doc/manual.html b/doc/manual.html
index 49350d3..9a14e39 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -150,6 +150,54 @@
         Encode the JWT and sign it with <info:var>key</info:var>.
       </p>
     </info:deffn>
+    <h1>Caching on server side</h1>
+    <p>
+      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.
+    </p>
+    <p>
+      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</emph>. 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.
+    </p>
+    <p>
+      The <emph>(webid-oidc&#160;cache)</emph> module exports two
+      functions to deal with the cache.
+    </p>
+    <info:deffn type="function" name="clean-cache" arguments="[#percents] [#dir]">
+      <p>
+        Drop <info:var>percents</info:var>% of the cache right now, in
+        <info:var>dir</info:var> (defaults to some place within
+        <emph>XDG_CACHE_HOME</emph>).
+      </p>
+    </info:deffn>
+    <info:deffn type="function" name="with-cache" arguments="[#current-time] [#http-get] [#dir]">
+      <p>
+        Return a function acting as <emph>http-get</emph> from
+        <emph>(web&#160;client)</emph> (takes an URI as the first
+        parameter, and an optional <info:var>#:headers</info:var> set,
+        and returns 2 values, the response and its body).
+      </p>
+      <p>
+        The cache will be read and written in <info:var>dir</info:var>
+        (defaults to some place within <emph>XDG_CACHE_HOME</emph>),
+        and the <info:var>current-time</info:var> number of seconds,
+        SRFI-19 time or date, or time-returning thunk will be used to
+        check for the validity of responses.
+      </p>
+      <p>
+        The back-end function, <info:var>http-get</info:var>, defaults
+        to that of <emph>(web&#160;client)</emph>.
+      </p>
+    </info:deffn>
     <h1>What if something goes wrong?</h1>
     <p>
       The library will raise an exception whenever something fishy