coldwire-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f01aeddab9f97e903edaa61b6e17a674359cf508633835ed5df8d3fd77145fd8
+  data.tar.gz: e4b438c9a706473e652121ea5fd474057d5d93d42213a85846c28449e14e2f5e
+SHA512:
+  metadata.gz: bd80ebb768d19c935f3426c7b48649c562ae8518f56c3539866ab579cc5eeee2caa04097c4c96144c8591c64a8c34857f966cef4dea4c8538b94a33c8a0d8a0f
+  data.tar.gz: 67b95dae87ed9c8bce9301911c85e6fdd26f7520836fcdcd73d47b9470424ae568c0ad1c1e4f4a9a8855e99c412d1f1321c4d71cab5ed7d0755a243e1242a581

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## [Unreleased]
+
+First release. The API may still change before 1.0.
+
+- **`bin/rails coldwire:install`.** Mounts the engine at `/offline`, writes an initializer
+  with every option and its default, registers the Stimulus controller, and tags the
+  layout. Safe to run twice.
+- **Offline support switch** in the status header on the offline settings page. Off deletes
+  what is stored, unregisters the worker, and hides the rest of the page.
+  `config.caching_enabled_by_default` is the starting position of the switch (on). A device
+  remembers the choice.
+- **Service worker and offline fallback.** A mountable engine serves the worker; when there is
+  no cached copy and no network, a full page or a `<turbo-frame>` — both overridable — stands
+  in. Built to satisfy Hotwire Native, which is stricter than a browser.
+- **Precaching.** `auto_sync.precache_urls` is a list of URLs computed in Ruby, fetched along
+  with the subresources those pages reference.
+- **The cache's requests carry the app's user agent**, by way of a cookie. A worker's own
+  fetches cannot: Hotwire Native sets the agent on the web view, `ServiceWorkerWebSettings` has
+  no equivalent, and `fetch` may not set one — so on Android everything precached came back
+  rendered for a browser. Each page writes its agent into `coldwire-user-agent`, which the
+  browser attaches to every same-origin request, and a middleware puts it back.
+- **`cache_as_you_go`** names the pages kept as somebody browses — default `["/*"]`, every
+  path. An empty list stores nothing by browsing. **A stored page brings what it asks for**
+  — its stylesheets, scripts and images are stored with it whatever the lists say, because
+  a page held without them is the offline equivalent of not holding it. **`never_cache`**
+  is the one veto over storing anything, by any route in; it is not `never_intercept`,
+  which stops the worker touching a request at all and so fails outright offline.
+- **Automatic syncing** on an interval, refetching anything older than `max_age`, resuming
+  across page loads when a run is cut short.
+- **Offline settings page** at the mount point: connection status, force offline, an Auto Sync switch
+  with a countdown and live progress. The list of every cached URL is under **Inspect cache**,
+  closed until you open it and remembered after that.
+- **Nothing served from the cache is `data-turbo-track="reload"`.** Turbo will not render a
+  page whose tracked elements differ from the current page's; it reloads instead, which
+  offline buys nothing and which Hotwire Native can hang on. Asset digests change with every
+  deploy, so any page cached before the current one was built disagrees with it — no
+  configuration could have reconciled that. This replaced the `offline_head` setting, whose
+  whole job was keeping the fallback's tracked elements in step with the layout by hand.
+- **One cache entry per URL.** `cache.put()` replaces an entry only where the two agree about
+  `Vary`, and Rails answers HTML with `Vary: Accept` — so a page fetched by precaching
+  (`*/*`) and the same page visited by Turbo (`text/html`) are kept as two records, and the
+  list grows a copy per distinct Accept. Writing a page now retires the URL first. Range and
+  chunk entries, which share a path with their own query, are left alone.
+- **Allow and block lists** written as route patterns (`"/sites/:id/card"`) or Regexps.
+- **Cache identity.** The cache is dropped when the signed-in user changes.
+- **Cross-origin caching** for origins you nominate, and **`Range` caching** for tiles and
+  media that would otherwise be uncacheable.
+- **Downloadable archives.** Large files somebody can choose to keep, fetched in chunks so an
+  interrupted download resumes.
+- **`window.Coldwire`** — `isOffline()`, `isForcedOffline()`, `cachedAt()`, `onChange()` — plus
+  `data-coldwire-offline` on any HTML served from cache.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noreaster Group, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+# Coldwire
+
+**When your Hotwire wires go cold.**
+
+Offline caching for Rails. Add a gem, mount it, drop a tag in your layout — pages start
+working without a network. A service worker precaches what you nominate, keeps pages as
+people browse, and falls back to a view [Turbo](https://turbo.hotwired.dev) will actually
+render.
+
+Works the same in a plain Hotwire app, an installed PWA, or Hotwire Native.
+
+> **Status: early.** Extracted from a production app but young as a library. The API may
+> change before 1.0.
+
+> [!TIP]
+> **Need help going offline?** Coldwire is built by [Noreaster Group](https://noreastergroup.com).
+> If you want a hand adding offline to your Hotwire or Hotwire Native app,
+> [talk to us](https://noreastergroup.com).
+
+## What you get
+
+- **Minutes to wire.** `bin/rails coldwire:install`. The rest has working defaults.
+- **Precaching in Ruby.** Nominate URLs with your own route helpers; assets come with them.
+- **Cache as you go.** Pages someone visits are kept, with the styles, scripts, and images
+  they need to render.
+- **An offline fallback** Turbo — and Hotwire Native — will actually show.
+- **Offline settings** at `/offline`: turn offline support off, force offline, sync, downloads, what's cached.
+- **Safe when people sign in.** The cache drops when the user changes.
+
+<p align="center">
+  <img src="docs/images/offline-settings.png" alt="Offline settings: status, force offline, auto sync, and downloads" width="280">
+  <img src="docs/images/offline-settings-cached.png" alt="Offline settings: every cached entry, with search, sort, and delete" width="280">
+</p>
+
+<p align="center"><em>The offline settings page that ships with it. The URL list is under Inspect cache.</em></p>
+
+<p align="center">
+  <img src="docs/images/offline-fallback.png" alt="The offline fallback: You're offline. This page isn't available offline. Reconnect and try again." width="280">
+</p>
+
+<p align="center"><em>When a page isn't cached and there's no network, this is what people see — not a blank screen or a native error. Override it to match your app.</em></p>
+
+## Quick start
+
+```ruby
+# Gemfile
+gem "coldwire-rails"
+```
+
+```bash
+bin/rails coldwire:install
+```
+
+That mounts the engine at `/offline`, writes `config/initializers/coldwire.rb`, registers
+the Stimulus controller, and adds the tag to your layout. Visit `/offline` to see what's
+cached.
+
+For signed-in apps, set `cache_identity`. To have pages ready before anyone visits them,
+turn on `auto_sync`. Both are in the [configuration reference](docs/configuration.md).
+
+## Docs
+
+- [Setup](docs/setup.md) — install, requirements, Hotwire Native on iOS
+- [Configuration](docs/configuration.md) — every option and what it does
+- [How it works](docs/how-it-works.md) — why a naive cache fails in Hotwire
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/app/assets/javascripts/coldwire/archives.js

@@ -0,0 +1,52 @@
+// The download rows: what each one says, and what it looks like mid-download.
+
+import { formatBytes, formatCachedAt } from "coldwire/format"
+
+export function renderArchiveStatus(row, status) {
+  const label = row.querySelector("[data-archive-status]")
+  const download = row.querySelector("[data-archive-download-label]")
+  const remove = row.querySelector("[data-archive-remove]")
+
+  if (!status || !status.ok) {
+    label.textContent = "Not downloaded"
+    remove.hidden = true
+    download.textContent = "Download"
+    return
+  }
+
+  remove.hidden = status.chunks === 0
+  download.textContent = status.complete ? "Download again" : status.chunks ? "Resume" : "Download"
+
+  if (status.complete) {
+    label.textContent = status.cachedAt
+      ? `${formatBytes(status.bytes)} · downloaded ${formatCachedAt(status.cachedAt)}`
+      : `${formatBytes(status.bytes)} · on this device`
+  } else if (status.chunks) {
+    // Partly downloaded is worth saying plainly: it is not broken, it stopped, and asking
+    // again carries on from there.
+    const share = status.expected ? Math.round((status.chunks / status.expected) * 100) : null
+    const stopped = status.cachedAt ? `, stopped ${formatCachedAt(status.cachedAt)}` : ""
+    label.textContent = share
+      ? `${formatBytes(status.bytes)} of ${formatBytes(status.total)} · ${share}%${stopped}`
+      : `${formatBytes(status.bytes)} downloaded · not finished${stopped}`
+  } else {
+    label.textContent = "Not downloaded"
+  }
+}
+export function renderArchiveProgress(row, done, total) {
+  const progress = row.querySelector("[data-archive-progress]")
+  const bar = row.querySelector("[data-archive-bar]")
+  const label = row.querySelector("[data-archive-progress-label]")
+
+  progress.hidden = false
+  const percent = total ? Math.round((done / total) * 100) : 0
+  bar.style.width = `${percent}%`
+  bar.classList.remove("coldwire-pulse")
+  progress.setAttribute("aria-valuenow", String(percent))
+  label.textContent = `${done} of ${total} pieces`
+}
+export function toggleArchiveBusy(row, busy) {
+  row.querySelector("[data-archive-spinner]").hidden = !busy
+  row.querySelectorAll("button").forEach((button) => { button.disabled = busy })
+  if (!busy) row.querySelector("[data-archive-progress]").hidden = true
+}