RFC: Liveness

[oliverlloyd]

Please see this PR: #3869

In a previous document we discussed the general strategy for how we make liveblogs live. This PR takes that strategy and proposes an implementation based upon it.

In particular, this PR is proposing an approach where we use a react component Liveness to connect and execute the code we want to use to keep the content fresh, but it does not use react to maintain the list of blocks.

What features are included?

• Actually adding the liveness code to the page
• Polling the api
• [state] - Count of new updates pending
• [state] - When to show the Toast button

What is still to be done

• Inserting the html into the dom
• Hydrating the html after it is inserted
• Revealing (animating) the content
• The styling of the Toast component

How can we use react but not use react?

A react component is just a function that returns html. But if you tell the function to return null then it's just a function. If we insert Liveness in the LiveLayout file and wrap it in an Island then this code will be executed at page load.

With this approach we can choose to use react for some things, like rendering the Toast, but use plain javascript for inserting and hydrating the html. It also allows us to use SWR, DCR's react data fetching library, rather than having to introduce or create a second fetching lib to the page.

Pros to hybrid

• We can use SWR - not having multiple solutions for fetching data is a huge win
• We can use react state to show/hide the Toast and keep track of pending updates

Cons to hybrid

• Using a react component as a vehicle to instantiate js functions is non standard

What alternatives are there to this approach?

Instead of using a react component to trigger this code we could just use a script tag. This is a simple, established pattern for running javascript on the page.

Pros to purity

• Simple, well understood
• React does not exist so the code follows traditional flows

Cons to purity

• React (and DCR) was built for a reason, plain javascript does not scale well
• Code is un-scoped, you can do anything!
• We would need to either find a plain javascript lib for fetching data (there are no obvious options) or roll our own (lots of work!)

[oliverlloyd]

Related Trello tickets

https://trello.com/c/jQWODdaU/714-dcr-renders-blocks
https://trello.com/c/9kEvWKzI/708-new-blocks-are-animated-upon-insertion
https://trello.com/c/103EAWfE/709-hydration-works-for-a-single-block
https://trello.com/c/HLK2X1au/704-the-frontend-api-reads-blocks-from-dcr
https://trello.com/c/5EXi8gzE/713-investigate-pure-js-solutions-for-polling
https://trello.com/c/3X3Zm3vT/563-new-blocks-are-inserted-into-the-dom
https://trello.com/c/fPT57oNV/483-refactor-enhance-capi-to-help-support-live-functionality-block-rendering

[DavidLawes]

I really like the linked PR and I think it helps justify the approach: we're able to blend react rendering with plain js. I also like how we're utilising our standard approach for hydration to achieve this. If I were new to the codebase and wanted to achieve something similar this helps reinforce how we hydrate as well as defining patterns that could be expanded/replicated.

I like how Liveness is only defined for liveblogs - I feel like in frontend there was some logic (https://github.com/guardian/frontend/blob/main/static/src/javascripts/bootstraps/enhanced/main.js#L130, https://github.com/guardian/frontend/blob/main/static/src/javascripts/bootstraps/enhanced/liveblog.js#L51) about when the script would run, this solution is more clear about when to execute. I think the clarity is helped by co-locating rendering with the plain js.

Thinking about future requirements for liveblogs (both known and unknown), the ability to do both react rendering and plain js will be beneficial? I don't think these kinds of questions need a defined answer (and probably not worth spending lots of time on), but just wondering:
How can we filter by key events = update the api query params
How can we update modified posts = use plain js to find matching block id and replace content (?)
How can we delete posts = use plain js to find matching block id and remove content (?)
^^ maybe these kinds of considerations will help us form the API/data structure we'll be using?

I like that we've considered alternatives to this approach but I think I'm convinced enough by this to move forward with the idea. Maybe that's just because I'm getting more familiar with Islands though, so would be good to hear other peoples' opinions.

[oliverlloyd]

How can we filter by key events = update the api query params
How can we update modified posts = use plain js to find matching block id and replace content (?)
How can we delete posts = use plain js to find matching block id and remove content (?)

These questions are actually very insightful. I had a meeting with @jonathonherbert and @alinaboghiu the other day and we discussed these very things. Our focus was how the backend api might need to change, we agreed that:

• To delete a post we'd likely want to create some form of tombstone record in CAPI
• This tombstone should be a separate index
• We should look at refactoring the api to fetch new blocks to use lastUpdated instead of a cursor (this gives us updated content + new)

Filtering

We already made a change to the api to accept a new query param and only return blocks based on this. We currently deal with this on the client using a page refresh but once we have client side code to remove/update/insert blocks then I think we could look at using javascript to replace the entire list of blocks on the page, replacing them all with a new filtered (or reordered?) list