To store and serve resources, the server has two distinct mechanisms. A content is a read-only possible value for a resource, indexed by etags, and a path is a mutable value that indicates the etag of the resource, and of the auxiliary resources (description and ACL). With this separation, it is possible to atomically delete a resource and all associated auxiliary resources, by unlinking the corresponding path. It is also possible to mutate separately the ACL and the resource itself without writing a copy for both.
The content API is contained in the
(webid-oidc server resource content) module.
This class encapsulate a static resource content linked to a particular etag.
The content-type is a symbol, and static-content is a
bytevector, although a string will be encoded to UTF-8 at construction
time. contained is either
#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
#:etag, it will be loaded from the file
system under the etag index, or if
passed or the
current-content-cache is set to cache, it
will try to load from cache first. If you define a cache, the
result will also be added to cache.
If you pass
#:static-content, but not
#:etag, it will be
created and saved to disk, and optionally added to the
#:cache or the current content 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.
cache is a hash table for string etag values to cached content values. It is initialized as an empty hash table.
Return the ETag of content, as a string.
Return the Content-Type of content, as a symbol.
Return the contained paths of content, as a list of strings, or
#f if it is not a container.
Return the static content of content, as a bytevector.
Remove [content’s] etag from the file system. If it is cached in session, also remove the cached value. Otherwise, other sessions can still access it.
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.
The path API is defined in
(webid-oidc server resource path).
Read the resource at path, and return 2 values:
(web uri)), and the values are contents of the corresponding resource.
If the resource is not found, raise an exception with type
&path-not-found, and maybe
a resource with a different ending-in-slash exists.
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 content. If this is the case, then you must call this function again to read the updated path.
Read path, call f with two values: the main content and
the auxiliary contents (as returned by read-path), and update
the path accordingly. If path does not exist, then the first
#f and the second one is the empty list.
If f returns
#f, then the resource is deleted.
If 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.
This function uses the
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
Some operations should create the intermediate containers for a given
path, this is the case for the
PUT HTTP verb. For
the parent should exist. The #:create-intermediate-containers?
switch lets you change the behavior. In any case, it is an error to
delete a non-empty container.
The update is atomic, meaning that at any point in time the file is
fully written out. Concurrent access to the same resource is performed
by locking the lock file named X/.lock, where X is the
first character of the base64-url sha-256 hash of the
path. The lock file is not meant to be removed when the
resource is unlocked. It should be locked with
instead. Like other forms of lock-based synchronization, this
function is not composable. This means that you cannot call this
function within f, otherwise a deadlock may ensue.
If the resource is created or deleted, then the parent resource is updated as well. To avoid deadlocks with other processes, please follow the following rules: lock the path, then lock the parent path, then update the parent, then unlock the parent, and finally unlock the child path.
The Web Access Control specification defines an RDF vocabulary to
check whether a given user is allowed to perform some operations. The
(webid-oidc server resource wac) helps you do that.
Return the list of modes that are allowed for user accessing
path. The server-name URI is required to find the relevant
triples in the ACL. If user is unauthenticated, pass
Please note that in any case, the data owner should have all rights whatsoever, bypassing WAC. Otherwise, it is possible to steal control away from the data owner.
Assert that the resource at path on server-name is owned
by owner, and check that user has the proper
authorization. Otherwise, raise an exception of type