Client <-> Server version handling (Version Mismatch Errors)

[ErisDS]

As Ghost grows up, and we're doing bigger migrations and other changes between versions, we're starting to feel the need to be a bit smarter about updating, particularly around the client - server split.

We need a way for a client (particularly the admin client) to know when the server side is running a version ahead of it, so that it can prompt users that they need to refresh. This is particularly important when the data model changes, to prevent the client sending invalid data to the server.

This needs to be implemented in a robust way, that lets us handle API versioning in a better way in future and that will also work for clients other than the Ghost Admin.

As of TryGhost/Admin#38, the admin client sends an X-Ghost-Version header with every request to the API. This sends the first two digits of the version number (e.g. 0.8) to the server, to say "this is the version I'm expecting you to be right now".

On the server side, we need to add some middleware to receive that header, and return a brand new "400 Version Mismatch Error" if, for example, the server is running 0.9. This is not as straightforward as it sounds, because our error handling for the API doesn't use middleware properly and so the error doesn't get correctly sent as JSON... I have a WIP PR for the middleware, but the error refactor should probably land first.

Once we are correctly sending Version Mismatch Errors from the server, we need to update Ghost-Admin to handle those errors, and show the user a "Please refresh to update" message. Due to the use of minor-version numbers, this message will only be appearing for minor updates e.g. 0.8 -> 0.9, not patch updates like 0.9.0 -> 0.9.1. Therefore, if we want to change bits of the data model, we really need to do minor version bumps - we've always done this in the past, but it has now become more important.

Version Matching Tasks:

• Ghost-Admin: Send X-Ghost-Version header (@kevinansfield)
• Ghost: Refactor API error handling to use middleware correctly
• Ghost: Handle X-Ghost-Version header with Version Mismatch Error if needed (@ErisDS)
• Ghost-Admin: Handle Version Mismatch Errors gracefully, explaining to the user they need to restart (@kevinansfield) - 400 "Version Mismatch" error handling Admin#104

[ErisDS]

Ok - the error handling issue here was a false alert - I'd just wired my middleware up incorrectly 😞

I had totally missed/forgotten the fact that we do have error handling middleware on the API

Ghost/core/server/routes/api.js

Line 138 in 01ae7ae

, and thought we were solely relying on the catch here:

Ghost/core/server/api/index.js

Line 240 in 01ae7ae

}).catch(function onAPIError(error) {

As we do in fact have error handling middleware in place correctly, I just needed to move my wiring for the middleware from the blogApp to the API router, and bobs your uncle it all works.

PR INCOMING

[acburdine]

Now that the client PR was merged in I think this can be closed 😄