Add Gatsby Cloud Content Sync support (Next-gen Preview)

[TylerBarnes]

This PR adds next-gen Gatsby Cloud Preview to the Gatsby Contentful App in a backwards compatible way.

Content Sync is Gatsby's new Preview loading service which has many advantages over the old way of handling previews.
The user updates their content and presses "Open Preview". They're redirected to a loading page on Gatsby Cloud which waits for the associated build to complete and then redirects the user to the correct page once the updated content is available. The loading page also handles build errors and will let the user know if the build they're waiting for fails.

Check out this demo to see it in action:

content-sync-contentful-demo.mov

Backwards Compatibility

The changes in this PR have been crafted to only modify the apps behaviour when the user configures Content Sync in the installed app settings. This is done by copy/pasting the "Content Sync URL" from their Gatsby Cloud dashboard into the app settings. If the user doesn't configure this, the app will continue to function as it did before this PR was introduced.

Routing

There's no need for the user to manually configure slug patterns anymore. The changes in this PR allow Gatsby to route the user to the correct page automatically. This applies for entries that have a direct correlation with a page as well as entries that have no associated page but are queried on a page.
This means that in addition to slug patterns being obsolete, there is additional functionality in that the user can preview any entry or child entry from anywhere and be routed to a page where they can view their changes on the frontend of their Gatsby site.
If a user attempts to preview an entry which has no associated page and isn't queried anywhere the UI will go into an error state and explain that this content isn't shown on the frontend of the site anywhere.

App Settings UI

Slug patterns are no longer required and all content models can be previewed without additional configuration. Because of this we've automatically added the "Open Preview" button to all content models when the user configures Content Sync.

We've also taken some time to clean up the settings UI by moving non-essential settings into an "Advanced" accordion section and hiding the slug patterns section when the Content Sync URL field is filled.

Quick Connect

Gatsby Cloud quick connect has already been updated to automatically configure Content Sync when deploying a new Contentful/Gatsby site.

Source Plugin Changes

The changes in this PR also require an update on the source plugin side of things. The required changes will be published by tomorrow (today is Oct 14th) gatsbyjs/gatsby#33531.

Users will be required to update to the new version of the source plugin as well as the latest version of Gatsby core to use Content Sync. As this feature is currently opt-in this wont disturb existing Preview users. Users that configure Content Sync will see an error state in the Content Sync UI if they haven't upgraded, and the docs explain that this upgrade is required.

User-facing documentation

We've added a shortened URL http://gatsby.dev/contentful-preview-docs below the new "Content Sync" setting which currently redirects to a notion page on installing a beta of these changes. We're working on public facing docs and the link will redirect to those docs instead once this PR is ready to go live.

Webhooks

As these changes require the user to press "Open Preview" each time they make changes in order to update Content Sync, we've removed the debounced webhooks that fire every second as a user is updating content.
In doing this we've realized that there isn't a way for this app to reliably tell when Contentful has saved changes in the UI.
As a temporary workaround, when the user presses "Open Preview" we wait a few seconds before opening the preview, and then in the following 10 seconds after opening Content Sync, we refresh the Content Sync window with updated data if the Contentful UI saves the entry after the user opens Content Sync.
Discussion about this can be seen here https://gatsbyjs.slack.com/archives/CGS0Q95PE/p1632868387059900
Once sdk.entry.save() and sdk.entry.publish() are available we will be able to remove this workaround, but for now it's working reliably.

How Content Sync works

In order to make this system work for CMS's, source plugins, Gatsby Cloud, and Gatsby core all at once, we've created an ID format that all 4 can understand and agree upon. This is the "Node Manifest ID". This is an ID which is tied to a specific node, at a specific point in its revision history, in an unencoded format that the CMS and source plugin can both easily generate and understand.

For Contentful this ID is patterned as [spaceID]-[entry.id]-[entry.updatedAt] for ex vkdbses00qqs-4FjeXiNhhSsOGGW8iGekuZ-2021-10-14T17:44:55.565Z. When this app opens the Content Sync UI in a new tab, it passes this ID to the UI and the UI waits for this ID to be ready to view.
When the source plugin pulls content from the Preview API it generates this same ID format from recently updated entries and calls a new Gatsby core action to let Gatsby know to generate a manifest file linking this ID to the entry that was updated.
This manifest file is deployed with the frontend of the site and the Content Sync UI reads this file to know where to redirect the user.

This allows Content Sync to work for content updates as well as for routing to previous content updates that have already finished. If a user presses "Open Preview" without modifying the entry, they will be routed to the right page very quickly. If they update the entry data, Content Sync will wait for a new manifest file to be deployed with the latest changes before redirecting the user.

Peep this simplified diagram for an overview!

Trying it out

You can deploy this Gatsby starter to Gatsby Cloud to try this feature out. It works with the Contentful default blog example data.
There are also setup instructions to try it out with an existing Contentful site.

[TylerBarnes]

Thanks @Jwhiles ! Let's wait to merge this until next week in case there's any unexpected support needed after merge.

[TylerBarnes]

@Jwhiles ready to merge anytime 😄 thanks again!