chore: Add comments and refactor for readability

lib/clerk/authenticate_context.rb

@@ -179,8 +179,7 @@ def decode_publishable_key(pk)
         end
 
         def retrieve_from_query_string(url, key)
-            request_qs = Rack::Utils.parse_query(url.query)
-            request_qs[key]
+            Rack::Utils.parse_query(url.query)[key]
         end
     end
 end

lib/clerk/authenticate_request.rb

@@ -119,9 +119,12 @@ def resolve_handshake(env)
 
             session_token = ''
 
+            # Return signed-out outcome if the handshake verification fails
             handshake_payload = verify_token(auth_context.handshake_token)
             return signed_out(enforce_auth: true, reason: TokenVerificationErrorReason::JWK_FAILED_TO_RESOLVE) if !handshake_payload
 
+            # Retrieve the cookie directives included in handshake token payload and convert it to set-cookie headers
+            # Also retrieve the session token separately to determine the outcome of the request
             cookies_to_set = handshake_payload[HANDSHAKE_COOKIE_DIRECTIVES_KEY] || []
             cookies_to_set.each do |cookie|
                 headers[COOKIE_HEADER] ||= []
@@ -132,6 +135,7 @@ def resolve_handshake(env)
                 end
             end
 
+            # Clear handshake token from query params and set headers to redirect to the initial request url
             if auth_context.development_instance?
                 redirect_url = auth_context.clerk_url.dup
                 remove_from_query_string(redirect_url, HANDSHAKE_COOKIE)
@@ -140,25 +144,10 @@ def resolve_handshake(env)
                 headers[LOCATION_HEADER] = redirect_url.to_s
             end
 
-            if !session_token
-                return signed_out(reason: AuthErrorReason::SESSION_TOKEN_MISSING, headers: headers)
-            end
+
+            return signed_out(reason: AuthErrorReason::SESSION_TOKEN_MISSING, headers: headers) if !session_token
 
-            begin
-                claims = verify_token(session_token)
-                return signed_in(env, claims, session_token) if claims
-            rescue JWT::ExpiredSignature, JWT::InvalidIatError => e
-                if auth_context.development_instance?
-                    # TODO: log possible Clock skew detected
-
-                    # Retry with a generous clock skew allowance (1 day)
-                    claims = verify_token(session_token, timeout: 86_400)
-                    return signed_in(env, claims, session_token) if claims
-                end
-
-                # Raise error if handshake resolution fails in production
-                raise e
-            end
+            verify_token_with_retry(env, session_token)
         end
 
         def handle_handshake_maybe_status(env, **opts)
@@ -230,6 +219,27 @@ def verify_token(token, **opts)
             end
         end
 
+        # Verify session token and provide a 1-day leeway for development if initial verification
+        # fails for development instance due to invalid exp or iat
+        def verify_token_with_retry(env, token)
+            begin
+                claims = verify_token(token)
+                return signed_in(env, claims, token) if claims
+            rescue JWT::ExpiredSignature, JWT::InvalidIatError => e
+                if auth_context.development_instance?
+                    # TODO: log possible Clock skew detected
+
+                    # Retry with a generous clock skew allowance (1 day)
+                    claims = verify_token(token, timeout: 86_400)
+                    return signed_in(env, claims, token) if claims
+                end
+
+                # Raise error if handshake resolution fails in production
+                raise e
+            end
+
+        end
+
         def sdk
             Clerk::SDK.new
         end