From cf54a278e1633d6c22017322367b8041d73f9426 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Thu, 28 May 2026 13:18:23 -0400 Subject: [PATCH] docs: record lazy-browse stays wire-only; align error mapping --- docs/DesignDecisions.md | 13 +++++++++++++ docs/plans/2026-05-28-lazy-browse-design.md | 4 +++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/DesignDecisions.md b/docs/DesignDecisions.md index 85c9aa1..681eed4 100644 --- a/docs/DesignDecisions.md +++ b/docs/DesignDecisions.md @@ -362,6 +362,19 @@ Dashboard access should require API-key-backed dashboard authentication with is enabled by default through `Dashboard:AllowAnonymousLocalhost`; the bypass is limited to loopback requests. +## Lazy Browse Is Wire-Only + +Decision: the gateway continues to pull the full Galaxy hierarchy on each +deploy. `BrowseChildren` and the lazy dashboard render only avoid sending and +DOM-materializing the full tree — they do not push laziness into SQL or cache +loading. + +Rationale: snapshot persistence and the dashboard summary both depend on a +fully-materialized cache. Lazy SQL would increase per-click latency on a +deployment-heavy box, multiply per-session SQL connections, and complicate the +cold-start path. Wire-side laziness solves the actual pain (oversized gRPC +replies and a heavy DOM) without disturbing the materialization model. + ## Later Revisit Items These are explicit post-v1 revisit items, not open blockers: diff --git a/docs/plans/2026-05-28-lazy-browse-design.md b/docs/plans/2026-05-28-lazy-browse-design.md index 3582b9f..f3c3baa 100644 --- a/docs/plans/2026-05-28-lazy-browse-design.md +++ b/docs/plans/2026-05-28-lazy-browse-design.md @@ -102,12 +102,14 @@ message BrowseChildrenReply { | Condition | Status | |---|---| | Unknown `parent_gobject_id` / `parent_tag_name` / `parent_contained_path` | `NotFound` | -| Stale `page_token` (cache deployed forward) | `FailedPrecondition`; current `cache_sequence` in trailers | +| Stale `page_token` (cache deployed forward) | `InvalidArgument`; current `cache_sequence` in trailers | | Filter set differs between pages of the same token | `InvalidArgument` | | First load not complete within 5s | `Unavailable` | | API key missing `metadata:read` scope | `PermissionDenied` | | No API key | `Unauthenticated` | +Stale and filter-changed page tokens both surface as `InvalidArgument` — same contract as `DiscoverHierarchy`, since `BrowseChildren` reuses the same token encoding (`sequence:filter-signature:offset`). + `browse_subtrees` API-key constraints intersect with the request as today. ## Server projection