boardgame.io: Improve client error handling

Gah. I had some health problems come up and totally dropped the ball on this for like 2 years. I’ll try to get caught up and see if any of this still applies/is useful but no promises on timeline.

I’m looking forward to this feature 😄

Sounds great to me. The intermediate plumbing layer is unaffected by this discussion.

Oh, I’m not saying there should be no call site API. I totally understand that for certain implementations it would be preferable to have that way to associate action with error. I just also think there should be a way for code that didn’t dispatch an action to find out there was an error without the need for additional user-implemented infrastructure such as global error contexts or a message bus, which each call site needs to individually remember to tap into. For a hypothetical ErrorMessage component in React or plain JS there is no difference whether it gets its value from the boardgame.io client or from some user-land infrastructure — an error just shows up — but for the developer the difference is they have to build that infrastructure and I think we have a pretty clear path to providing a simple API they can use when they don’t need the fine-grained control of your examples.

Writing a component that consumes a declarative error object and displays it when it’s defined is a pretty simple concept to grasp, especially for less advanced users. It’s important to remember that not everyone is comfortable wiring up their own carefully calibrated infrastructure that filters and funnels errors — or that people may want a quick and easy way to access error for debugging purposes before building a system to decide what to display, what to log, what to ignore.

My proposal was just to tackle the “simple” API first as a way of getting all the plumbing in place and then add the call site API, but if you want to try this in some other order or all at once, that’s also fine by me 🙂

Thanks for putting this together @shaoster. I think we’re missing a step here before we tackle the move/event call sites.

The fundamental boardgame.io model currently looks something like this (starting bottom left with the move/event action):

When a client calls a move/event, that action is created and the client starts processing it. In the simplest case (no local or socket.io multiplayer) this completes synchronously and the client notifies all subscribers by calling their callback with the new value of state. In this synchronous model, returning a result from a dispatcher might be plausible.

However, when multiplayer is in play, things get more complicated:

• A game can set client: false on a move to indicate that the move must run on the server (usually because it relies on secret state).
• A plugin can declare that it must be run on the server. For example, if a move uses the randomness API, that will force it to run on the server (also because PRNG state is secret).
• Some events also run on the server exclusively.

So we actually have two update paths (solid blue and dashed red arrows in the diagram):

1. The action is allowed to run locally, so the local reducer completes and notifies subscribers synchronously with the updated state. At some point in the future the server update will also arrive, but will be ignored by the client that updated optimistically.
2. The action is not allowed to run locally, so the local reducer does not update state, calling subscribers synchronously with the unchanged state. When the server update is received, the client will call subscribers again with the now updated state.

The implication is that any call site API must be asynchronous (I’d recommend by returning a promise), because we can’t know ahead of time if we can definitely complete the full update cycle synchronously. For case 1, the optimistic update or error could be used to immediately resolve call-site promises. For case 2, the call-site promises should be resolved only once the server update/error is received.

I would propose before working on the call-site API, we should first focus on the existing basic API, which will in any case be a pre-requisite for call-site promises. It will also get the infrastructure set up needed for transmitting the error from the server to the client. I propose updating the client subscription callbacks so they receive (state, error) instead of just (state), so a plain JS user of the client can do something like:

// state should be defined even when we provide error to preserve backwards compatibility
client.subscribe((state, error) => {
  if (error) console.error(error.type);
});

client.moves.invalidMove();
// logs 'action/invalid_move'

The React client abstracts the plain JS client by spreading state into a board component’s props. I guess we would add the error there directly, so a board might look like:

const Board = ({ moves, error }) => {
  return error
    ? <p>Error: { error.type }</p>
    : <button onClick={() => moves.invalidMove()}>Move</button>;
};
// Clicking the move button causes the paragraph to read “Error: action/invalid_move”

I’m also open to a more descriptive name, like actionError, which is more important in React because it’s a named prop rather than just a function parameter.

According to this model the parts of closing this issue are:

1. Raise error transients from the reducer (done in #940).
2. Wire up server, client, and reducer to pass errors to subscribers.
3. Emit errors from the server for the errors the master raises (not just reducer errors)
4. Set up a call-site API to allow for action dispatchers to return promises.

What do you think?

I’ll take a stab at this.