Posted
Among static site hosts atomic deploys are a very popular feature. Often mentioned in prime marketing real-estate on the homepage.
Advertising this as a feature is strange because atomic deploys are insufficient at best. At worst they can be considered an anti-feature.
The fundamental issue with atomic deploys is that the web isn’t atomic. Any deployment procedure that depends on an atomic deployment is broken. Not only because it unlikely that these providers provide a truly atomic deployment, (Are they stalling requests at the edge until all involved processes have confirmed the switchover? I doubt it.) but also because an atomic deployment isn’t sufficient or required for seamless deploys.
Deployments that depend on atomic version switches reliably break when a user requests the page before the deploy, then attempts to request referenced assets after the switch.
Let’s have a trivial site. index.html which includes main.js, some handlers in the HTML reference functions in the JavaScript file. We will attempt to deploy a simple function rename. Now consider the following sequence of events:
- User requests
index.html and gets version 1.
- Atomic deploy occurs, version 2 is now active.
- User requests
main.js and gets version 2.
index.html tries to call the renamed function and crashes.
For a simple case like this the timing window is small, but add lazy-loading, caching or even a user with a bad connection and you will have significant windows where the user receives a broken site.
Let’s use the same site from the previous example. However this time the JavaScript file has a unique ID in the filename. This is commonly a hash of the contents, but for simplicity this example will use a version number. This is a common practice to allow long caching of unchanged assets, but when the assets change a new URL will ensure that the new version is fetched.
- User requests
index.html and gets version 1.
- Atomic deploy occurs, version 2 is now active.
- User requests
main-v1.js and gets a 404.
index.html tries to call a function which failed to load and crashes.
Again, the site is broken. This case is possibly even worse because because compatibility between versions won’t help. Any time the JavaScript file changes (and gets a new URL) the request will fail since the old version is no longer available.
The correct way to deploy static sites with absolutely no errors is to split the site’s files into two categories which I call Entries and Assets.
Entries, or “entrypoints” are places where your app is “entered”. The most common example is user-visible URLs. These URLs should be stable over time so that they can be bookmarked. But other things fall into this category too, for example a public JavaScript file that is referenced by third-parties. (For example if you have a widget that can be included in third-party sites.)
In important requirement for Entries is that they must have a stable interface. For an HTML page this is generally quite easy. The interface is “can be viewed in the browser”. However you also want to keep IDs and URL parameters stable so that links don’t break. For a JavaScript file then you should have API stability, you can release fixes but users shouldn’t care exactly what version they get.
In the above example index.html is an Entry.
Everything else is an Asset. Assets should be given versioned filenames and are always referred to by this name. This removes the need for interface stability as every user gets exactly the version that they need.
In the above example main.js is an asset.
The main requirement of the build process is generating a unique path for each changed Asset and ensuring that that all Assets are referenced by this path. The result on our example site would look something like this:
<!-- main.html -->
<script src=main-v2.js></script>
<button onclick="clicked()">Click Me</button>
// main-v2.js
function clicked() {
alert("Hello!");
}
The most important part of the deploy is that you must deploy Assets before Entries and ensure that all Assets from possibly-live deploys are still available. For a simple site like this the calculation could be as simple as the max-age value of the HTML file plus some leeway for download time. For sites that lazy-load resources, Assets could potentially be alive forever! (Maybe a user has had that tab open for 10 years and finally decided to click the “Play” button.) But in general these old files are not too large and can be given a generous time window before cleaning.
The final deployment process looks like this:
- Upload all of the Assets to the site.
- Upload all of the Entries to the site.
- Remove any old Entries (if anything was removed or renamed).
- Clean up old Assets. (Optional)
Note that step 2 is where the new site goes “live”. This can be done atomically (including being done atomically with step 3) if you desire, but there is no real benefit. In fact it may be a good idea to start by serving the new Entries to a small portion of your users and evaluating your metrics before deploying to 100%.
Rollbacks look like this:
- Upload all of the Assets. (Only required if you have cleaned them)
- Upload all of the Entries.
- Remove any old Entries.
It is identical to deploys except that step 1 is probably already done by the deploy. You can still do steps 2 and 3 together atomically if desired.