[cl-openid-devel] provider API suggestions

[Anton Vodonosov]

Hello Maciej.

I tried to use the provider as if in a real web site
In result I have the following suggestions about
the provider API, so that it will be more 
convenient for user.

HANDLE-OPENID-PROVIDER-REQUEST
 - always return the second value, HTTP code.
 - when result means that redirect must be performed,
   always return the URI as a string, to avoid 
   PRINC-TO-STRING everywere in the code;
 - rename SECURE-P to ALLOW-UNENCRYPTED

CANCEL-RESPONSE and SUCCESSFUL-RESPONSE are always
redirects; therefore they may return a single value -
the redirect URI. It must always be a string too.
CANCEL-RESPONSE-URI and CANCEL-RESPONSE-URI will
be more clear names for the functions, both
when studying the library and reading code that uses it.
CANCEL-RESPONCE doc string has an error: it says the 
function *sends* a response (in reality it only constructs 
a response).

WITH-INDIRECT-ERROR-HANDLER is unnecessary to export
and to mention in the docs. Instead, the library must
catch *any* errors when it calls HANDLE-CHECKID-SETUP 
and other user provided functions; not only INDIRECT-ERROR.

I feel the INDIRECT-ERROR and SIGNAL-INDIRECT-ERROR,
are not needed in the public API too. In practice
there were no cases when I needed them. Indirect error
responses are more for malformed requests, and all the
correctness checks are already made by the library.

It is necessary to provide a function to extract
realm from messages, like this:

  (defun auth-req-realm (message)
    (or (if (not (message-v2-p message))
            ;; prior to 2.0 "openid.realm" 
            ;; was called "openid.trust_root"
            ;; see the spec, section 14.2.1
            (message-field message "openid.trust_root")
            (message-field message "openid.realm"))
        ;; section 9.1, if "openid.realm" is not
        ;; specifed, it defaults to "openid.return_to"
        (message-field message "openid.return_to")))

The name of the function intends to point that
realm is present only in authentication request
messages. 

As a result of the suggested changes, only the
HANDLE-OPENID-PROVIDER-REQUEST will have two-value 
return convention. Code to examine its return
value may be written in place. This saves us from 
creating separate  HUNCHENTOOT-OPENID-RESPONSE (as in
your example) and calling it via MULTIPLE-VALUE-CALL 
everywhere.

Best regards,
-Anton