Content API: use GOOPS for the cache

1 files changed, 73 insertions, 43 deletions

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index 35e8e13..5523a21 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -1457,42 +1457,67 @@ copy for both.
 The @emph{content} API is contained in the
 @code{(webid-oidc server resource content)} module.
 
-@deffn function with-session @var{f}
-Call @var{f} with 5 arguments:
-@itemize
-@item
-a function to get the content-type of a given etag;
-@item
-a function to list the paths contained within the resource;
-@item
-a function to load the content of a given etag;
-@item
-a function to create a new content;
-@item
-a function to remove a content from the file system. It is still
-possible to query it with the first 3 functions, but new sessions will
-not see it.
-@end itemize
+@deftp {Class} <content> () @var{etag} @var{content-type} @var{contained} @var{static-content}
+This class encapsulate a static resource content linked to a
+particular @var{etag}.
+
+The @var{content-type} is a symbol, and @var{static-content} is a
+bytevector, although a string will be encoded to UTF-8 at construction
+time. @var{contained} is either @code{#f}, if the resource is not a
+container, or a list of resource paths (each one is a string)
+identifying contained resources.
+
+You can construct a content in two ways.
+
+If you pass @code{#:@var{etag}}, it will be loaded from the file
+system under the @var{etag} index, or if @code{#:@var{cache}} is
+passed or the @code{current-content-cache} is set to @var{cache}, it
+will try to load from @var{cache} first. If you define a cache, the
+result will also be added to @var{cache}.
+
+If you pass @code{#:@var{content-type}}, @code{#:@var{contained}} and
+@code{#:@var{static-content}}, but not @code{#:etag}, it will be
+created and saved to disk, and optionally added to the
+@code{#:@var{cache}} or the current content cache.
+@end deftp
 
-Since the contents are read-only, it is possible to cache the value of
-the content in memory. This is why @var{f} should run within a session
-with memoization.
+@deftp {Class} <content-cache> () @var{cache}
+Since the contents are read-only, it is possible to cache the values
+in memory to avoid reading the same file more than once. This is how
+the session works.
 
-Resources only store @emph{static} content, because the membership
-triples for containers is considered dynamic and not included in the
-representation.
+@var{cache} is a hash table for string etag values to cached content
+values. It is initialized as an empty hash table.
+@end deftp
 
-The first 3 functions as well as the last one are called with an etag,
-and the function to create a content is called with the content-type,
-list of contained paths, and (static) content.
+@deffn {Generic} etag @var{content}
+Return the ETag of @var{content}, as a string.
+@end deffn
+
+@deffn {Generic} content-type @var{content}
+Return the Content-Type of @var{content}, as a symbol.
+@end deffn
+
+@deffn {Generic} contained @var{content}
+Return the contained paths of @var{content}, as a list of strings, or
+@code{#f} if it is not a container.
+@end deffn
+
+@deffn {Generic} static-content @var{content}
+Return the static content of @var{content}, as a bytevector.
+@end deffn
 
-The contents are searched in the @emph{server/content} subdirectory of
-@var{data-home}.
+@deffn {Generic} delete-content @var{content}
+@deffnx {Generic} delete-content @var{etag}
+Remove [@var{content}’s] @var{etag} from the file system. If it is
+cached in @var{session}, also remove the cached value. Otherwise,
+other sessions can still access it.
 @end deffn
 
-@deffn parameter data-home
-Defines the directory where to store persistent data. Defaults to
-@emph{XDG_DATA_HOME}.
+@deffn parameter current-content-cache
+A guile parameter indicating a cache where loaded contents should be
+added and preferably fetched. By default, no caching is performed. You
+need to set this parameter to benefit from it.
 @end deffn
 
 The @emph{path} API is defined in
@@ -1502,10 +1527,10 @@ The @emph{path} API is defined in
 Read the resource at @var{path}, and return 2 values:
 @enumerate
 @item
-the ETag of the main resource;
+the content of the main resource;
 @item
 an alist where keys are auxiliary resource type URIs (the type is from
-@code{(web uri)}), and the values are ETags of the corresponding
+@code{(web uri)}), and the values are contents of the corresponding
 resource.
 @end enumerate
 
@@ -1513,27 +1538,32 @@ If the resource is not found, raise an exception with type
 @code{&path-not-found}, and maybe @code{&uri-slash-semantics-error} if
 a resource with a different ending-in-slash exists.
 
+If the @code{current-content-cache} parameter is set to a cache, it
+will be used to load the content and auxiliary contents.
+
 This function is safe to call when the path is being modified, either
 by another thread, process or else, as the returned values will always
 be consistent. However, once the function returns, an updating process
-may have deleted the returned ETags. If this is the case, then you
+may have deleted the returned content. If this is the case, then you
 must call this function again to read the updated path.
 @end deffn
 
-@deffn function update-path @var{path} @var{f} @var{content-type} @var{contained} @var{static-content} @var{create} @var{delete} [@var{#:create-intermediate-containers?}=@code{#f}]
-Read @var{path}, call @var{f} with two values: the ETag and the
-auxiliary ETags (as returned by @var{read-path}), and update the path
-accordingly. If @var{path} does not exist, then the first argument is
-@code{#f} and the second one is the empty list.
+@deffn function update-path @var{path} @var{f} [@code{#:@var{create-intermediate-containers?}}=@code{#f}]
+Read @var{path}, call @var{f} with two values: the main content and
+the auxiliary contents (as returned by @var{read-path}), and update
+the path accordingly. If @var{path} does not exist, then the first
+argument is @code{#f} and the second one is the empty list.
 
 If @var{f} returns @code{#f}, then the resource is deleted.
 
-If @var{f} returns an ETag as the first returned value and an alist of
-auxiliary resource ETags as the second value, then the resource is
-updated.
+If @var{f} returns two values: a content as the first and an alist of
+auxiliary types (as URIs) to auxiliary contents as the second, then
+the resource is updated.
 
-The last functions are from the content API. Since creating or
-deleting children requires updating the parent, we need them.
+This function uses the @code{current-content-cache} parameter to load
+contents. If a resource is created or deleted, the parent’s
+containment triples will be modified, so they will also be loaded in
+the cache.
 
 Some operations should create the intermediate containers for a given
 path, this is the case for the @code{PUT} HTTP verb. For @code{POST},