coldwire-rails 0.1.0

data/lib/coldwire/worker/serve.js

@@ -0,0 +1,226 @@
+// One entry per URL. cache.put() replaces an entry only where the two agree about Vary, and
+// Rails answers HTML with `Vary: Accept` — so precaching (`*/*`) and a Turbo visit
+// (`text/html`) are two records of one page, which WebKit keeps and Chrome collapses.
+//
+// Not ignoreSearch: range and chunk entries share the path with their own query, and a page
+// write must never take a downloaded archive with it.
+async function putFresh(cache, key, response) {
+  await cache.delete(key, { ignoreVary: true })
+  await cache.put(key, response)
+}
+
+async function fetchAndCache(cache, href, { managed = false } = {}) {
+  const request = new Request(href, { credentials: "same-origin" })
+  // Skipped rather than failed: the app asked for this URL never to be stored, and a manifest
+  // that also names it is a contradiction to resolve quietly in favour of not storing.
+  if (isNeverCached(new URL(request.url))) return []
+
+  const response = await fetch(request)
+  if (!isCacheable(request, response)) {
+    throw new Error(response.redirected ? `Redirected to ${response.url}` : `HTTP ${response.status}`)
+  }
+
+  await putFresh(cache, cacheKey(request, { managed }), response.clone())
+
+  const contentType = response.headers.get("Content-Type") || ""
+  if (!contentType.includes("text/html")) return []
+
+  return urlsFromHtml(await response.text(), href)
+}
+
+// Subresources only — do not follow <a href> or this becomes a site crawler.
+function urlsFromHtml(html, pageUrl) {
+  const urls = new Set()
+  const base = new URL(pageUrl)
+
+  const add = (raw) => {
+    if (!raw) return
+    raw.split(",").forEach((part) => {
+      const token = part.trim().split(/\s+/)[0]
+      if (!token || token.startsWith("data:")) return
+      try {
+        const url = new URL(token, base)
+        // Any origin we are allowed to cache, not just our own. A page whose map library
+        // comes off a CDN is not offline-ready without it: precaching the page and skipping
+        // the script it cannot run without leaves a blank screen and a full cache.
+        if (!cacheableOrigin(url)) return
+        if (matchesPath(url, NEVER_INTERCEPT)) return
+        urls.add(url.href)
+      } catch {}
+    })
+  }
+
+  for (const match of html.matchAll(/<link\b[^>]*\bhref=["']([^"']+)["']/gi)) add(match[1])
+  for (const match of html.matchAll(/<(?:script|img|source)\b[^>]*\bsrc=["']([^"']+)["']/gi)) add(match[1])
+  for (const match of html.matchAll(/\bsrcset=["']([^"']+)["']/gi)) add(match[1])
+
+  const importmap = html.match(/<script[^>]*type=["']importmap["'][^>]*>([\s\S]*?)<\/script>/i)
+  if (importmap) {
+    try {
+      const json = JSON.parse(importmap[1])
+      Object.values(json.imports || {}).forEach(add)
+      Object.values(json.scopes || {}).forEach((map) => Object.values(map).forEach(add))
+    } catch {}
+  }
+
+  return [...urls]
+}
+
+// The network answers whenever it can, and the cache is what is left when it cannot. Nothing
+// here second-guesses the browser about what it already holds: an asset is served from the
+// browser's own cache without a request either way, and a worker sitting in front of that can
+// only get it wrong.
+//
+// So the cache is not even consulted until the network has failed. There is no lookup on the
+// path where everything is working.
+async function handleFetch(request, event) {
+  const cache = await caches.open(CACHE_NAME)
+
+  if (forcedOffline) return offlineFallback(cache, request)
+
+  try {
+    const response = await fetch(request)
+    if (isCacheable(request, response) && isAutoCacheable(request)) {
+      // waitUntil rather than a promise left running: a worker can be stopped the moment it
+      // has answered, and a page stored without the stylesheet it names is worse offline than
+      // a page not stored at all.
+      const stored = storeResponse(cache, request, response.clone())
+      if (event) event.waitUntil(stored)
+    }
+    return response
+  } catch {
+    return offlineFallback(cache, request)
+  }
+}
+
+async function offlineFallback(cache, request) {
+  const cached = await cache.match(request, MATCH_OPTIONS)
+
+  return (await cachedPageResponse(cache, request, cached)) || offlineResponse(request)
+}
+
+// A page is stored with whatever it asks for. The lists say which pages are worth keeping as
+// you browse; what one needs in order to render is not a second question, and a page held
+// without its stylesheet is the offline equivalent of not holding it at all.
+async function storeResponse(cache, request, response) {
+  await putFresh(cache, cacheKey(request), response.clone())
+
+  const type = response.headers.get("Content-Type") || ""
+  if (!type.includes("text/html")) return
+
+  const urls = urlsFromHtml(await response.text(), request.url)
+  await Promise.all(urls.map((href) => storeSubresource(cache, href)))
+}
+
+// Only what is missing. A digested address is stored once and then named by every page that
+// uses it, so after the first visit this settles down to a lookup and nothing else.
+async function storeSubresource(cache, href) {
+  if (isNeverCached(new URL(href))) return
+  if (await cache.match(href, MATCH_OPTIONS)) return
+
+  try {
+    await fetchAndCache(cache, href)
+  } catch {
+    // One subresource that will not fetch is no reason to lose the page.
+  }
+}
+
+// Turbo will not render a page whose data-turbo-track="reload" elements differ from the
+// current page's; it reloads instead, to pick up the new assets. Offline there are none to
+// pick up and the reload is answered from this same cache, so it costs a document load that
+// Hotwire Native can hang on.
+//
+// Asset digests change with every deploy, so any page cached before the current one was built
+// disagrees with it — nothing served from this cache is tracked. A live page still is, so the
+// first fresh page after the connection returns still reloads, which is what was wanted.
+function untrack(html) {
+  return html.replace(/\sdata-turbo-track\s*=\s*(?:"reload"|'reload'|reload)(?=[\s>/])/gi, "")
+}
+
+// Everything answered from the cache: untracked always, marked when mark_cached_pages is on.
+//
+// Two markers, read at different moments. The <html> attributes are for the first paint of a
+// cold boot, before any JS runs. The <meta> is for Turbo visits, which merge the head but
+// never copy <html> attributes.
+async function cachedPageResponse(cache, request, cached) {
+  if (!cached || !wantsHtml(request)) return cached
+
+  const type = cached.headers.get("Content-Type") || ""
+  if (!type.includes("text/html")) return cached
+
+  const html = await cached.clone().text()
+  if (!/<html\b/i.test(html)) return cached
+
+  let body = untrack(html)
+
+  if (MARK_CACHED_PAGES) {
+    // The timestamp rides on the stored key, so ask the cache for the key that matched.
+    const [ key ] = await cache.keys(request, MATCH_OPTIONS)
+    const cachedAt = key ? key.headers.get(TIMESTAMP_HEADER) : null
+    const stamp = cachedAt ? ` ${CACHED_AT_ATTRIBUTE}="${escapeHtml(cachedAt)}"` : ""
+
+    body = body
+      .replace(/<html\b([^>]*)>/i, `<html$1 ${OFFLINE_ATTRIBUTE}${stamp}>`)
+      .replace(/<head\b([^>]*)>/i, `<head$1><meta name="coldwire-offline" content="${escapeHtml(cachedAt || "")}">`)
+  }
+
+  // Rewriting changed the length, so the stored Content-Length no longer describes the
+  // body — carrying it over invites the consumer to truncate the page. Drop it and let the
+  // response report its own length.
+  const headers = new Headers(cached.headers)
+  headers.delete("Content-Length")
+
+  return new Response(body, {
+    status: cached.status,
+    statusText: cached.statusText,
+    headers
+  })
+}
+
+// Turbo Drive visits and frame loads ask for HTML; assets and JSON do not. Handing an HTML
+// body to a stylesheet or an <img> just produces a broken asset, so those fail instead.
+function wantsHtml(request) {
+  if (request.mode === "navigate" || request.destination === "document") return true
+
+  return (request.headers.get("Accept") || "").includes("text/html")
+}
+
+function offlineResponse(request) {
+  if (!wantsHtml(request)) {
+    return new Response("", { status: 504, statusText: "Offline" })
+  }
+
+  // A frame request only ever renders a matching <turbo-frame>; the full page would be
+  // discarded and the frame would sit on its loading state forever.
+  const frame = request.headers.get("Turbo-Frame")
+
+  return new Response(frame ? offlineFrame(frame, request.url) : OFFLINE_PAGE, {
+    // 200 on purpose. Hotwire Native treats a non-2xx visit as a failed request and shows
+    // its own native error screen, so an error-status body is never rendered.
+    status: 200,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store"
+    }
+  })
+}
+
+// The frame template is baked when the worker is built, so it cannot know which URL it will
+// stand in for. Substitute it here: a retry link inside a frame has to point at the frame's
+// own URL, since an empty href would resolve to the page and load the whole document into
+// the card.
+function offlineFrame(id, url) {
+  const content = OFFLINE_FRAME_CONTENT.split(RETRY_URL_TOKEN).join(escapeHtml(url))
+
+  return `<turbo-frame id="${escapeHtml(id)}">${content}</turbo-frame>`
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (character) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;"
+  })[character])
+}

data/lib/coldwire/worker/sync.js

@@ -0,0 +1,234 @@
+// Bringing the cache in line with the manifest, without refetching what is already good.
+//
+// Only one runs at a time: the page triggers this on load, and a slow sync must not have a
+// second one pile in behind it.
+let syncing = null
+
+function syncManifest() {
+  if (!syncing) {
+    syncing = runSync().finally(() => { syncing = null })
+  }
+
+  return syncing
+}
+
+async function runSync() {
+  // Force offline is a request to use no network at all. A sync is nothing but network, and
+  // the worker's own fetches do not pass through its fetch handler — so without this it would
+  // quietly go to the network anyway, which is the one thing the switch exists to prevent.
+  if (forcedOffline) {
+    const paused = { ok: false, offline: true, reason: "forced", complete: false,
+                     cached: 0, retired: 0, remaining: 0, failed: [], finishedAt: Date.now() }
+    await notifyClients({ type: SYNC_MESSAGE, state: "finished", ...paused })
+
+    return paused
+  }
+
+  if (!cachingEnabled) {
+    const paused = { ok: false, offline: true, reason: "disabled", complete: false,
+                     cached: 0, retired: 0, remaining: 0, failed: [], finishedAt: Date.now() }
+    await notifyClients({ type: SYNC_MESSAGE, state: "finished", ...paused })
+
+    return paused
+  }
+
+  const cache = await caches.open(CACHE_NAME)
+
+  let manifest
+  try {
+    manifest = await fetchManifest()
+  } catch (error) {
+    // No connection is not the manifest misbehaving, and retrying sooner cannot help. Said
+    // plainly so a page waits for the network instead of counting it as a failed attempt.
+    const failure = { ok: false, error: error.message, offline: Boolean(error.offline),
+                      complete: false, cached: 0, retired: 0, remaining: 0, failed: [],
+                      finishedAt: Date.now() }
+    await notifyClients({ type: SYNC_MESSAGE, state: "finished", ...failure })
+
+    return failure
+  }
+
+  const wanted = new Set(manifest.map((value) => cacheUrl(new URL(value, self.location.origin).href)))
+
+  // Retire what the manifest dropped — an unpublished site, say. Only entries the manifest
+  // owns, so assets and ordinary browsing are left alone.
+  const retired = await retireUnlisted(cache, wanted)
+
+  // Fetch what is missing (a new site) or past its age (a stale one). Everything else is
+  // already good and costs nothing.
+  const now = Date.now() / 1000
+  const pending = []
+  for (const href of wanted) {
+    const [ key ] = await cache.keys(new Request(href), MATCH_OPTIONS)
+    const at = key ? unixTimestamp(key.headers.get(TIMESTAMP_HEADER)) : null
+
+    if (!key || !at || (REFETCH_AFTER !== null && now - at > REFETCH_AFTER)) pending.push(href)
+  }
+
+  // Every open page hears about this, not just the one that asked. A sync outlives the page
+  // that triggered it, so by the time it lands the user is usually somewhere else — and the
+  // page that started it can no longer record that it finished, or show it happening.
+  notifyClients({ type: SYNC_MESSAGE, state: "started", pending: pending.length, retired })
+
+  const result = await precacheUrls(pending, (progress) => {
+    notifyClients({ type: SYNC_MESSAGE, state: "progress", ...progress })
+  })
+
+  // The whole manifest was attempted, so what is left is what would not fetch. Those stay
+  // missing from the cache, so the next sync finds them pending again and tries once more.
+  const remaining = result.pageFailures
+  const complete = remaining === 0
+  // When the run actually ended, decided here rather than by whoever hears about it. A page
+  // that opens later and asks what it missed must be able to say "synced four minutes ago",
+  // not re-date the run to the moment it happened to look.
+  const finished = { ...result, retired, synced: pending.length - remaining, remaining, complete,
+                     finishedAt: Date.now() }
+
+  await notifyClients({ type: SYNC_MESSAGE, state: "finished", ...finished })
+
+  return finished
+}
+
+// Kept so a page can ask what it missed. The head snippet starts a sync while the page is
+// still parsing, so a short run can begin and end before any Stimulus controller has
+// connected to hear it — without this the offline settings page would sit on "Idle" through a sync it
+// caused itself.
+let lastSyncMessage = null
+
+async function notifyClients(message) {
+  lastSyncMessage = message
+
+  const clients = await self.clients.matchAll({ includeUncontrolled: true, type: "window" })
+  clients.forEach((client) => client.postMessage(message))
+}
+
+async function fetchManifest() {
+  let response
+
+  try {
+    response = await fetch(PACK_PATH, {
+      credentials: "same-origin",
+      // The manifest has to describe the server as it is now. Left to the HTTP cache a
+      // browser may serve a heuristically-fresh copy without asking, and a sync would then
+      // faithfully fetch an old list, missing the pages it exists to pick up.
+      cache: "no-store",
+      headers: { Accept: "application/json" }
+    })
+  } catch (error) {
+    // The fetch never completed at all: no connection, rather than a server saying no.
+    const offline = new Error("No connection")
+    offline.offline = true
+    throw offline
+  }
+
+  // Signed out, this follows a redirect to the login page and arrives as a perfectly ok 200
+  // of HTML, which would fail as an opaque JSON parse error.
+  if (response.redirected) throw new Error("Signed out")
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+
+  const pack = await response.json()
+
+  return Array.isArray(pack.urls) ? pack.urls : []
+}
+
+async function retireUnlisted(cache, wanted) {
+  const keys = await cache.keys()
+  let retired = 0
+
+  for (const key of keys) {
+    if (key.headers.get(MANAGED_HEADER) !== "1") continue
+    if (wanted.has(cacheUrl(key.url))) continue
+
+    await cache.delete(key)
+    retired++
+  }
+
+  return retired
+}
+
+// Compare URLs the same way they are stored, or every entry looks unlisted the moment a
+// query string is involved.
+function cacheUrl(href) {
+  const url = new URL(href)
+  if (IGNORE_SEARCH) url.search = ""
+
+  return url.href
+}
+
+// A fixed number of lanes pulling from one queue.
+//
+// One at a time takes as many round trips as there are URLs — minutes for a real manifest.
+// Promise.all over the lot opens a connection per URL and leaves the app's own requests
+// queued behind its own precaching, which is worse than slow.
+async function runPool(items, concurrency, handler) {
+  const queue = items.slice()
+  const lanes = Math.max(1, Math.min(concurrency, queue.length))
+
+  await Promise.all(Array.from({ length: lanes }, async () => {
+    while (queue.length) {
+      try {
+        await handler(queue.shift())
+      } catch {
+        // A lane has to outlive its work. Callers record their own failures, so this is a
+        // backstop — but without it one unexpected throw kills that lane, rejects the
+        // Promise.all, and abandons every URL still queued behind it.
+      }
+    }
+  }))
+}
+
+// One retry, because a sync runs for a while on a phone and a single dropped request should
+// not leave a page missing until the next interval comes round.
+async function fetchWithRetry(cache, href, options) {
+  try {
+    return await fetchAndCache(cache, href, options)
+  } catch {
+    await new Promise((resolve) => setTimeout(resolve, 500))
+
+    return fetchAndCache(cache, href, options)
+  }
+}
+
+async function precacheUrls(inputUrls, onProgress = () => {}) {
+  const cache = await caches.open(CACHE_NAME)
+  // A Set, not an array: lanes finish out of order and an array turns the "already have it"
+  // check into a scan per asset.
+  const cached = new Set()
+  const failed = []
+  const pageFailures = []
+  const assets = new Set()
+
+  let done = 0
+  onProgress({ phase: "pages", done, total: inputUrls.length })
+
+  await runPool(inputUrls, SYNC_CONCURRENCY, async (value) => {
+    try {
+      const href = new URL(value, self.location.origin).href
+      const extra = await fetchWithRetry(cache, href, { managed: true })
+      cached.add(href)
+      extra.forEach((url) => assets.add(url))
+    } catch {
+      failed.push(String(value))
+      pageFailures.push(String(value))
+    }
+    onProgress({ phase: "pages", done: ++done, total: inputUrls.length })
+  })
+
+  // Assets are only known once the pages are parsed, so they get their own count.
+  const pending = [...assets].filter((href) => !cached.has(href))
+  done = 0
+  onProgress({ phase: "assets", done, total: pending.length })
+
+  await runPool(pending, SYNC_CONCURRENCY, async (href) => {
+    try {
+      await fetchWithRetry(cache, href)
+      cached.add(href)
+    } catch {
+      failed.push(href)
+    }
+    onProgress({ phase: "assets", done: ++done, total: pending.length })
+  })
+
+  return { ok: failed.length === 0, cached: cached.size, failed, pageFailures: pageFailures.length }
+}
+

data/lib/coldwire-rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Bundler requires a gem by its own name. Everything lives in `Coldwire`, the way turbo-rails
+# provides `Turbo`.
+require "coldwire"

data/lib/coldwire.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "coldwire/version"
+require "coldwire/configuration"
+require "coldwire/source"
+require "coldwire/client_user_agent"
+require "coldwire/engine"
+
+module Coldwire
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Paths the worker never intercepts: whatever the host excluded, plus the engine endpoints
+    # passed in.
+    #
+    # Only two of Coldwire's own endpoints qualify — the worker script and the manifest —
+    # because caching either would strand the app on a stale copy of the thing meant to
+    # refresh it. The offline settings page is ordinary HTML and is left interceptable, so a host that
+    # wants to reach it offline can list it in `cache_as_you_go` like any other page.
+    def never_intercept(*engine_paths)
+      normalize(config.never_intercept + engine_paths)
+    end
+
+    # Serializes a mixed list of strings and Regexps into something the worker can rebuild.
+    # Ruby's `i` is the only flag with a safe JavaScript equivalent; the others are rejected
+    # when the list is assigned.
+    def cache_rules(patterns)
+      Array(patterns).filter_map do |pattern|
+        if pattern.is_a?(Regexp)
+          { type: "regexp", source: pattern.source,
+            flags: pattern.options.anybits?(Regexp::IGNORECASE) ? "i" : "" }
+        else
+          # Trim a trailing slash so "/sites/" and "/sites" behave alike, but not from "/"
+          # itself — chomping that leaves an empty string and the rule vanishes, which is a
+          # silent way to lose the root path.
+          path = pattern.to_s
+          path = path.chomp("/") unless path == "/"
+          { type: "path", value: path } unless path.empty?
+        end
+      end
+    end
+
+    private
+
+    def normalize(paths)
+      paths.map { |path| path.to_s.chomp("/") }.reject(&:empty?).uniq
+    end
+  end
+end

data/lib/generators/coldwire/install/install_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Coldwire
+  module Generators
+    # `bin/rails coldwire:install` / `bin/rails generate coldwire:install`
+    #
+    # Mounts the engine, writes the initializer, registers the Stimulus controller, and
+    # drops the service worker tag into the layout. Each step is skipped if it is already
+    # done, so running it twice is safe.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install Coldwire into this application"
+
+      LAYOUTS = [
+        "app/views/layouts/application.html.erb"
+      ].freeze
+
+      STIMULUS_INDEXES = [
+        "app/javascript/controllers/index.js",
+        "app/javascript/controllers/index.ts"
+      ].freeze
+
+      STIMULUS_REGISTRATION = <<~JS
+
+        import ColdwireCacheController from "coldwire"
+        application.register("coldwire-cache", ColdwireCacheController)
+      JS
+
+      def add_route
+        if file_contains?("config/routes.rb", "Coldwire::Engine")
+          say "Coldwire is already mounted in config/routes.rb, skipping"
+          return
+        end
+
+        route 'mount Coldwire::Engine => "/offline"'
+      end
+
+      def copy_initializer
+        if file_exists?("config/initializers/coldwire.rb")
+          say "config/initializers/coldwire.rb already exists, skipping"
+          return
+        end
+
+        copy_file "coldwire.rb", "config/initializers/coldwire.rb"
+      end
+
+      def add_layout_tag
+        layout = first_existing(LAYOUTS)
+        unless layout
+          say "Could not find app/views/layouts/application.html.erb. " \
+              "Add <%= coldwire_service_worker_tag %> inside <head>.", :yellow
+          return
+        end
+
+        if file_contains?(layout, "coldwire_service_worker_tag")
+          say "#{layout} already includes coldwire_service_worker_tag, skipping"
+          return
+        end
+
+        unless file_contains?(layout, "</head>")
+          say "Could not find </head> in #{layout}. " \
+              "Add <%= coldwire_service_worker_tag %> inside <head>.", :yellow
+          return
+        end
+
+        insert_into_file layout, "    <%= coldwire_service_worker_tag %>\n", before: "</head>"
+      end
+
+      def register_stimulus
+        index = first_existing(STIMULUS_INDEXES)
+        unless index
+          say "Could not find app/javascript/controllers/index.js. Register the controller with:", :yellow
+          say STIMULUS_REGISTRATION
+          return
+        end
+
+        if file_contains?(index, "coldwire-cache") || file_contains?(index, 'from "coldwire"')
+          say "#{index} already registers Coldwire, skipping"
+          return
+        end
+
+        append_to_file index, STIMULUS_REGISTRATION
+      end
+
+      def next_steps
+        say ""
+        say "Coldwire is mounted at /offline.", :green
+        say "Set config.cache_identity if anyone signs in."
+        say "Turn on config.auto_sync to precache pages."
+      end
+
+      private
+
+      def first_existing(paths)
+        paths.find { |path| file_exists?(path) }
+      end
+
+      def file_exists?(relative)
+        File.exist?(File.join(destination_root, relative))
+      end
+
+      def file_contains?(relative, snippet)
+        file_exists?(relative) && File.read(File.join(destination_root, relative)).include?(snippet)
+      end
+    end
+  end
+end

data/lib/generators/coldwire/install/templates/coldwire.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Offline caching. Only `auto_sync` really needs your attention; the rest has a working
+# default. See docs/configuration.md in the coldwire-rails gem for every option.
+Coldwire.configure do |config|
+  # What to precache and how often. Evaluated against your app's URL helpers.
+  config.auto_sync do |sync|
+    sync.enabled = false          # off by default: background fetching is somebody's data plan
+    sync.precache_urls = -> { [] }
+    # sync.precache_urls = -> { Article.published.map { |a| article_path(a) } }
+    sync.interval = 6.hours
+    sync.max_age = 7.days
+    sync.concurrency = 4
+  end
+
+  # Who the cache belongs to. Evaluated in the view. When it changes, the cache is dropped —
+  # which is what makes signing out, and switching accounts, safe.
+  config.cache_identity = -> { nil }
+  # config.cache_identity = -> { current_user&.id }
+
+  # Where the worker registers at all. Evaluated in the view, so `request` and `current_user`
+  # are both in scope. A page that does not register does not cache or sync.
+  config.register_if = -> { true }
+
+  # Default for the Offline support switch on the offline settings page. People can turn
+  # it off there, which deletes what is stored. A fresh device follows this.
+  config.caching_enabled_by_default = true
+
+  # The importmap module the offline page loads to boot Turbo. nil if you are not on
+  # importmap-rails; load Turbo your own way in the template instead.
+  config.offline_import = "@hotwired/turbo-rails"
+
+  # Which pages are kept as somebody browses. What one needs to render comes with it.
+  # "/*" is everything; `never_cache` always wins. An empty list stores nothing by browsing.
+  config.cache_as_you_go = [ "/*" ]
+  config.never_cache = []
+
+  # Never intercepted, so these fail outright offline. Coldwire's own routes are added for you.
+  config.never_intercept = [ "/up" ]  # probe_path is added for you
+
+  # Origins besides your own the worker may cache, and URLs whose Range requests it caches.
+  config.cache_origins = []
+  config.cache_ranges = []
+
+  # Large files somebody can download for offline use. Nothing downloads on its own.
+  config.cache_archives = []
+
+  config.probe_path = "/up"          # pinged to tell online from offline
+  config.mark_cached_pages = true    # stamp HTML served from cache
+  config.ignore_query_params = true  # treat "/map" and "/map?zoom=9" as one page
+  config.cache_name = "coldwire"     # bump to invalidate every entry at once
+  config.worker_scope = "/"
+end