sneak/quak
1
0
Fork 0
Code Issues 8 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Fresh read variants that await a server round-trip before resolving #75

New Issue
Closed
opened 2026-09-22 22:55:49 +02:00 by clawbot · 1 comment
clawbot commented 2026-09-22 22:55:49 +02:00
Collaborator
Copy Link
Copy Source

Owner amendment to the design (#36, sneak
2026-09-22): the default read methods stay exactly as designed — answer immediately from
the local copy and kick off a background refresh (the caller may get data slightly behind
the server). ADD a parallel "fresh" variant of the read calls: still awaited like any other
call, but it resolves only AFTER a round trip to the server has completed and the local
copy has been updated, so at resolve time the answer is guaranteed current. The quak CLL
read commands use the fresh variants, not the defaults.

Scope

  • Add a fresh read path to the library (built on #42 refresh + #44 read surface, both on
    next). A fresh read forces a refresh (collections cursor + per-changed-album diffs, ML as
    applicable), awaits its completion, persists, then answers from the updated local copy.
    Choose the cleaner surface (implementer's call, keep it plain):
    • either a { fresh?: boolean } option on the existing read calls (albums.list/byName/
      byID, photos.byID/records, timeline.groups, snapshot), default false; or
    • dedicated fresh methods alongside the defaults.
  • Concurrency: a fresh read reuses the metadata pool; multiple concurrent fresh reads must
    not each trigger a redundant full refresh (coalesce to the in-flight refresh where one is
    running).
  • A fresh read whose refresh fails: surface the error to the caller (it awaited currency and
    could not get it) rather than silently answering stale — distinct from the default path,
    where a failed refresh is invisible and reads keep serving the local copy.
  • Do NOT change the default methods' behaviour or the background refresh loop.

Definition of done

  • Fresh variants exist and, at resolve time, reflect a completed server round trip + updated
    local copy (tested against a mock Client: a fresh read observes a server change that a
    default read taken at the same instant would miss).
  • Concurrent fresh reads coalesce to one refresh; a failed refresh rejects the fresh read.
  • Defaults and the background loop unchanged; make check AND make build green.

Follow-on

The CLI (#52) switches its read commands
(collections/files/get/get-thumb) to the fresh variants — handled in #52's rework, which
depends on this unit.

Model: opus-4-8

Owner amendment to the design (https://git.eeqj.de/sneak/quak/issues/36, sneak 2026-09-22): the default read methods stay exactly as designed — answer immediately from the local copy and kick off a background refresh (the caller may get data slightly behind the server). ADD a parallel "fresh" variant of the read calls: still awaited like any other call, but it resolves only AFTER a round trip to the server has completed and the local copy has been updated, so at resolve time the answer is guaranteed current. The `quak` CLL read commands use the fresh variants, not the defaults. ## Scope - Add a fresh read path to the library (built on #42 refresh + #44 read surface, both on next). A fresh read forces a refresh (collections cursor + per-changed-album diffs, ML as applicable), awaits its completion, persists, then answers from the updated local copy. Choose the cleaner surface (implementer's call, keep it plain): - either a `{ fresh?: boolean }` option on the existing read calls (albums.list/byName/ byID, photos.byID/records, timeline.groups, snapshot), default false; or - dedicated fresh methods alongside the defaults. - Concurrency: a fresh read reuses the metadata pool; multiple concurrent fresh reads must not each trigger a redundant full refresh (coalesce to the in-flight refresh where one is running). - A fresh read whose refresh fails: surface the error to the caller (it awaited currency and could not get it) rather than silently answering stale — distinct from the default path, where a failed refresh is invisible and reads keep serving the local copy. - Do NOT change the default methods' behaviour or the background refresh loop. ## Definition of done - Fresh variants exist and, at resolve time, reflect a completed server round trip + updated local copy (tested against a mock Client: a fresh read observes a server change that a default read taken at the same instant would miss). - Concurrent fresh reads coalesce to one refresh; a failed refresh rejects the fresh read. - Defaults and the background loop unchanged; make check AND make build green. ## Follow-on The CLI (https://git.eeqj.de/sneak/quak/issues/52) switches its read commands (collections/files/get/get-thumb) to the fresh variants — handled in #52's rework, which depends on this unit. Model: opus-4-8
clawbot commented 2026-09-22 23:07:06 +02:00
Author
Collaborator
Copy Link
Copy Source

Implemented in #76 (branch issue-75-fresh-reads, base next).

Added Library.fresh(): it forces a refresh, awaits it, persists, then hands back the same albums/photos/timeline read namespaces, now reflecting a completed server round-trip. The default reads and the background refresh loop are unchanged.

Concurrent fresh reads coalesce onto one in-flight refresh, so they make a single server round-trip. A refresh that fails rejects the fresh read, whereas a default read stays silent and keeps serving the last good copy.

The CLI switching its read commands to fresh reads remains #52.

Model: opus-4-8

Implemented in https://git.eeqj.de/sneak/quak/pulls/76 (branch `issue-75-fresh-reads`, base `next`). Added `Library.fresh()`: it forces a refresh, awaits it, persists, then hands back the same `albums`/`photos`/`timeline` read namespaces, now reflecting a completed server round-trip. The default reads and the background refresh loop are unchanged. Concurrent fresh reads coalesce onto one in-flight refresh, so they make a single server round-trip. A refresh that fails rejects the fresh read, whereas a default read stays silent and keeps serving the last good copy. The CLI switching its read commands to fresh reads remains https://git.eeqj.de/sneak/quak/issues/52. Model: opus-4-8
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
merge-ready
Review passed; ready to merge
 needs-checks
CI / make check is not green on this PR
 needs-rebase
PR conflicts with main and must be rebased
 needs-review
PR is awaiting adversarial review
 needs-rework
Review failed; PR needs changes
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/quak#75