The client needs to handle OAuth-related errors in a user-friendly way

[seanh]

When the client is using OAuth tokens to authenticate to the API (currently this only happens when the client is embedded in a partner site) there are at least four things that can go wrong:

1. The client fails to get the grant token from the partner's web page (for example: the partner site has not inserted the grant token into the page properly)

2. The client's request to the hypothes.is API for an access token fails (for example: the grant token from the client site is invalid)

3. The client has to refresh the access token every hour, because they expire. One of the client's refresh requests to the hypothes.is API could fail (for example: if the user suspends their laptop, or loses their internet connection, so that the access token expires before the client has a chance to send a refresh request).

4. One of the client's requests that try to use the access token fails (e.g. to retrieve annotations from the server, or to make a new annotation, or just to get the user's profile information, etc). This could happen if any of the above three problems happened and then the client still tried to use the access token, or it could happen for some other reason.

Currently the only remedy, when any of the above happen, is for the user to reload the page. This will re-start the whole process: the partner site inserts the grant token into the page, the Hypothesis client extracts the grant token from the page, the client exchanges the grant token with hypothes.is for an access token... And hopefully whatever went wrong won't go wrong again.

When any of the above happen I think we need to show the user some sort of error message to the effect of "Logging into Hypothesis failed, try reloading the page".

I think there are two basic kinds of error message that we could show here:

1. Each time when the user tries to use the access token (for example when they try to make an annotation) and it fails, we can show an error to the user. So for example if you suspended your laptop and your access token expired, and then you opened up the laptop again and started trying to use h on a partner page without reloading the page, then every time you try to do something (like create an annotation) you'll see an error telling you to try reloading the page.

   This is how this sort of error message currently looks in the client - the error message from the server is shown in a red bubble that disappears after a while, and if the user tries to create an annotation (or whatever) again and the request fails again then they get the bubble again:

   

   We would need a better-worded error message, of course.

2. Rather than waiting for the user to try to do something such as create an annotation, as soon as something goes wrong (the client fails to retrieve the grant token from the page; or the client's access token request fails; or a refresh fails; or the access token expires) the "you need to reload" error message appears as some sort of "banner" (a permanent error message that does not disappear after a few seconds like the bubbles shown above do).

   This is nicer because the user sees immediately that it's not working and they need to reload the page, rather than everything looking fine until they've typed out an annotation and try to save it.

   I don't think we have any error message of this sort in the Hypothesis client currently, but here is an example from Slack: with Slack open turn off your internet connection, wait a few seconds, and this appears:

   

   Turn on your internet connection again and it disappears by itself.

I think 1 is needed, 2 is a bonus.

When 2 happens we could also disable the client so that you can't try to create an annotation etc, preventing further occurrences of 1. This would be another bonus.

[seanh]

In addition to showing an error to the user, we may also want to log these failures somewhere for debugging and/or so we know how often this sort of thing is happening.

Just log errors to the console?

Or report them back to hypothes.is somehow?

[seanh]

I said above that with our current toaster-bubble type error messages we don't have a good way to display a permanent error message on screen like the one in the Slack screenshot above, but I've been looking into the library that we use for these errors (see their demo) and it turns out you actually can.

This would be an error message that appears in the top right on top of the sidebar, as the current error messages do, but it would stay there forever until you reload the page, and would not disappear. It would look something like this:

It's possible that we can add a button to this error message that, when clicked, will reload the page (but I'm not sure whether we can actually do this - it would require JavaScript code in our different-origin iframe to force a reload of the parent page).

So this seems like a decent solution to this issue to me: if the client loses its connection to the Hypothesis server, e.g. because its refresh token times out, then it just starts showing an error message like the one above all the time, telling the user they must reload the page. If possible with a clickable button in the error that does the page reload, but if not possible then not.

[seanh]

@ajpeddakotla ^

[seanh]

It's possible that we can add a button to this error message that, when clicked, will reload the page (but I'm not sure whether we can actually do this - it would require JavaScript code in our different-origin iframe to force a reload of the parent page).

Actually I think this should be doable, we just may need to send a message over the bridge to the src.annotator code to have it reload the page for us.

[seanh]

I think this issue is probably pointable and playable now

[seanh]

hypothesis/client#376 (not finished or merged yet) at least shows an error message when the client gets into this logged out / broken state, telling the user that they need to reload the page.

But there is still a problem that, even though a "You must reload" error is showing, the user can still click on various buttons (reply to an annotation, etc) and get various different error messages and broken behaviors.

A suggestion that has been floating around is that we need to put the client into a "read-only" mode where all these broken buttons are still visible but are disabled (and the "You must reload" error is showing). Buttons we would need to disable:

• Changing the focused group via the groups dropdown to a private group (although this dropdown is not currently present on publisher embeds, so not a problem right now) (changing group sends a request to the API to get the newly selected group's annotations, and if it's a private group this request won't work when the oauth token is expired) (the group that is already selected when the access token expires is not a problem, even if it's a private group)
• Creating a new annotation
• Creating a new highlight
• Creating a new page note
• Replying to an annotation
• Editing an annotation
• Deleting an annotation

I think that's it

[seanh]

@ajpeddakotla This only applies to "third-party groups" (i.e. eLife) and won't apply to the new first-party open and restricted groups. In this case, should we remove the groups label from this? (Maybe we need a separate 3rd-party groups label or just use the eLife label.)