LX-306 Collaborative mapping, with edits locked to one user

[rogup]

What? Why?

Closes #306, #307 and #308

This PR adds the following functionality:

• The owner of a map can share a map to an email address with either read/write access. When the Share modal is opened, the list of current users with access is shown, and can be edited. Changes take effect when 'Save' is clicked.
• When a user starts editing a map (not including changing the zoom or map position), the map becomes 'locked' to this user. This means that for other users with write access, a toast is displayed showing the initials of the user who is now editing, and their map changes to read-only mode.
• Whilst a user is editing a map, other clients viewing the map will refresh the map data every 30s.
• When the editing user closes their map (e.g. closes the browser or opens a different map) or hasn't made any edits for 5 mins, the map gets 'unlocked', and all other clients viewing the map will do a final refresh of the map data. Another user can then acquire the lock by making an edit.
• If something goes wrong which causes the FE client to not receive updates about the map lock, they will get a 503 error if they try to make an edit. It will also trigger the backend to re-notify the client about the lock, so their map should visibly change to read-only mode as intended.

In order to achieve the two-way messaging required for map locking, we have created a WebSocket architecture. This diagram shows the different WS messaging flows that have been implemented.

What should we test?

Test the behaviour described above. e.g.

• try sharing a map with multiple users, then changing / revoking / re-granting access
• try sharing a map to a user that doesn't exist yet and check that they are sent an email inviting them to LX (and then can access the map after registering). This area of the code was fixed and refactored.
• play around with viewing and editing a map simultaneously with different users on different browsers, and test that read-only mode and the toast always displays correctly, and that map locks are released in all the different ways that a user might close or stop working on a map.
• do a bit of investigation into what happens when internet connection is unstable or disconnects. This might affect websocket functionality

Release notes

Deployment notes

When deploying on prod:

• the staging.app.landexplorer.coop-le-ssl.conf Apache2 conf file needs to be updated on the server to handle websocket connections - copy this over from the staging server.
• we also need to enable websocket proxy tunnels for this to work, with the command sudo a2enmod proxy_wstunnel
• the ROOT_URL in the front-end repo config/.env needs to be fixed, to remove the /api suffix. This was configured incorrectly, so up till now, API request URLs have contained a duplicate /api segment, e.g. https://staging.app.landexplorer.coop/api/api/user/map/view. This didn't work when using Socket.IO since it impacts the namespace functionality. Note that there is also a tweak to the \api part of staging.app.landexplorer.coop-le-ssl.conf to reflect this.

Documentation updates

There is a Wiki here which outlines our strategic direction for simultaneous map edits (with locking) https://github.com/DigitalCommons/land-explorer-front-end/wiki/Strategic-Direction#simultaneous-map-editing

Not that we also didn't include unit tests as part of this work due to budget constraints. We need proper unit testing for any future work in this area, since it's complex and there is a high risk of bugs.

[lin-d-hop]

This is looking really great team! I think there are a few little bits that might be a bit confusing for people, but overall the behaviour looks correct to me and I think this is ready to go out into the wild!! I've spent quite a bit of time today testing and summarised the testing notes here.

I'll do a little more testing mocking a flakey connection and then I think we are good to go.

[lin-d-hop]

Spent a chunk of time this morn testing a browser going online and offline while editing. Everything worked exactly as expected. II played with three different sessions interacting with the same map. I'm happy to move this one into release mode :)