Add support for (basic, cached on-visit) offline access using service workers

[rosa]

This PR is a start on bringing proper offline support to Turbo using service workers, which can be useful for PWA, but also for mobile apps built using Hotwire Native.

Main app's side

On the main app side, it can be used like this:

import { Turbo } from "@hotwired/turbo-rails"
// Or however you're importing Turbo into your app

// Then run the following to register your service worker
Turbo.offline.start(scriptUrl, options)

scriptUrl is the URL of the service worker script. For example, the default service worker added by Rails is located at /service-worker.js. This needs to return a MIME type of text/javascript.

options are the following:

• scope: the service worker's registration scope, which determines which URLs the service worker can control. For /service-worker.js, the default would be /. In this way, the service worker can intercept any URL from your app.
• type: this can be classic, which is the default (and it means the service worker is a standard script), and module, which means the service worker is an ES module. This is not currently supported on Firefox, however.
• native: this is a specific option for Hotwire Native support. If true, it'll set a cookie that's needed for Hotwire Native apps to work correctly when a service worker intercepts requests. It's true by default, but if you're not using Hotwire Native you can set it to false.

So, for example:

import { Turbo } from "@hotwired/turbo-rails"

Turbo.offline.start("/service-worker.js", { 
  scope: "/", 
  type: "module", 
  native: true 
})

In a Rails app, this could be placed on app/javascript/application.js or app/javascript/initializers/turbo_offline.js for example.

Service worker side

Your app needs to serve a text/javascript response with your service worker on the URL you've provided to the registration. Maybe you're already using a service worker for push messages, or, if you're not using one at the moment, you can start with an empty response. Then, you can configure offline mode like this:

// if using `type: "classic"
importScripts("url-to-turbo-offline-umd.js")

// if using `type: "module"` (not supported in Firefox), you can do 
// import { addRule, start, handlers } from "url-to-turbo-offline.min"

// Then, add rules for caching  
TurboOffline.addRule({
  match: /\/topics\/\d+/,
  handler: Turbo.handlers.networkFirst({
    cacheName: "topics",
    maxAge: 60 * 60 * 24 * 7,
    networkTimeout: 3
  })
})

// ... more rules if needed

TurboOffline.start()

• match controls what requests the service worker will intercept, and can be a regexp that will be tested against the request's URL, or a function that will get the request object passed as a parameter. By default it's /.*/, which means it'll match all URLs.
• handler: can be one of the following:
  • handlers.cacheFirst: return cached response if exists, without going to the network. If it doesn't exists, go to the network and add it to the cache.
  • handlers.networkFirst: go always to the network first, caching the response afterwards. Fall back to the cache if the network returns an error.
  • handlers.staleWhileRevalidate: return a cached response if available, but always refresh it in the background.

You always need to provide a cacheName, and you can have different rules with different cache names, to cache separate parts in your app. Then, you can also provide the following options, but they're optional:

• networkTimeout: this only makes sense in the networkFirst handler. Basically, the time to wait until falling back to the cache. It's for those cases where connectivity is bad, but it takes a long time to get an error, so you'd be better off using the cached version sooner. In this case, if the timeout was reached but the response is not cached, we'll wait for the network anyway.
• maxAge: in seconds, to delete entries from the cache. The cache trimming process is triggered in the background whenever we add a new entry to the cache or when a cached response is used in the cacheFirst strategy. For now, only deleting by maxAge is supported, and we look at the last time an entry was cached. So, those entries not refreshed in the last maxAge seconds will be deleted. I'd like to add other mechanisms in the future.

For example, if you wanted your service worker to go to the network first, cache everything for at most 24 hours and fall back to the cache after 3 seconds, you could do it like this:

importScripts("url-to-turbo-offline-umd.js")

// Then, add rules for caching  
TurboOffline.addRule({
  handler: Turbo.handlers.networkFirst({
    cacheName: "global",
    maxAge: 60 * 60 * 24,
    networkTimeout: 3
  })
})

TurboOffline.start()

This is still a simple approach, but my plan, if this works, it's to build on this and add more sophisticated mechanisms to pre-cache URLs for offline access before they're accessed, and in a dynamic way, so they don't need to be listed in the service worker beforehand. We need this in HEY's mobile apps, so I'll be extracting that from my work there.

I wanted to get this out as soon as possible to get feedback, ideas and so on. I'll open a corresponding PR to turbo-rails to expose the new @hotwired/turbo/offline.

cc @joemasilotti @jayohms @dhh