1 files changed, 98 insertions, 0 deletions
diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 66b9c6d..60ec866 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -566,6 +566,71 @@ By default, the contents are stored within @var{XDG_DATA_HOME}, but it
 can be overriden by @var{#:dir}.
 @end deffn
 
+The @emph{path} API is defined in
+@code{(webid-oidc server resource path)}.
+
+@deffn function read-path @var{path}
+Read the resource at @var{path}, and return 2 values:
+@enumerate
+@item
+the ETag 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
+resource.
+@end enumerate
+
+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.
+
+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
+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.
+
+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.
+
+The last functions are from the content API. Since creating or
+deleting children requires updating the parent, we need them.
+
+Some operations should create the intermediate containers for a given
+path, this is the case for the @code{PUT} HTTP verb. For @code{POST},
+the parent should exist. The @var{#: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 @var{X}/@var{Y}.lock, where @var{X} is
+the first character of the base64-url sha-256 hash of the path, and
+@var{Y} is the other characters. @strong{The lock file is not meant to
+be removed} when the resource is unlocked. It should be locked with
+@code{flock} instead.
+
+Also, the API uses a global mutex to prevent concurrent updates. So,
+if @var{f} tries to update some other paths, then a deadlock will
+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.
+@end deffn
+
 @node Running a client
 @chapter Running a client
 
@@ -731,6 +796,7 @@ Return a string explaining the @var{error}. You can limit the
 * Invalid JWT::
 * Cannot fetch data on the web::
 * Other errors in the protocol or from a reasonable implementation::
+* Server-side errors::
 @end menu
 
 @node Invalid data format
@@ -1131,6 +1197,38 @@ The @var{webid}, as certified by @var{iss}, cannot be refreshed
 because we don’t have a refresh token stored in @var{dir}.
 @end deftp
 
+@node Server-side errors
+@section Server-side errors
+The resource server implementation may encounter some more exceptional
+conditions.
+
+@deftp {exception type} &path-not-found @var{path}
+There is no registered resource at @var{path}.
+@end deftp
+
+@deftp {exception type} &uri-slash-semantics-error @var{path} @var{expected-path}
+While the resource at @var{path} does not exist, the resource at
+@var{expected-path} does, and @var{path} and @var{expected-path}
+differ only by a trailing slash. This exception may be raised along
+with @code{&path-not-found}.
+
+Beware that even if it is true at the time when the exception is
+created, maybe the resource has been created by the time it is
+handled.
+@end deftp
+
+@deftp {exception type} &cannot-delete-root
+There was a request to delete the root storage, which is an error.
+@end deftp
+
+@deftp {exception type} &container-not-empty @var{path}
+There was a request to delete a non-empty container.
+@end deftp
+
+@deftp {exception type} &not-a-container @var{path} @var{content-type}
+There was a request to create a resource in something that is not a
+container.
+@end deftp
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License