API: allow to query only active games

[janKir]

Currently, the GET /games/:game API endpoint lists all existing games. It includes also games that are already finished and also outdated games that were started days ago but never finished.
It would be nice to allow handing query parameters to the endpoint to only receive active / recent games.

I know this filtering could be done on the client but this doesn't resolve the issue that with every new game, this response is getting bigger and bigger.

[delucis]

Yes, this would be nice. There are some things that are relatively easy to add like filtering out completed matches by checking the metadata’s gameover field. How would you suggest measuring active vs inactive? We would probably need to add some kind of lastActive or modified timestamp to the metadata and update it on every game action.

Ideally, this would also be implemented in the Storage API as most backends would probably support filtering entries more efficiently than looping over the full list on the server.

[janKir]

I think it would make sense anyway to add timestamps like createdAt, updatedAt and finishedAt.
Doing it in the storage sounds good, but how should we handle the potential incompatiblity to existing storage packages?

[delucis]

We can add additional fields to the metadata during the game creation process here:

https://github.com/nicolodavis/boardgame.io/blob/41d77da5c846a9a375e1be510985edd678010c21/src/server/api.ts#L47-L51

And update the type here:

https://github.com/nicolodavis/boardgame.io/blob/41d77da5c846a9a375e1be510985edd678010c21/src/types.ts#L284-L292

In terms of filtering, it should be possible to add this without breaking other storage implementations if we do it by adding to the options object passed to db.listGames:

https://github.com/nicolodavis/boardgame.io/blob/41d77da5c846a9a375e1be510985edd678010c21/src/server/db/base.ts#L37-L39

Implementations that haven’t been updated will simply return all games instead of filtering, which is probably OK until they can be updated. (This is actually already the case with the bundled FlatFile which ignores the listGames options.)

Would you be interested in trying to make this work? If possible, it would be best to base your work on the 0.40.0 branch as there are already some breaking changes to the REST API there.

[janKir]

What do you think how the query options should look like? And how extensive should they be?
I can think of something like this, but not sure if we really need all of those:

export interface ListGamesOpts {
  gameName?: string;
  where?: {
    gameover?: boolean; // true -> only finished games, false -> only unfinished games, undefined -> all games
    createdBefore?: number; // timestamps
    createdAfter?: number;
    updatedBefore?: number;
    updatedAfter?: number;
    gameoverBefore?: number;
    gameoverAfter?: number;
  }
}

[delucis]

I can see gameover being useful and agree with the way you defined the true/false/undefined behaviour.

Thinking about practical uses, the most obvious ones seem to be the updated queries, so a client could get anything updated since its last fetch for example. It would be nice not to overload this (passing on the implementation effort to the storage API maintainers) if no-one is necessarily going to use them. Would gameover, updatedBefore and updatedAfter cover all your use cases?

[janKir]

You're right, it shouldn't get too complicated. Also after having another thought, I'd say we don't need at gameoverAt / finishedAt field since it would always have the same value as updatedAt.

[delucis]

Yes, that sounds good to me.

[delucis]

Closed in #740