diff options
author | Vivien Kraus <vivien@planete-kraus.eu> | 2021-06-03 18:16:10 +0200 |
---|---|---|
committer | Vivien Kraus <vivien@planete-kraus.eu> | 2021-06-19 15:44:36 +0200 |
commit | 63ae0abe0a53dc30e0b914ef038d715cdf14cfb0 (patch) | |
tree | 856790985539ff849bc298d573fd793bf331ae89 /doc | |
parent | 5863e990a70ab01b98540bed49bbe9ca38cba638 (diff) |
Add an API to update server resource paths
Diffstat (limited to 'doc')
-rw-r--r-- | doc/webid-oidc.texi | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi index 66b9c6d..b2cc3d7 100644 --- a/doc/webid-oidc.texi +++ b/doc/webid-oidc.texi @@ -566,6 +566,69 @@ 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}/.lock, where @var{X} is the +first character of the base64-url sha-256 hash of the +path. @strong{The lock file is not meant to be removed} when the +resource is unlocked. It should be locked with @code{flock} +instead. @strong{Like other forms of lock-based synchronization, this +function is not composable}. This means that you cannot call this +function within @var{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. +@end deffn + @node Running a client @chapter Running a client @@ -731,6 +794,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 +1195,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} ¬-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 |