Document how SigningKeyResolver implementations should signal there's no matching key

Is your feature request related to a problem? Please describe. When building an implementation for SigningKeyResolver, the Javadocs for the interface provide no hints as to how an implementation should react when it cannot find a key. Returning null is not handled by the calling code in JJWT, so it appears the correct thing to do is throw an exception. It would be nice if the Javadocs simply stated explicitly what an implementor should do.

Describe the solution you’d like Update the Javadocs to indicate how SigningKeyResolver implementations should react when there’s no matching key.

Additional context I ended up implementing my SigningKeyResolver to throw a SignatureException, since that seemed to be what the surrounding code in JJWT would do (for example, if a key was returned but could not verify the signature).

[bturner]

HeaderException doesn’t feel like the right fit for this, to me, because there’s nothing wrong with the headers (necessarily). I’d expect that to be more related to parsing than resolving keys. NoSuchKeyException or UnknownKeyException or MissingKeyException, something more indicative that the system tried to resolve a key but couldn’t find one, that would be my vote.

Alternatively, if any exception my resolver throws is simply going to be passed through as-is, rather than caught and wrapped, perhaps that’s all the documentation would need to say–that you can throw an application-specific exception that your surrounding code (because we all write good catch blocks, right? :badpokerface:) can catch and handle however is appropriate. I only think a new exception might be needed if the plan is to document that the resolver can return null and JJWT’s internals will automatically throw. (I think it’d be a nice touch if the new exception could include the Header, since those must have been parsed correctly for JJWT to try and look up a key.)

By the way, thanks for considering this. I appreciate the support.

[stale[bot]]

This issue has been automatically marked as stale due to inactivity for 60 or more days. It will be closed in 7 days if no further activity occurs.