Next: , Previous: , Up: Top   [Contents][Index]

13 Resources stored on the server

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.

Class: <content> () etag content-type contained static-content

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 #:cache is 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 #:content-type, #:contained and #:static-content, but not #:etag, it will be created and saved to disk, and optionally added to the #:cache or the current content cache.

Class: <content-cache> () 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.

Generic: etag content

Return the ETag of content, as a string.

Generic: content-type content

Return the Content-Type of content, as a symbol.

Generic: contained content

Return the contained paths of content, as a list of strings, or #f if it is not a container.

Generic: static-content content

Return the static content of content, as a bytevector.

Generic: delete-content content
Generic: delete-content etag

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.

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.

The path API is defined in (webid-oidc server resource path).

function: read-path path

Read the resource at path, and return 2 values:

  1. the content of the main resource;
  2. an alist where keys are auxiliary resource type URIs (the type is from (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 &uri-slash-semantics-error if a resource with a different ending-in-slash exists.

If the 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.

function: update-path path f [#:create-intermediate-containers?=#f]

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 argument is #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 the cache.

Some operations should create the intermediate containers for a given path, this is the case for the PUT HTTP verb. For POST, 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 flock 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.

function: wac-get-modes server-name path user [#:http-get]

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 #f.

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.

function: check-acl-can-read server-name path owner user [#:http-get]
function: check-acl-can-write server-name path owner user [#:http-get]
function: check-acl-can-append server-name path owner user [#:http-get]
function: check-acl-can-control server-name path owner user [#:http-get]

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 &forbidden.

Next: , Previous: , Up: Top   [Contents][Index]