OpenID for Node.js v0.2.0 released

I am pleased to announce the release of OpenID for Node.js v0.2.0. It deserves a blog post since the new version is a bump of the minor version number. What does this mean to the users of the library?

API changes

The API of the entire thing has changed. All callbacks exposed and used by the library are now on the form callback(error, args). This convention is familiar to Node.js developers, and gives us the advantage of simpler integration with other libraries, as well as a slight increase in the fidelity of error messages.

What has changed?

• authenticate now expects a callback which will be called with (error, authUrl). Existing code which expects (authUrl) will not get an authUrl (but possibly an error instead), and so authentication won't work after upgrade until you change your code.
• verifyAssertion also expects a callback of the same form, which will be called with (error, result). Again, existing code depends on receiving a (result) call, and will break.
• loadAssociation and saveAssociation must now accept a callback on the form (error, result) as an additional parameter. Previously, these functions were synchronous, so existing implementations will have to adapt so they call the callback rather than return.

What is new?

As usual, we have fixed several bugs. The library is gaining a community, and there have been several contributions along the 0.1 release path leading up to 0.2.0. Thank you all for your participation!

Apart from the changes above, 0.2.0 also introduces a discovery cache for caching discovered information. This cache is used to avoid additional HTTP requests when verifying assertions from the OpenID providers. The default cache is an in-memory cache, but you can implement your own by overloading two functions:

• loadDiscoveredInformation(claimedIdentifier, callback) is expected to look for and load a cached provider for the given claimedIdentifier. It is expected to call callback(error, provider) when finished, with either an error or a provider (duh).
• saveDiscoveredInformation(provider, callback) is expected to cache the given provider. The key for this object is provider.claimedIdentifier, which loadDiscoveredInformation uses for lookup. After saving, the function is expected to call callback(error) with an error if something failed, or nothing if all went well.

I have been very reluctant to make these significant API changes, but the recent development, reported issues, and feature requests have convinced me that a unified API, and a more familiar API for Node.js developers, is the right way. Also, adapting to the new API is a pretty easy process. I hope you agree with me that the introduction of these changes is best in the long run.