Future-Proof Server/Client Compatibility

[PullJosh]

trafficstars

Right now, we only have one server and two clients. If we want to make a change to the API or add a feature, it's relatively simple. We just go in and change all three of them simultaneously.

However, the end goal is to have many different servers and many different clients all working in harmony. Unfortunately, it's a little optimistic to assume that every client and every server will be upgraded after every change is made to the code.

To mitigate this issue, I propose two things:

1. Encourage server updates. Most likely this would be a notification that appears on the client to logged-in admins, although if we're feeling ambitious, might it be possible to also provide an update button within that notification that does all of the git pulling and lerna building and server running automatically? (No idea if this is feasible.)
2. Server introspection endpoint. This would be an API endpoint for showing the server's version number and a list of which features the server supports. Then, if we make a change to the server in the future, we also update the response of that endpoint so that clients can understand exactly how to interact with this particular server.

Thoughts?

[bates64]

a list of which features the server supports

I really like this idea! /api/ already returns { decentVersion } but we could also return decentFeatures, with separate versions for each feature.

{
  decentVersion: "2.1.0",
  decentFeatures: {
    flairs: "0.0.0",
    dogs: "1.2.3"
  }
}

Although, decentVersion is semver-oriented so provided the major version isn't higher than n your client would work (all other changes to the spec would be backwards-compatible). This could be overkill, honestly.

might it be possible to also provide an update button within that notification that does all of the git pulling and lerna building and server running automatically? (No idea if this is feasible.)

npm upgrade -g @decent/cli, I guess. That'd be awesome.

[PullJosh]

npm upgrade -g @decent/cli, I guess. That'd be awesome.

Will that allow the server to automatically reboot itself after updating as well?

[bates64]

We currently don't have a daemonising feature, so no. We could make one, though, with a fancy setup command too:

> npm i -g @decent/cli
> decent new "best-server"

Server name: the best decent server
Admin password: *****
Port [80]:
Under HTTPS proxy: yes

> decent start "best-server"
# server started in background
> decent stop "best-server"

etc.

That's for another issue though.

[towerofnix]

(@heyitsmeuralex:) Although, decentVersion is semver-oriented so provided the major version isn't higher than n your client would work (all other changes to the spec would be backwards-compatible). This could be overkill, honestly.

I'm inclined here - Decent features aren't actually modules or packages of their own, they're just pieces of code in the server. Sure, they're fairly easy to remove or swap or change, but in the end, that really does just mean changing the code of the server and client.

Just checking that the major version of the server is equal to the client should be enough.

@heyitsmeuralex - Just to clarify, though.. As we make bug fixes to the client, we update the patch version of it. As we add features to it, its minor version goes up. And so on. But how does that match the server? Or, how do we check that the server and the client have matching semantic versions, if those semvers are tracked separately? We might, for example, implement two major changes to the server - two major semvers - then implement them in one go to the client - one semver. So then we have 2.x.x and 1.x.x, and those don't match...

[bates64]

@towerofnix I was under the impression that the the client ver = server ver = spec ver. The client itself doesn't need to adhere to SemVer (it's an app, it has no outward-facing interface) and the server simply adheres to the spec and inherits its version.

If the client is 2.14.0, it was released at the same time as server 2.14.0. Both adhere to spec 2.14.0, which is backwards-compatible with all versions later than and including 2.0.0. The spec might have been released earlier than the server/client implementation.

[bates64]

Looks like @towerofnix and I on the same page-

1. :+1: to encourage server updates
2. :no_good_man: to server introspection - a version number is enough

[towerofnix]

@heyitsmeuralex Sounds good. Does this mean that pull requests which target only the client shouldn't have semver labels, since the client's semver depends solely upon the server?

[bates64]

No - the client can be bumped to 1.3.0 while the server is left at 1.2.4, provided the spec is >=1.3.0.

Realistically though, all three will get updated at once. If a commit is a breaking change to the server, the spec must change to reflect that, so the PR gets semver: major anyway.

[bates64]

Note we will need to allow servers to decide when to ask for an update, for encourage server updates. We don't want to check this repo specifically, because custom servers. I'm thinking it should be returned as part of GET /api/?

GET /api/

{
  decentVersion: '1.0.0-preview',
  needsUpdate: true
}

[bates64]

RE: server introspection; although we shouldn't need this I think that optional parts of the API would be nice. We already have an optional image-upload endpoint - the server can just say they're not allowed. We should do the same for #257 - it's up to the server implementation - it can just say NO_CALLS_ALLOWED or something if it doesn't support calls.