From 6e2f63056e51f6e0e788d25f338834bfb0497af1 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 28 Mar 2013 21:01:44 +0000 Subject: [PATCH] docs: more work --- caf.pod | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 1 deletion(-) diff --git a/caf.pod b/caf.pod index ce9e3fb..40ee9cd 100644 --- a/caf.pod +++ b/caf.pod @@ -597,6 +597,123 @@ confidential for the user.) =back. +=head1 DIVERT SPEC + +The return value from C indicates how the request should +be handled. It is C if all is well and the user is logged in. + +Otherwise the return value is a hash ref with the following keys: + +=over + +=item C + +Scalar string indicating the kind of diversion required. + +=item C + +Scalar string for display to the user in relation to the diversion. +Has already been translated. In HTML but normally does not contain +any tags. + +=item C + +The secret cookie which should be set along with whatever response is +sent to the client. The value in the hash is the actual secret value +of the cookie as a string. C means no cookie setting header +should be sent; C<''> means the cookie should be cleared. + +=item C + +The extra hidden form parameters (and the C) which should +be set when the subsequent request bounces back from the client, in +the form used by C. + +The contents of this hashref does not include the CAF-specific +parameters such as the secret cookie, those which follow from the kind +of diversion requested, etc. + +It is correct to always include the contents of C as hidden +parameters in the urls for all redirections, and as hidden input +fields in all generated forms. The specific cases where C is +currently relevant are also mentioned in the text for each divert +kind. + +=back + +The values of C are: + +=over + +=item CI + +We should respond by sending our application source code. I +(which will contain only word characters, and no lower case) is the +specific item to send, normally C or C. + +=item C + +We should respond with an HTTP redirect to the HTTPS instance of our +application. + +=item C + +We should redirect to a page showing that the user has been logged +out. (Ie, to a url with one of the the C set.) + +=item C + +We should generate a page showing that the user has been logged out. +There can be a link on the page pointing to the login page so that the +user can log back in. + +=item C + +We should generate a page reporting that the user does not have +cookies enabled. It should probably contain a link pointing to the +login page with additionally all the parameters in C. When +this divert spec is generated, C will explain the problem +with cookies so there is no need to do that again in the page body if +you include the contents of C. + +=item C + +The user's session was stale (this is described in C). We +should generate a login form. + +=item C + +The user supplied bad login credentials. The details are in +C. We should generate a login form (with additionally the +parameters from C as hidden fields). + +=item C + +We should generate a login form (with the specified parameters); the +user is entering the site via a cross-site link but is not yet logged +in. + +=item C + +We should generate a login form. The user is not yet logged in. + +=item C + +We should redirect to our actual application, with the specified +parameters. (The user has just logged in.) + +=item C + +We should generate our main page but B +and B. Most applications will find this +difficult to implement. + +An alternative is to generate a small page with a form or link which +submits our own main page without any parameters. + +(Applications which set C do not see this divert +kind.) + =head1 SETTINGS C and C each take a list of settings, as @@ -1193,7 +1310,6 @@ xxx document _db_setup_do xxx make _db_setup_do explicitly overrideable -xxx divert spec xxx remaining settings assocdb_password username_password_error -- 2.30.2