associations robustness improvements and documentation updates

3 files changed, 24 insertions, 1 deletions

diff --git a/include/opkele/association.h b/include/opkele/association.h
index a8f3915..72eff5b 100644
--- a/include/opkele/association.h
+++ b/include/opkele/association.h
@@ -60,8 +60,10 @@ namespace opkele {
             virtual string assoc_type() const { return _assoc_type; }
             virtual secret_t secret() const { return _secret; }
             virtual int expires_in() const { return _expires-time(0); }
             virtual bool stateless() const { return _stateless; }
+
+            virtual bool is_expired() const { return _expires<time(0); }
     };
 
 }
 
diff --git a/include/opkele/consumer.h b/include/opkele/consumer.h
index 042e2d1..b9d1e54 100644
--- a/include/opkele/consumer.h
+++ b/include/opkele/consumer.h
@@ -12,8 +12,13 @@
 namespace opkele {
 
     /**
      * implementation of basic consumer functionality
+     *
+     * @note
+     * The consumer uses libcurl internally, which means that if you're using
+     * libopkele in multithreaded environment you should call curl_global_init
+     * yourself before spawning any threads.
      */
     class consumer_t {
         public:
 
@@ -30,12 +35,18 @@ namespace opkele {
             /**
              * retrieve stored association. The function should be overridden
              * in the real implementation to provide persistent assocations
              * store.
+             *
+             * @note
+             * The user is responsible for handling associations expiry and
+             * this function should never return an expired or invalidated
+             * association.
+             *
              * @param server the OpenID server
              * @param handle association handle
              * @return the autho_ptr<> for the newly allocated association_t object
-             * @throw failed_lookup in case of error
+             * @throw failed_lookup if no unexpired association found
              */
             virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0;
             /**
              * invalidate stored association. The function should be overridden
@@ -47,8 +58,14 @@ namespace opkele {
             /**
              * retrieve any unexpired association for the server. If the
              * function is not overridden in the real implementation, the new
              * association will be established for each request.
+             *
+             * @note
+             * The user is responsible for handling associations and this
+             * function should never return an expired or invalidated
+             * association.
+             *
              * @param server the OpenID server
              * @return the auto_ptr<> for the newly allocated association_t object
              * @throw failed_lookup in case of absence of the handle
              */
diff --git a/lib/consumer.cc b/lib/consumer.cc
index dd8e150..af309c1 100644
--- a/lib/consumer.cc
+++ b/lib/consumer.cc
@@ -143,8 +143,10 @@ namespace opkele {
             p["trust_root"] = trust_root;
         p["return_to"] = return_to;
         try {
             string ah = find_assoc(server)->handle();
+            if(ah->is_expired()) /* TODO: or should I throw some other exception to force programmer fix his implementation? */
+                throw failed_lookup(OPKELE_CP_ "find_assoc() has returned expired handle");
             p["assoc_handle"] = ah;
         }catch(failed_lookup& fl) {
             string ah = associate(server)->handle();
             p["assoc_handle"] = ah;
@@ -160,8 +162,10 @@ namespace opkele {
         retrieve_links(identity.empty()?pin.get_param("openid.identity"):canonicalize(identity),server,delegate);
         params_t ps;
         try {
             assoc_t assoc = retrieve_assoc(server,pin.get_param("openid.assoc_handle"));
+            if(assoc->is_expired()) /* TODO: or should I throw some other exception to force programmer fix his implementation? */
+                throw failed_lookup(OPKELE_CP_ "retrieve_assoc() has returned expired handle");
             const string& sigenc = pin.get_param("openid.sig");
             vector<unsigned char> sig;
             util::decode_base64(sigenc,sig);
             const string& slist = pin.get_param("openid.signed");