feat(frontend): offline support via service worker

[ebrahimgamdiwala]

Continuation of #516

netchampfaris's PR was handed over to me to finish. It is reopened from my fork because I have no write access. The commit history from #516 is intact, with develop merges and new commits on top.

What it does

From #516: a service worker serves the app shell offline, and anything already fetched (discussions, spaces, people, profiles) renders from the frappe-ui IndexedDB cache when a request fails.

New here:

• Download for offline (Settings → Preferences → Offline, or More → Offline on mobile). Keep the past week, month or 3 months of discussions from your communities on the device, with their comments, polls, activity and images. The default does not change: only what you open. Guests do not see the setting, because they join no communities.
• No requests while offline. data/offline/requests.ts refuses /api/ calls locally instead of letting them fail one by one. Each resource on screen refetches once on reconnect.
• A refused action says why, at the first click. No button is disabled for being offline. An action that needs the server shows one "You're offline. Reconnect to do this." toast: reacting, Submit, Publish and Save check first (refuseOffline()), and a confirm dialog is refused before it opens (data/offline/dialog.ts). Opening a page never warns, although call() reads over POST and a visit writes track_visit: the toast is only for a write that starts within 1.5 s of a click, Enter or Space, on the same page. What was typed is kept as a draft. Fields that save as you type (task, page, profile) are read-only offline, because typing there would be lost.
• Drafts that survive going offline. A discussion started offline is listed on the Drafts page and saved when the connection returns. See How drafts work.
• Honest empty states. A page that was never fetched says so and offers Retry, instead of rendering as empty. This applies to network failures only. A 403 or 404 keeps the page's own handling.

How downloads work

• Two POST endpoints in gameplan/offline_downloads.py. The index lists what the device should hold and what changed since its last sync. The bundle returns those discussions 20 at a time. Both use frappe's @rate_limit: 1,000 requests per hour per endpoint and IP address (see below).
• Scope is the communities you have joined: every Space in them that you can open. frappe.get_list applies the discussion permission, so private Spaces you are not in stay out.
• Everything goes into the cache entries the app already reads, through data/offline/cache.ts. So a downloaded discussion opens exactly like a visited one, and a Space you have never opened still lists its discussions.
• An up-to-date device spends one index request. Background syncs run at most every 6 hours, in one tab at a time (Web Locks), and skip a hidden tab or Data Saver. A failed sync backs off from 5 minutes up to that interval.
• A device keeps at most the 500 newest discussions of the window.
• Changing the window keeps what is already on the device and fetches only what is missing.
• Discussions the user can no longer read are removed, with images nothing else shows. A discussion that ages out of the window is no longer kept up to date, but stays like any visited page.

How drafts work

Earlier rounds of review kept finding drafts that came back after being deleted, were saved twice, or were lost. Each came from one of four causes: a draft had two names (a local key and a server name), "deleted" was known only to the device that deleted it, replies and edits shared a slot per discussion, and two writers could save the same draft at once. So the design removes those causes instead of patching each case:

• One name per draft. The client names a draft at its first keystroke: 20 lowercase letters and digits. That name is its key on the device, the ?draft= in its link and its GP Draft name. Saving creates the row under that name, and updates it if it already exists, so a retried save never makes a second row. The composer holds only whether its draft is saved, never a second name, so it cannot mistake another device's row for its own. Once a record is saved it stays saved until it is deleted, so a tab that has not heard of the save cannot undo it.
• The server refuses a deleted name. GPDraft.autoname keeps the client's name, and refuses one that is in Deleted Document. So a tab or device still holding a deleted draft cannot bring it back: its save fails, it drops its copy and says "This draft was deleted, so your changes were not saved."
• Deleting a saved draft needs the connection. Offline, it is refused like any other write, and the selection stays. A draft that exists only on the device can be discarded offline.
• One writer at a time. Saves and deletes of one draft run under a Web Lock named after it, across tabs. A save records that the draft is saved before it lets go of the lock, so a delete asked for while its upload is in flight waits for the upload, then removes the row.
• Reply drafts keep the existing find_my_draft behaviour. A reply typed offline while another device saved one for the same discussion is saved as its own draft, and find_my_draft keeps the newest. Drafts stored by an earlier version move to their new keys once, on first use. Records that an earlier version had marked deleted are dropped, not brought back, and one bad record cannot stop the recovery sweep.

Recording

gameplan-offline-demo-github.mp4

Recorded before the review changes below. Writes now show a toast instead of looking disabled, and the download offer in step 2 has since been removed; the rest is the same. Four minutes, with the app on the left and the DevTools Network panel on the right, filtered to /api:

1. Discovering it: a fresh sign-in, normal use, then the connection drops. What was opened still reads, a reply is kept as a draft, and pages that were never opened say so and offer Retry. No API request is attempted while offline.
2. Downloading: the offer on the next load, throttled to Slow 4G. There is one index request, then one per 20 discussions.
3. Reading offline: a discussion downloaded in the background and never opened, with its comments and images.
4. On a phone: the same flows at phone width.

Response to the review

The review said the feature was built in the wrong layer: knowledge of frappe-ui's internals was spread across the app. This round moves it into one folder, fixes the five blockers and the correctness issues, and cuts the guards.

frontend/src/data/offline/ is now the only code that knows how frappe-ui fetches and caches. Its README.md lists what each file relies on, and what in frappe-ui would let it go.

The rest of the app imports from frappe-ui exactly as on develop. A small Vite plugin (offlineResources in vite.config.ts) resolves the app's frappe-ui to data/offline/resources.ts, which re-exports frappe-ui with the offline versions of useList, useDoc, useCall and dialog. Only data/offline/ itself gets the package. When frappe-ui has these options, deleting the plugin is the whole switch; no import changes.

File	Job
resources.ts	frappe-ui, with useList, useDoc and useCall given the offline defaults (staleOnError, reload on reconnect, a cacheLoaded promise) and dialog from dialog.ts
requests.ts	Refuses /api/ requests offline, with one toast for a write the person asked for; refuseOffline() for an action to check first
dialog.ts	frappe-ui's dialog, refused offline before it opens unless worksOffline
cache.ts	cacheFor(user): the cache key formats of frappe-ui#1211 for one account, used by the download engine

Blockers

1. Activities transform ran twice on cached rows: fixed at the source by Cache: run transform once, and keep each user's cache apart frappe-ui#1211. This PR pins that commit.
2. The first page load after a deploy waited for the whole build: the service worker now answers at once and caches in waitUntil.
3. The nightly Cypress run used gameplan.test, where no service worker can register: it now uses localhost, like ui-test.yml. I did not rename the CI site to gameplan.localhost. That touches 54 references in 14 files, mostly server-test workflows.
4. Retry on "Can't load this space" could not succeed: the router now keeps the link in ?redirect=, and Retry opens it. The copy says "community" when a community was requested.
5. frappe-ui's cache format was used in several places: it is now only in cache.ts. downloads.cy.ts writes through it and reads back through the app, so a format change fails CI.

Two accounts never mix

The session cookie can change at any moment: a sign-in in another tab, bench browse --sid, the dev user switcher. Checking it before each write still left a gap at every await. So the design removes the question instead of asking it more often. The rules are in data/offline/README.md:

• Bind, do not look up. A download builds every key through cacheFor(owner), fixed when it starts. Nothing in it reads the cookie again.
• Answers say whose they are. Both endpoints return user, and the client drops an answer for another account before storing it. A Cypress test sends such an answer and checks that nothing is stored.
• Clearing excludes writing. A logout or user switch stops this tab's download, then clears under the lock downloads hold. So no write lands after the clear.

Correctness

• The download engine reads its metadata inside the lock on every run, so a second tab cannot sync from stale metadata or leave orphans. One AbortController replaces four tracking variables.
• A manual sync waits for another tab's sync instead of reporting a failure.
• Changing the window keeps what is on the device. Aged-out discussions are no longer treated as revoked.
• A failure after a cancel or logout writes nothing.
• The index reports its sync time a minute early, so a change committed during the read is caught next time.
• A failing route chunk reloads a page once, not in a loop.
• A browser without IndexedDB counts as cleared, so it no longer blocks the app after a user switch.
• The router waits for cached lists only when there is something cached, not 3 s every time.
• Saved images survive a new worker version. Images saved while browsing are capped at 300.
• Pinning a Space offline is put back when the save fails.
• The settings copy now says "the communities you've joined".

Removed: about 40 component guards and the global pointerup listener; the hand-written per-user rate limiter; the field allowlist; the second permission filter; _allowed_window (window_days is now Literal[7, 30, 90]); the service worker round trip and the deleteDatabase fallback in offline.ts (366 to 175 lines); three of the four paths that filled the asset cache.

Security fixes found in an audit of this PR

• The worker script sends no session cookie. The browser fetches gameplan-sw.js in the background to look for an update, and Frappe sets sid on every response for the session the request began under. An update check that started before a login and ended after it put the previous user's session back, so the next page opened as that user. www/gameplan_sw.py serves the script as public, no-cache, which Frappe answers without cookies. app-shell.cy.ts checks it.
• The People list cannot read other users' account fields. gp_user_profile.get_list passed the client's fields and filters to frappe.qb.get_query, which skips permission checks by default. A field or filter can follow a link, so any member could read user.last_ip, user.mobile_no and similar fields of every profile, or guess them through a filter. The query now runs with ignore_permissions=False: linked fields the user may not read come back empty, and filters on them match nothing. The list returns the same rows for members and guests. A backend test covers both the select and the filter.

Rate limiting: the hand-written per-user limiter is replaced by frappe's @rate_limit decorator. Frappe has no per-user limiter: the rate_limit site setting is one site-wide counter, and the decorator keys on IP address. An office shares one address, so the limit is 1,000 requests per hour per endpoint. A first 3-month download is at most 26 requests, which leaves room for about 40 people behind one address in the same hour, and a client stuck in a loop is still stopped. The counter is keyed on cmd, which the app's /api/method/ calls set.

Kept on purpose: the size readout in the settings, and the rotating check of visited discussions for lost access.

Removed after review: the one-time download offer (offlineIntroduction.ts). Downloads are switched on in Settings only. Reactions made offline are no longer queued: reacting offline is refused like any other write, and reactions otherwise work as on develop.

frappe-ui migration

This PR pins frappe-ui to the merge commit of frappe/frappe-ui#1211 (9be0602) until a release includes it. #1211 runs transform once on cached data and keys the cache per user. So Gameplan's own per-user key suffix is gone.

The pin moves frappe-ui from 1.0.0-beta.64 to 1.0.0-rc.1, so this PR carries the parts of the 1.0 migration that the build and the Cypress suite need. The rest of the migration is tracked in #540, and develop has already done sections 1, 2, 4 and 5 of it.

• Codemods: list-v1, navigation-v1, editor-v1, destinations-v1 and tokens-v2 (51 token renames in 36 files).
• Icons: frappeui() no longer installs unplugin-icons. The seven <Lucide*> tags and ~icons/ imports use CSS icon classes instead, like the rest of the app.
• UploadedFile is now imported from frappe-ui, not frappe-ui/editor.
• useDoc and useCall writes now reject on failure. This is the follow-up that Upgrading to frappe-ui 1.0.0 #540 section 3 names for useDoc (Take the v2 composables to bar: tests and the P1-P15 audit frappe-ui#933). The fire-and-forget calls now catch. TaskDetail uses one setTaskValue helper, and a failed post edit puts the old title back.
• useCall.data is a shallow ref. A role change merged into the users list did not show until reload. activeUsers now reads through the reactive store.

Not in this PR: the useList and useDoctype writes in #540 section 3.2. They already reject on beta.64, so they are existing work, not something the pin causes. The queued() clean-up from section 3.4 is also left for #540.

Also in this PR

• main.js and utils/resetDataMixin.js are now TypeScript. Boot values set on window are typed in globals.d.ts, as site_name already was. gameplan-sw.js stays JavaScript, because Frappe serves it from www/ without a build.

Testing

• Backend, drafts: a draft keeps the name its client gave it, a second create with that name fails without a second row, a deleted name is refused, and a malformed name is rejected.
• Backend, profiles: the People list reads nothing of another user's account through the user link, by select or by filter.
• Backend, downloads: 11 tests for the download endpoints: scope, what takes a discussion out, the device cap, Space moves, revoked access, every kind of change, the bundle contents and bounds, the account each answer names, the per-address rate limit, and POST-only. They compare only the discussions they create, so data already on the site does not break them. The full suite passes.
• Offline e2e (frontend/cypress/e2e/offline, 9 specs, 30 tests): the browser goes offline through the DevTools protocol. These specs can now fail:
  • The network is restored before and after every test.
  • The scroll test seeds a thread long enough to scroll.
  • The profile and fallback checks match the real copy and real content.
  • drafts.cy.ts has one test per draft rule above. Each was checked by breaking that rule in the code and watching its test fail.
  • The refused-write toast, a Sync now refused before its dialog, a saved discussion opened without a toast, and a reaction refused offline have their own tests.
• Full suite: 184 of 187 pass locally. Two failures need the realtime server, which this machine does not run: realtime-activity, and the poll's live-tally step. The third, comment-actions, is the edit-then-delete race that fix(comments): await draft commit before closing edit mode #600 fixes; it passed three times when run again. After the latest changes, the offline and draft specs were run again and pass.
• Open item: "reacts to a poll" failed several times, but only when run after the other poll tests. It passes alone, repeated, and under a service worker reload, and it passed in the final full run. I have not found the cause.
• Browser: checked on desktop and at phone width.

One CI change

A service worker only registers on a secure origin, and over plain http that means localhost. install.sh makes gameplan.test the default site (bench use), and both UI workflows point Cypress at http://localhost:8000 with GAMEPLAN_SITE: gameplan.test. The site check in cypress.config.ts reads that variable and still refuses to run against any other site.

[greptile-apps]

Confidence Score: 4/5

[Medium risk] Adds offline support via service worker and caching.

The PR should not merge until the outstanding workaround-documentation requirement is addressed.

_{Reviews (71) · Last reviewed commit: "refactor(offline): keep the last-seen us..."}

[greptile-apps]

Workaround Reference Missing
cache.ts mirrors frappe-ui’s private cache keys without naming an upstream PR that will replace this workaround. The repository requires that reference for local workarounds; please add it or move the cache API upstream before merging.

Context Used: AGENTS.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: frontend/src/data/offline/cache.ts
Line: 2-4

Comment:
**Workaround Reference Missing**
`cache.ts` mirrors frappe-ui’s private cache keys without naming an upstream PR that will replace this workaround. The repository requires that reference for local workarounds; please add it or move the cache API upstream before merging.

**Context Used:** AGENTS.md ([source](https://github.com/frappe/gameplan/blob/develop/AGENTS.md))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!