upgrade

The upgrade plugin offers a document made from a Hyperclay template the newer version of that template, once per load, to whoever can edit it. Nothing is replaced until that person accepts.

Who is asked#

The plugin asks canEdit, and it does not ask a draft: a visitor cannot act on an offer, and a draft is not the document the source would replace. On a page that is neither, nothing is fetched at all.

It is also silent when the page carries no template metas, when the network or the fetch fails, when the published HTML does not match the digest its manifest names, and when the published version is not newer.

The offer works in view as well as in edit, because it asks a capability and not a mode. Opening the menu or choosing Edit is never an upgrade: the upgrade runs only from a click on its own menu item, or on the Upgrade action of its notice.

The two metas#

A copy made from a template says where it came from:

<meta name="hyper-source" content="https://hyperclay.com/templates/kanban/owned/latest.html">
<meta name="hyper-version" content="1.0.0">

hyper-source is the published template’s HTML, and its manifest is the same URL with .json in place of .html, which holds { id, variant, version, html, sha256 }. hyper-version is the version this copy was made from. A page whose hyper-source points at itself is the source rather than a copy of one, and is offered nothing.

The check#

The manifest is read at most once every 24 hours. The answer is cached in local storage under the manifest’s URL and the version this copy has, and a cached answer younger than 24 hours is used as it stands.

The plugin fetches the HTML the manifest names and hashes it with SHA-256. A digest that is not the manifest’s sha256 ends the check with nothing offered: bytes that do not hash to the published version are not that version. So does a version that is equal to this copy’s, or older.

The offer#

With the menu loaded, the offer is a menu item reading Upgrade to version followed by the published version, with a dot on claygoo. Without a menu it is a persistent notice with Upgrade and Not now. Not now remembers that version, and that version is not offered again.

Either one dispatches clay:upgrade-requested on the document with detail: { version, html, sha256, latestUrl }: the published version, the absolute URL of its HTML, that HTML’s digest, and the manifest’s URL. The click lands there and nothing has been written yet.

The run#

The click draws a modal. It says the page’s layout and code are replaced and that the current version stays in the document’s history, and it offers Upgrade and Cancel. A host that keeps no version history also gets Download a copy first, and Upgrade stays disabled until that copy is downloaded.

An upgrade is one document operation, so a mode switch cannot start its save barrier in the middle of one and two upgrades cannot interleave. The run then:

1. Flushes the saves when the page is in edit, and stops if a save could not be settled.
2. Fetches the manifest again, and checks that it is for this template and variant, that its version is newer, and that its HTML is served from the template host.
3. Fetches the HTML, and checks its SHA-256 against the manifest once more.
4. Runs the transformations the template declares over the page as it stands.
5. Refuses with lost when a saved value would not survive the new version, and names it. Nothing is written in that case.
6. Saves the new HTML through the document’s own replace, with the ETag it last saw.
7. Reloads the page.

A refused upgrade leaves the document as it was, and the modal says why.