diff options
author | Vivien Kraus <vivien@planete-kraus.eu> | 2021-10-14 14:23:51 +0200 |
---|---|---|
committer | Vivien Kraus <vivien@planete-kraus.eu> | 2021-10-19 11:32:00 +0200 |
commit | a219bf64933d3313aebe0e5576b291e32e93d93f (patch) | |
tree | cac1226f500dfbd5a7daf991bfc2b157846ad83d /doc | |
parent | 19915a8b5b2912d255a6850a5d8d796a4f9c7fc9 (diff) |
server: add an exception for showing a message to the user
Diffstat (limited to 'doc')
-rw-r--r-- | doc/disfluid.texi | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/doc/disfluid.texi b/doc/disfluid.texi index fa5347a..6b9ad08 100644 --- a/doc/disfluid.texi +++ b/doc/disfluid.texi @@ -1539,10 +1539,80 @@ Return the path prefix @var{endpoint} is configured to respond to. Check if @var{endpoint} is configured to respond to @var{request}. @end deffn +The handler may throw exceptions to signal errors. Exception messages +will be printed to the log file, and user messages will be passed to +the user. + @menu +* Error signalling:: * Router endpoint:: @end menu +@node Error signalling +@section Error signalling +The @emph{(webid-oidc server endpoint)} module defines exception types +that can be emitted to abort the computation in a handler. If an +exception of a different kind is raised, this will lead to a 500 +Internal Server Error response. + +@deftp {Exception type} &web-exception @var{code} @var{reason-phrase} +The request failed, with @var{code} and @var{reason-phrase}. +@end deftp + +@deffn {function} make-web-exception @var{code} @var{reason-phrase} +Create an exception with @var{code} and @var{reason-phrase}. +@end deffn + +@deffn {function} web-exception? @var{exn} +Check if @var{exn} was thrown because the request failed. +@end deffn + +@deffn {function} web-exception-code @var{exn} +@deffnx {function} web-exception-reason-phrase @var{exn} +Return the code and reason-phrase for when @var{exn} was thrown, if it +was thrown because of a failing request. +@end deffn + +@deftp {Exception type} &caused-by-user @var{webid} +If a web exception is raised, maybe it is caused by some user +identified by @var{webid} (an URI, or @code{#f}. +@end deftp + +@deffn {function} make-caused-by-user @var{webid} +Constructor for @code{&caused-by-user}. +@end deffn + +@deffn {function} caused-by-user? @var{exn} +Check if @var{exn} was caused by the user. +@end deffn + +@deffn {function} caused-by-user-webid @var{exn} +Return the webid of the user that caused @var{exn}. +@end deffn + +@deftp {Exception type} &user-message @var{sxml} +An exception containing a message that is safe to show to the user, as +an SXML fragment of XHTML. Typically, this would be a @code{<p/>}, or +a @code{<div/>}. + +You can set a user-message multiple times. The occurences will be +concatenated in the response, in the order they appear in the +composite exception. +@end deftp + +@deffn {function} make-user-message @var{sxml} +Create a new user message containing the @var{sxml} fragment. +@end deffn + +@deffn {function} user-message? @var{exn} +Check if there is at least one user message in @var{exn}. +@end deffn + +@deffn {function} user-message-sxml @var{exn} +Return all user messages in @var{exn}, as a @code{<div/>} SXML +fragment. +@end deffn + @node Router endpoint @section Router endpoint The first non-trivial handler is for the router endpoint, defined in |