Hash the primary cache key.

1 files changed, 25 insertions, 1 deletions

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index 7b6b30a..be1d82f 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -7,7 +7,7 @@
 @settitle Demanding Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid
 @c %**end of header
 
-@set UPDATED 19 March 2023
+@set UPDATED 20 March 2023
 @set UPDATED-MONTH March 2023
 @include version_number.texi
 
@@ -195,4 +195,28 @@ response dates, according to the client, a boolean flag to mark an
 entry as invalidated, and the HTTP scheme that was used (HTTP or
 HTTPS).
 
+@cindex hash, cache entry hash
+If you have a method and URI to query, you can find all the relevant
+entries by hashing the request method and URI.
+
+@cindex private cache
+When querying the cache for a @strong{private} cache implementation,
+you must make sure to only consider entries that are available to the
+party that is querying the cache. The method and URI are salted with
+an optional password. If the password is not the empty string, then
+only cache entries that have been added specifically with that
+password will be available. If you are running a multi-user cache, you
+can query the cache with the user name as the password in a private
+setting, and then query the cache again with an empty password in a
+shared setting, so you get all the private entries for that user, plus
+all the shared entries.
+
+@deftypefun int disfluid_hash_primary_cache_key (const char *@var{method}, const char *@var{uri}, const char *@var{password}, size_t @var{password_length}, size_t @var{max_hash}, char *@var{hash})
+Hash @var{method} and @var{uri} to get a NUL-terminated hexadecimal
+string of characters in @var{hash}. At most @var{max_hash} bytes will
+be written. If @var{max_hash} is too short, then @var{hash} may not be
+NUL-terminated, and the value @code{-2} is returned. Otherwise,
+@code{0} is returned.
+@end deftypefun
+
 @bye