From avodonosov at yandex.ru Sat Sep 13 18:23:03 2008 From: avodonosov at yandex.ru (Anton Vodonosov) Date: Sat, 13 Sep 2008 21:23:03 +0300 Subject: [cl-openid-devel] provider API suggestions Message-ID: <1775752252.20080913212303@yandex.ru> 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