From 4c9472831888d4c6a3e126c6027b69d8d282bcb4 Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Tue, 3 Nov 2026 23:43:15 -0800 Subject: [PATCH 1/8] Filter hardware offers and add bounded marketplace pages Signed-off-by: Nirmal Khedkar --- CONFORMANCE.md | 15 ++ docs/marketplace-browse.md | 90 ++++++++ internal/consumerapi/market.go | 45 ++-- internal/consumerapi/market_browse_test.go | 227 +++++++++++++++++++++ internal/consumerapi/market_query.go | 86 ++++++++ internal/market/browse.go | 59 ++++++ 6 files changed, 510 insertions(+), 12 deletions(-) create mode 100644 docs/marketplace-browse.md create mode 100644 internal/consumerapi/market_browse_test.go create mode 100644 internal/consumerapi/market_query.go create mode 100644 internal/market/browse.go diff --git a/CONFORMANCE.md b/CONFORMANCE.md index 6f2272a..8767919 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -77,3 +77,18 @@ signed-field tampering. The existing summary response remains unchanged. This proves signed authorship, not truth or independent witnessing; the Technology Tree remains its documented unwitnessed single-writer stand-in. See `docs/signed-claim-export.md` for the format and verification boundaries. + +Public hardware-offer browsing supports exact maker-key and signed accepted-rail +filters, plus opt-in bounded append-order pages. Repeated rails match any selected +rail; category and maker filters combine with that selection. The maker remains +the same platform member identity. These are structural discovery controls: +credit acceptance does not switch the economy out of escrow or authorize a +credit spend. No narrative, scoring, promotion or settlement authority is added. +Bindings: `internal/market/browse.go`, `internal/consumerapi/market_query.go`, and +`TestMarketplaceBrowseFilters`, `TestMarketplaceBrowsePagesAcrossSalesAndAppends`, +`TestMarketplaceBrowseRejectsMalformedFilters`, +`TestMarketplaceBrowseLegacyAndEmptyCategory`, `TestMarketplaceBrowsePageBounds`. +Pages avoid full-log/category/sales-history copies, but sparse filters can scan +the remaining catalogue. Existing unpaged reads remain unbounded; in-memory, +single-writer and witnessing limitations remain unchanged. See +`docs/marketplace-browse.md` for query syntax and compatibility limits. diff --git a/docs/marketplace-browse.md b/docs/marketplace-browse.md new file mode 100644 index 0000000..b4512a5 --- /dev/null +++ b/docs/marketplace-browse.md @@ -0,0 +1,90 @@ +# Browsing hardware offers + +`GET /api/v1/market/listings` is public and returns structural listing summaries +in catalogue append order. Browsing neither records an exchange nor authorizes +settlement. Maker keys are the existing platform member keys; the API adds no +producer/consumer identity split, paid placement, reputation score or ranking. + +## Filters + +| Parameter | Meaning | +| --- | --- | +| `category` | Existing hardware category: `computer`, `mobile_phone`, `tablet`, `smart_tv`, `tv_streaming_stick`, or `nas_storage`. Omitted/empty retains the existing behavior: no matches. | +| `maker` | Optional exact 32-byte Ed25519 public key, encoded as 64 hex characters. Uppercase and lowercase hex denote the same key. An unknown well-formed key returns an empty list. | +| `rail` | Optional `fiat` or `member_credit`. Repeat the parameter to match **any** selected rail. Omit it to impose no rail restriction. | + +Category, maker and the rail selection combine with AND. For example: + +```text +/api/v1/market/listings?category=computer&rail=fiat&rail=member_credit&limit=10 +``` + +This returns computer offers accepting fiat, member credit, or both. Selecting +only `rail=member_credit` matches credit-only and dual-rail offers. These flags +describe the maker's signed acceptance, not the platform's current settlement +capabilities. Credit remains blocked while the economy is in escrow mode. Fiat +and credit remain separate, nonconvertible rails; no purchase or redemption of +member credit is added. + +## Opt-in pagination + +Supplying `limit` or `cursor` enables paged reads. `limit` must be 1–100; it +defaults to 50 when only `cursor` is supplied. Start at `cursor=0` or omit the +cursor on the first limited request. + +```json +{"listings": [], "next_cursor": "125"} +``` + +`listings` contains the same summary fields as before. When more matching +offers exist, `next_cursor` is a decimal string pointing after the last returned +listing in the catalogue log. Follow it with the same category, maker, rail +selection and page limit. Treat it as a continuation token, not a result count: +sales and nonmatching listings also occupy log positions. Exhausted pages omit +`next_cursor`; `listings` is always an array, including for empty results. + +Append positions stay stable as offers and sales are appended. Pagination is +live, not a frozen snapshot: later requests may include new offers and updated +sales counts. A cursor equal to the current log length returns an empty page; +a cursor beyond the current log length is invalid. Cursors are local to this +in-memory catalogue instance, not portable durable bookmarks. After a restart, +start a fresh traversal. Changing filters also starts a fresh traversal. + +Each request snapshots its summaries under the existing server lock and writes +the response after unlocking. Bounded reads allocate for the page, without +copying the complete log, full category results or sales histories. Sparse +filters may still scan all remaining log entries; this is not an indexed search +or a bound on scan CPU time. Legacy requests with neither pagination parameter +remain unbounded and preserve the `{"listings": [...]}` response shape. + +## Invalid input and compatibility + +Malformed URL query encoding, invalid nonempty categories, malformed/empty maker +keys, unknown/empty rails, and repeated singleton parameters (`category`, +`maker`, `limit`, `cursor`) return HTTP 400. Rails may repeat; duplicates do not +duplicate offers. Comma-separated rail values are not supported. Page numbers +must contain only ASCII decimal digits and fit a nonnegative Go `int`; signs, +whitespace, fractions, suffixes and overflow fail. Empty bounds fail rather than +silently becoming defaults. Unknown unrelated query parameters remain ignored. + +Valid existing category-only requests retain their fields, append ordering and +empty-category behavior. Invalid categories now receive 400 rather than looking +like a successful empty result. No signed listing, domain tag, protocol message, +storage format, public-read authorization or governance policy changes. + +## Verification + +```sh +go test ./internal/consumerapi -run '^TestMarketplaceBrowse' -count=1 +go test -race ./... +go vet ./... +go build ./... +go test ./internal/consumerapi -run '^$' -bench '^BenchmarkMarketplaceBrowse$' -benchmem +``` + +HTTP tests use real signed registration, product-spec claims, listing creation +and the catalogue. They check filter conjunction and rail OR semantics, dual-rail +offers, unknown keys, exact summary fields, sale-interleaved append cursors, +continuation after appends, malformed requests, page limits and legacy behavior. +The benchmark uses a ten-offer page against 100 and 1,000 stored offers. It +measures local request allocations and time, not a production capacity guarantee. diff --git a/internal/consumerapi/market.go b/internal/consumerapi/market.go index daf70aa..7c5765e 100644 --- a/internal/consumerapi/market.go +++ b/internal/consumerapi/market.go @@ -5,6 +5,7 @@ import ( "encoding/json" "errors" "net/http" + "strconv" "time" "github.com/NTARI-RAND/Cloudy/internal/market" @@ -138,26 +139,46 @@ func (s *Server) listingViewLocked(id market.ListingID, l market.Listing) listin AcceptFiat: l.Rails.Fiat, AcceptCredit: l.Rails.MemberCredit, ListedAt: l.ListedAt.UTC().Format(time.RFC3339Nano), - SalesCount: len(s.catalog.SalesOf(id)), + SalesCount: s.catalog.SalesCount(id), } } -// handleBrowseListings lists listings in a category (query ?category=), in -// append order — never ranked or promoted. Public. +// handleBrowseListings returns public, append-ordered structural summaries. +// limit or cursor opts into bounded pages; existing unpaged reads stay compatible. func (s *Server) handleBrowseListings(w http.ResponseWriter, r *http.Request) { - cat := market.Category(r.URL.Query().Get("category")) + query, paged, err := parseMarketQuery(r.URL.RawQuery) + if err != nil { + writeErr(w, http.StatusBadRequest, errMarketQuery.Error()) + return + } + out, next, err := s.browseListings(query) + if err != nil { + writeErr(w, http.StatusBadRequest, err.Error()) + return + } + response := struct { + Listings []listingView `json:"listings"` + NextCursor string `json:"next_cursor,omitempty"` + }{Listings: out} + if paged && next != 0 { + response.NextCursor = strconv.Itoa(next) + } + writeJSON(w, http.StatusOK, response) +} + +func (s *Server) browseListings(query market.ListingQuery) ([]listingView, int, error) { s.mu.Lock() defer s.mu.Unlock() - ids := s.catalog.ByCategory(cat) - out := make([]listingView, 0, len(ids)) - for _, id := range ids { - l, ok := s.catalog.Listing(id) - if !ok { - continue - } + page, err := s.catalog.Browse(query) + if err != nil { + return nil, 0, err + } + out := make([]listingView, 0, len(page.IDs)) + for _, id := range page.IDs { + l, _ := s.catalog.Listing(id) out = append(out, s.listingViewLocked(id, l)) } - writeJSON(w, http.StatusOK, map[string][]listingView{"listings": out}) + return out, page.Next, nil } // handleGetListing serves one listing. Public. diff --git a/internal/consumerapi/market_browse_test.go b/internal/consumerapi/market_browse_test.go new file mode 100644 index 0000000..5c848b7 --- /dev/null +++ b/internal/consumerapi/market_browse_test.go @@ -0,0 +1,227 @@ +package consumerapi + +import ( + "crypto/ed25519" + "encoding/hex" + "fmt" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "testing" + "time" + + "github.com/NTARI-RAND/Cloudy/internal/market" + "github.com/NTARI-RAND/Cloudy/internal/techtree" +) + +// The fixtures enter through signed HTTP writes, so filtering cannot rely on +// caller-supplied maker labels or bypass the real catalogue's invariants. +func browseListing(t *testing.T, s *Server, seed byte, category market.Category, rails market.AcceptedRails) string { + t.Helper() + pub, priv := key(seed) + h := s.Handler() + registerMember(t, h, pub, priv) + specID := anchorClaim(t, h, pub, priv, techtree.KindProductSpec, "private specification", "test", "test") + l, err := market.NewListing(platform, pub, category, market.SpecRef(decodeClaimID(t, specID)), rails, time.Now().UTC()) + if err != nil { + t.Fatal(err) + } + if err := l.Sign(priv); err != nil { + t.Fatal(err) + } + rec, out := do(t, h, http.MethodPost, "/api/v1/market/listings", listingDTO{ + Platform: platform, Maker: hx(pub), Category: string(category), Spec: specID, + AcceptFiat: rails.Fiat, AcceptCredit: rails.MemberCredit, Nonce: hx(l.Nonce[:]), + ListedAtNs: l.ListedAt.UnixNano(), Signature: hx(l.Signature), + }) + if rec.Code != http.StatusCreated { + t.Fatalf("create listing: %d %s", rec.Code, rec.Body.String()) + } + return out["listing_id"].(string) +} + +func browseServer(t *testing.T) *Server { + t.Helper() + s, err := NewServer(platform) + if err != nil { + t.Fatal(err) + } + return s +} + +func browseIDs(t *testing.T, s *Server, query string) ([]string, map[string]any) { + t.Helper() + rec, out := do(t, s.Handler(), http.MethodGet, "/api/v1/market/listings"+query, nil) + if rec.Code != http.StatusOK { + t.Fatalf("browse %s: %d %s", query, rec.Code, rec.Body.String()) + } + rows, ok := out["listings"].([]any) + if !ok { + t.Fatalf("listings is not an array: %s", rec.Body.String()) + } + ids := make([]string, 0, len(rows)) + for _, row := range rows { + ids = append(ids, row.(map[string]any)["listing_id"].(string)) + } + return ids, out +} + +// Catches ignoring any filter, applying rails as AND, or sorting by maker/time. +func TestMarketplaceBrowseFilters(t *testing.T) { + s := browseServer(t) + a := browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + b := browseListing(t, s, 2, market.CategoryComputer, market.AcceptedRails{MemberCredit: true}) + c := browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true, MemberCredit: true}) + _ = browseListing(t, s, 1, market.CategorySmartTV, market.AcceptedRails{Fiat: true}) + pub, _ := key(1) + makerQuery := "?category=computer&maker=" + for _, tc := range []struct { + query string + want []string + }{ + {"?category=computer&rail=fiat", []string{a, c}}, + {"?category=computer&rail=member_credit", []string{b, c}}, + {"?category=computer&rail=fiat&rail=member_credit", []string{a, b, c}}, + {makerQuery + hx(pub) + "&rail=member_credit", []string{c}}, + {makerQuery + strings.ToUpper(hx(pub)), []string{a, c}}, + {makerQuery + strings.Repeat("00", ed25519.PublicKeySize), []string{}}, + } { + t.Run(tc.query, func(t *testing.T) { + got, _ := browseIDs(t, s, tc.query) + if !reflect.DeepEqual(got, tc.want) { + t.Fatalf("got %v, want %v", got, tc.want) + } + }) + } +} + +// Catches cursors based on filtered offsets, counting sales as offers, missing +// continuation, duplicate pages, and leaking narrative in the summary. +func TestMarketplaceBrowsePagesAcrossSalesAndAppends(t *testing.T) { + s := browseServer(t) + a := browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + idBytes, _ := hex.DecodeString(a) + var id market.ListingID + copy(id[:], idBytes) + if err := s.catalog.RecordSale(id, market.ExchangeRef{1}, time.Now()); err != nil { + t.Fatal(err) + } + _ = browseListing(t, s, 1, market.CategorySmartTV, market.AcceptedRails{Fiat: true}) + b := browseListing(t, s, 2, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + first, page := browseIDs(t, s, "?category=computer&limit=1") + if !reflect.DeepEqual(first, []string{a}) || page["next_cursor"] != "1" { + t.Fatalf("first page: %v", page) + } + row := page["listings"].([]any)[0].(map[string]any) + if row["sales_count"] != float64(1) || len(row) != 9 { + t.Fatalf("summary fields changed: %v", row) + } + c := browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{MemberCredit: true}) + second, page := browseIDs(t, s, "?category=computer&limit=1&cursor=1") + if !reflect.DeepEqual(second, []string{b}) || page["next_cursor"] != "4" { + t.Fatalf("second page: %v", page) + } + last, page := browseIDs(t, s, "?category=computer&limit=1&cursor=4") + if !reflect.DeepEqual(last, []string{c}) || page["next_cursor"] != nil { + t.Fatalf("last page: %v", page) + } +} + +func TestMarketplaceBrowseLegacyAndEmptyCategory(t *testing.T) { + s := browseServer(t) + a := browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + ids, out := browseIDs(t, s, "?category=computer") + if !reflect.DeepEqual(ids, []string{a}) || len(out) != 1 { + t.Fatalf("legacy response changed: %v", out) + } + for _, query := range []string{"", "?category=", "?category=&limit=1", "?cursor=0"} { + ids, _ := browseIDs(t, s, query) + if len(ids) != 0 { + t.Fatalf("empty category %q returned %v", query, ids) + } + } +} + +// Catches accepting malformed/ambiguous queries or clamping invalid bounds. +func TestMarketplaceBrowseRejectsMalformedFilters(t *testing.T) { + s := browseServer(t) + const makerParameter = "maker=" + for _, query := range []string{ + "category=tomato", "category=computer&category=smart_tv", makerParameter, "maker=zz", makerParameter + strings.Repeat("ab", 31), + makerParameter + strings.Repeat("ab", 33), "maker=aa&maker=bb", "rail=", "rail=credit", "rail=fiat,member_credit", + "limit=", "limit=0", "limit=-1", "limit=101", "limit=1junk", "limit=%2B1", "limit=1&limit=2", + "cursor=", "cursor=-1", "cursor=1.0", "cursor=1junk", "cursor=%201", "cursor=999999999999999999999999", "cursor=1", "cursor=0&cursor=0", + "category=computer%ZZ", + } { + t.Run(query, func(t *testing.T) { + rec, _ := do(t, s.Handler(), http.MethodGet, "/api/v1/market/listings?"+query, nil) + if rec.Code != http.StatusBadRequest { + t.Fatalf("got %d, want 400: %s", rec.Code, rec.Body.String()) + } + }) + } +} + +func TestMarketplaceBrowsePageBounds(t *testing.T) { + s := browseServer(t) + for i := 0; i < 103; i++ { + browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + } + for _, tc := range []struct { + query string + want int + }{ + {"?category=computer", 103}, + {"?category=computer&cursor=0", 50}, + {"?category=computer&limit=100", 100}, + {"?category=computer&limit=100&cursor=100", 3}, + {"?category=computer&limit=1&cursor=103", 0}, + } { + t.Run(tc.query, func(t *testing.T) { + ids, _ := browseIDs(t, s, tc.query) + if len(ids) != tc.want { + t.Fatalf("got %d offers, want %d", len(ids), tc.want) + } + }) + } +} + +func BenchmarkMarketplaceBrowse(b *testing.B) { + for _, count := range []int{100, 1000} { + b.Run(fmt.Sprint(count), func(b *testing.B) { + h := benchmarkMarketHandler(b, count) + b.ReportAllocs() + b.ResetTimer() + for i := 0; i < b.N; i++ { + rec := httptest.NewRecorder() + h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/market/listings?category=computer&limit=10", nil)) + if rec.Code != http.StatusOK { + b.Fatal(rec.Code) + } + } + }) + } +} + +func benchmarkMarketHandler(b *testing.B, count int) http.Handler { + b.Helper() + s, err := NewServer(platform) + if err != nil { + b.Fatal(err) + } + pub, priv := key(1) + for i := 0; i < count; i++ { + l, err := market.NewListing(platform, pub, market.CategoryComputer, market.SpecRef{1}, market.AcceptedRails{Fiat: true}, time.Now()) + if err != nil { + b.Fatal(err) + } + if err := l.Sign(priv); err != nil { + b.Fatal(err) + } + if _, err := s.catalog.AddListing(l); err != nil { + b.Fatal(err) + } + } + return s.Handler() +} diff --git a/internal/consumerapi/market_query.go b/internal/consumerapi/market_query.go new file mode 100644 index 0000000..134824f --- /dev/null +++ b/internal/consumerapi/market_query.go @@ -0,0 +1,86 @@ +package consumerapi + +import ( + "errors" + "net/url" + "slices" + "strconv" + + "github.com/NTARI-RAND/Cloudy/internal/market" +) + +var errMarketQuery = errors.New("invalid marketplace query") + +func parseMarketQuery(raw string) (market.ListingQuery, bool, error) { + values, err := url.ParseQuery(raw) + if err != nil { + return market.ListingQuery{}, false, errMarketQuery + } + for _, name := range []string{"category", "maker", "limit", "cursor"} { + if len(values[name]) > 1 { + return market.ListingQuery{}, false, errMarketQuery + } + } + q, err := marketFilters(values) + if err != nil { + return q, false, err + } + paged := values.Has("limit") || values.Has("cursor") + if paged { + q.Limit, q.Start, err = marketPageBounds(values) + } + return q, paged, err +} + +func marketFilters(values url.Values) (market.ListingQuery, error) { + q := market.ListingQuery{Category: market.Category(values.Get("category"))} + if q.Category != "" && !slices.Contains(market.Categories(), q.Category) { + return q, errMarketQuery + } + if values.Has("maker") { + var ok bool + q.Maker, ok = decodeKey(values.Get("maker")) + if !ok { + return q, errMarketQuery + } + } + for _, rail := range values["rail"] { + switch rail { + case "fiat": + q.Rails.Fiat = true + case "member_credit": + q.Rails.MemberCredit = true + default: + return q, errMarketQuery + } + } + return q, nil +} + +func marketPageBounds(values url.Values) (int, int, error) { + limit, start := 50, 0 + var err error + if values.Has("limit") { + limit, err = marketPageNumber(values.Get("limit")) + if err != nil || limit < 1 || limit > 100 { + return 0, 0, errMarketQuery + } + } + if values.Has("cursor") { + start, err = marketPageNumber(values.Get("cursor")) + } + return limit, start, err +} + +func marketPageNumber(value string) (int, error) { + if value == "" { + return 0, errMarketQuery + } + for _, digit := range value { + if digit < '0' || digit > '9' { + return 0, errMarketQuery + } + } + n, err := strconv.Atoi(value) + return n, err +} diff --git a/internal/market/browse.go b/internal/market/browse.go new file mode 100644 index 0000000..e5a514f --- /dev/null +++ b/internal/market/browse.go @@ -0,0 +1,59 @@ +package market + +import ( + "crypto/ed25519" + "errors" +) + +// ListingQuery selects listings, never sales, in catalogue append order. +// Rails matches ANY selected rail; an empty set imposes no rail filter. +// Start is a catalogue log position. Limit zero preserves unpaged traversal. +// Like the other catalogue methods, Browse requires external synchronization. +type ListingQuery struct { + Category Category + Maker ed25519.PublicKey + Rails AcceptedRails + Start int + Limit int +} + +// ListingPage contains at most Limit ids. Next is zero at exhaustion, otherwise +// the append position following the last returned listing. Pages are live, +// not a frozen export; appends do not move existing catalogue positions. +type ListingPage struct { + IDs []ListingID + Next int +} + +// Browse scans without copying the log or building the complete matching set. +// Sparse filters can still scan the remaining history; storage for a bounded +// page grows with its result count, not with unrelated listings or sales. +func (c *Catalog) Browse(q ListingQuery) (ListingPage, error) { + if q.Start < 0 || q.Start > len(c.log) || q.Limit < 0 { + return ListingPage{}, errors.New("market: invalid listing page bounds") + } + page := ListingPage{} + for pos := q.Start; pos < len(c.log); pos++ { + l := c.log[pos].Listing + if l == nil || !q.matches(*l) { + continue + } + if q.Limit > 0 && len(page.IDs) == q.Limit { + return page, nil + } + page.IDs = append(page.IDs, l.ID()) + page.Next = pos + 1 + } + page.Next = 0 + return page, nil +} + +func (q ListingQuery) matches(l Listing) bool { + if l.Category != q.Category || (len(q.Maker) > 0 && !l.Maker.Equal(q.Maker)) { + return false + } + return !q.Rails.Valid() || (q.Rails.Fiat && l.Rails.Fiat) || (q.Rails.MemberCredit && l.Rails.MemberCredit) +} + +// SalesCount returns provenance depth without copying the exchange history. +func (c *Catalog) SalesCount(id ListingID) int { return len(c.sales[id]) } From f8628c91ef9012ecdd3e03908749018f2c41eb65 Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:26:43 -0800 Subject: [PATCH 2/8] test: pin marketplace summary field names Signed-off-by: Nirmal Khedkar --- internal/consumerapi/market_browse_test.go | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/internal/consumerapi/market_browse_test.go b/internal/consumerapi/market_browse_test.go index 5c848b7..8c7b36f 100644 --- a/internal/consumerapi/market_browse_test.go +++ b/internal/consumerapi/market_browse_test.go @@ -7,6 +7,7 @@ import ( "net/http" "net/http/httptest" "reflect" + "sort" "strings" "testing" "time" @@ -96,6 +97,23 @@ func TestMarketplaceBrowseFilters(t *testing.T) { } } +// Renaming or replacing a summary field must fail even if its field count stays nine. +func TestMarketplaceBrowseSummaryFields(t *testing.T) { + s := browseServer(t) + browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + _, page := browseIDs(t, s, "?category=computer&limit=1") + row := page["listings"].([]any)[0].(map[string]any) + fields := make([]string, 0, len(row)) + for field := range row { + fields = append(fields, field) + } + sort.Strings(fields) + want := []string{"accept_fiat", "accept_member_credit", "category", "listed_at", "listing_id", "maker", "platform", "sales_count", "spec"} + if !reflect.DeepEqual(fields, want) { + t.Fatalf("summary fields = %v, want %v", fields, want) + } +} + // Catches cursors based on filtered offsets, counting sales as offers, missing // continuation, duplicate pages, and leaking narrative in the summary. func TestMarketplaceBrowsePagesAcrossSalesAndAppends(t *testing.T) { From 91207261f610204452699ecbeb25a900983b829a Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:29:30 -0800 Subject: [PATCH 3/8] test: reject repeated well-formed marketplace maker keys Signed-off-by: Nirmal Khedkar --- internal/consumerapi/market_browse_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/consumerapi/market_browse_test.go b/internal/consumerapi/market_browse_test.go index 8c7b36f..0e90ff8 100644 --- a/internal/consumerapi/market_browse_test.go +++ b/internal/consumerapi/market_browse_test.go @@ -167,7 +167,7 @@ func TestMarketplaceBrowseRejectsMalformedFilters(t *testing.T) { const makerParameter = "maker=" for _, query := range []string{ "category=tomato", "category=computer&category=smart_tv", makerParameter, "maker=zz", makerParameter + strings.Repeat("ab", 31), - makerParameter + strings.Repeat("ab", 33), "maker=aa&maker=bb", "rail=", "rail=credit", "rail=fiat,member_credit", + makerParameter + strings.Repeat("ab", 33), makerParameter + strings.Repeat("ab", 32) + "&maker=" + strings.Repeat("cd", 32), "rail=", "rail=credit", "rail=fiat,member_credit", "limit=", "limit=0", "limit=-1", "limit=101", "limit=1junk", "limit=%2B1", "limit=1&limit=2", "cursor=", "cursor=-1", "cursor=1.0", "cursor=1junk", "cursor=%201", "cursor=999999999999999999999999", "cursor=1", "cursor=0&cursor=0", "category=computer%ZZ", From 7572845337b37e33cfb7d365b4b3de0916e59d1c Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:35:05 -0800 Subject: [PATCH 4/8] test: require marketplace page continuation tokens Signed-off-by: Nirmal Khedkar --- internal/consumerapi/market_browse_test.go | 24 ------------- .../consumerapi/market_pagination_test.go | 35 +++++++++++++++++++ 2 files changed, 35 insertions(+), 24 deletions(-) create mode 100644 internal/consumerapi/market_pagination_test.go diff --git a/internal/consumerapi/market_browse_test.go b/internal/consumerapi/market_browse_test.go index 0e90ff8..f4c8665 100644 --- a/internal/consumerapi/market_browse_test.go +++ b/internal/consumerapi/market_browse_test.go @@ -181,30 +181,6 @@ func TestMarketplaceBrowseRejectsMalformedFilters(t *testing.T) { } } -func TestMarketplaceBrowsePageBounds(t *testing.T) { - s := browseServer(t) - for i := 0; i < 103; i++ { - browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) - } - for _, tc := range []struct { - query string - want int - }{ - {"?category=computer", 103}, - {"?category=computer&cursor=0", 50}, - {"?category=computer&limit=100", 100}, - {"?category=computer&limit=100&cursor=100", 3}, - {"?category=computer&limit=1&cursor=103", 0}, - } { - t.Run(tc.query, func(t *testing.T) { - ids, _ := browseIDs(t, s, tc.query) - if len(ids) != tc.want { - t.Fatalf("got %d offers, want %d", len(ids), tc.want) - } - }) - } -} - func BenchmarkMarketplaceBrowse(b *testing.B) { for _, count := range []int{100, 1000} { b.Run(fmt.Sprint(count), func(b *testing.B) { diff --git a/internal/consumerapi/market_pagination_test.go b/internal/consumerapi/market_pagination_test.go new file mode 100644 index 0000000..0fb4707 --- /dev/null +++ b/internal/consumerapi/market_pagination_test.go @@ -0,0 +1,35 @@ +package consumerapi + +import ( + "testing" + + "github.com/NTARI-RAND/Cloudy/internal/market" +) + +func TestMarketplaceBrowsePageBounds(t *testing.T) { + s := browseServer(t) + for i := 0; i < 103; i++ { + browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + } + for _, tc := range []struct { + query string + want int + next any + }{ + {"?category=computer", 103, nil}, + {"?category=computer&cursor=0", 50, "50"}, + {"?category=computer&limit=100", 100, "100"}, + {"?category=computer&limit=100&cursor=100", 3, nil}, + {"?category=computer&limit=1&cursor=103", 0, nil}, + } { + t.Run(tc.query, func(t *testing.T) { + ids, page := browseIDs(t, s, tc.query) + if len(ids) != tc.want { + t.Fatalf("got %d offers, want %d", len(ids), tc.want) + } + if page["next_cursor"] != tc.next { + t.Fatalf("next cursor = %v, want %v", page["next_cursor"], tc.next) + } + }) + } +} From b7c41cd4e07ff5566eeb36272d55cfe48eea96d6 Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:41:34 -0800 Subject: [PATCH 5/8] docs: show a valid exhausted marketplace page Signed-off-by: Nirmal Khedkar --- docs/marketplace-browse.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/marketplace-browse.md b/docs/marketplace-browse.md index b4512a5..491728a 100644 --- a/docs/marketplace-browse.md +++ b/docs/marketplace-browse.md @@ -32,8 +32,10 @@ Supplying `limit` or `cursor` enables paged reads. `limit` must be 1–100; it defaults to 50 when only `cursor` is supplied. Start at `cursor=0` or omit the cursor on the first limited request. +An exhausted page can contain an empty array and has no continuation token: + ```json -{"listings": [], "next_cursor": "125"} +{"listings": []} ``` `listings` contains the same summary fields as before. When more matching From 61e45e99a998bdd8636a882137e0170cb0f6ea20 Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:41:34 -0800 Subject: [PATCH 6/8] docs: clarify marketplace maker identity scope Signed-off-by: Nirmal Khedkar --- CONFORMANCE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONFORMANCE.md b/CONFORMANCE.md index 8767919..2bc35ef 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -80,8 +80,8 @@ See `docs/signed-claim-export.md` for the format and verification boundaries. Public hardware-offer browsing supports exact maker-key and signed accepted-rail filters, plus opt-in bounded append-order pages. Repeated rails match any selected -rail; category and maker filters combine with that selection. The maker remains -the same platform member identity. These are structural discovery controls: +rail; category and maker filters combine with that selection. Maker keys are +the existing platform member keys. These are structural discovery controls: credit acceptance does not switch the economy out of escrow or authorize a credit spend. No narrative, scoring, promotion or settlement authority is added. Bindings: `internal/market/browse.go`, `internal/consumerapi/market_query.go`, and From 9f355af00905ae4827eac8b0c83de5d406104869 Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:43:54 -0800 Subject: [PATCH 7/8] fix: reject marketplace cursors from previous instances Signed-off-by: Nirmal Khedkar --- CONFORMANCE.md | 4 +- docs/marketplace-browse.md | 19 ++++--- internal/consumerapi/market.go | 4 +- internal/consumerapi/market_browse_test.go | 8 +-- .../consumerapi/market_pagination_test.go | 9 +-- internal/consumerapi/market_query.go | 20 +++++-- internal/consumerapi/market_restart_test.go | 57 +++++++++++++++++++ 7 files changed, 99 insertions(+), 22 deletions(-) create mode 100644 internal/consumerapi/market_restart_test.go diff --git a/CONFORMANCE.md b/CONFORMANCE.md index 2bc35ef..fd492ea 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -87,7 +87,9 @@ credit spend. No narrative, scoring, promotion or settlement authority is added. Bindings: `internal/market/browse.go`, `internal/consumerapi/market_query.go`, and `TestMarketplaceBrowseFilters`, `TestMarketplaceBrowsePagesAcrossSalesAndAppends`, `TestMarketplaceBrowseRejectsMalformedFilters`, -`TestMarketplaceBrowseLegacyAndEmptyCategory`, `TestMarketplaceBrowsePageBounds`. +`TestMarketplaceBrowseLegacyAndEmptyCategory`, `TestMarketplaceBrowsePageBounds`, +and `TestMarketplaceBrowseRejectsCursorFromPreviousInstance`. Continuation tokens +bind append positions to the running instance's log ID; stale tokens return 400. Pages avoid full-log/category/sales-history copies, but sparse filters can scan the remaining catalogue. Existing unpaged reads remain unbounded; in-memory, single-writer and witnessing limitations remain unchanged. See diff --git a/docs/marketplace-browse.md b/docs/marketplace-browse.md index 491728a..24171ef 100644 --- a/docs/marketplace-browse.md +++ b/docs/marketplace-browse.md @@ -39,8 +39,9 @@ An exhausted page can contain an empty array and has no continuation token: ``` `listings` contains the same summary fields as before. When more matching -offers exist, `next_cursor` is a decimal string pointing after the last returned -listing in the catalogue log. Follow it with the same category, maker, rail +offers exist, `next_cursor` contains the running instance's log ID and a decimal +append position, separated by `:` (for example, `<64-hex-log-id>:125`). It points +after the last returned listing in the catalogue log. Follow it with the same category, maker, rail selection and page limit. Treat it as a continuation token, not a result count: sales and nonmatching listings also occupy log positions. Exhausted pages omit `next_cursor`; `listings` is always an array, including for empty results. @@ -49,8 +50,11 @@ Append positions stay stable as offers and sales are appended. Pagination is live, not a frozen snapshot: later requests may include new offers and updated sales counts. A cursor equal to the current log length returns an empty page; a cursor beyond the current log length is invalid. Cursors are local to this -in-memory catalogue instance, not portable durable bookmarks. After a restart, -start a fresh traversal. Changing filters also starts a fresh traversal. +in-memory catalogue instance, not portable durable bookmarks. Tokens from another +instance or a previous run return HTTP 400, even when their position would fit +the current log. After a restart, start a fresh traversal with `cursor=0` or omit +the cursor on a limited request. Bare decimal continuations other than the +bootstrap value `0` are rejected. Changing filters also starts a fresh traversal. Each request snapshots its summaries under the existing server lock and writes the response after unlocking. Bounded reads allocate for the page, without @@ -64,8 +68,8 @@ remain unbounded and preserve the `{"listings": [...]}` response shape. Malformed URL query encoding, invalid nonempty categories, malformed/empty maker keys, unknown/empty rails, and repeated singleton parameters (`category`, `maker`, `limit`, `cursor`) return HTTP 400. Rails may repeat; duplicates do not -duplicate offers. Comma-separated rail values are not supported. Page numbers -must contain only ASCII decimal digits and fit a nonnegative Go `int`; signs, +duplicate offers. Comma-separated rail values are not supported. Limits and cursor +positions must contain only ASCII decimal digits and fit a nonnegative Go `int`; signs, whitespace, fractions, suffixes and overflow fail. Empty bounds fail rather than silently becoming defaults. Unknown unrelated query parameters remain ignored. @@ -87,6 +91,7 @@ go test ./internal/consumerapi -run '^$' -bench '^BenchmarkMarketplaceBrowse$' - HTTP tests use real signed registration, product-spec claims, listing creation and the catalogue. They check filter conjunction and rail OR semantics, dual-rail offers, unknown keys, exact summary fields, sale-interleaved append cursors, -continuation after appends, malformed requests, page limits and legacy behavior. +continuation after appends, rejection after a server restart, malformed instance +tokens, malformed requests, page limits and legacy behavior. The benchmark uses a ten-offer page against 100 and 1,000 stored offers. It measures local request allocations and time, not a production capacity guarantee. diff --git a/internal/consumerapi/market.go b/internal/consumerapi/market.go index 7c5765e..7f7cf98 100644 --- a/internal/consumerapi/market.go +++ b/internal/consumerapi/market.go @@ -146,7 +146,7 @@ func (s *Server) listingViewLocked(id market.ListingID, l market.Listing) listin // handleBrowseListings returns public, append-ordered structural summaries. // limit or cursor opts into bounded pages; existing unpaged reads stay compatible. func (s *Server) handleBrowseListings(w http.ResponseWriter, r *http.Request) { - query, paged, err := parseMarketQuery(r.URL.RawQuery) + query, paged, err := s.parseMarketQuery(r.URL.RawQuery) if err != nil { writeErr(w, http.StatusBadRequest, errMarketQuery.Error()) return @@ -161,7 +161,7 @@ func (s *Server) handleBrowseListings(w http.ResponseWriter, r *http.Request) { NextCursor string `json:"next_cursor,omitempty"` }{Listings: out} if paged && next != 0 { - response.NextCursor = strconv.Itoa(next) + response.NextCursor = hx(s.logID[:]) + ":" + strconv.Itoa(next) } writeJSON(w, http.StatusOK, response) } diff --git a/internal/consumerapi/market_browse_test.go b/internal/consumerapi/market_browse_test.go index f4c8665..b03caea 100644 --- a/internal/consumerapi/market_browse_test.go +++ b/internal/consumerapi/market_browse_test.go @@ -128,7 +128,7 @@ func TestMarketplaceBrowsePagesAcrossSalesAndAppends(t *testing.T) { _ = browseListing(t, s, 1, market.CategorySmartTV, market.AcceptedRails{Fiat: true}) b := browseListing(t, s, 2, market.CategoryComputer, market.AcceptedRails{Fiat: true}) first, page := browseIDs(t, s, "?category=computer&limit=1") - if !reflect.DeepEqual(first, []string{a}) || page["next_cursor"] != "1" { + if !reflect.DeepEqual(first, []string{a}) || page["next_cursor"] != hx(s.logID[:])+":1" { t.Fatalf("first page: %v", page) } row := page["listings"].([]any)[0].(map[string]any) @@ -136,11 +136,11 @@ func TestMarketplaceBrowsePagesAcrossSalesAndAppends(t *testing.T) { t.Fatalf("summary fields changed: %v", row) } c := browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{MemberCredit: true}) - second, page := browseIDs(t, s, "?category=computer&limit=1&cursor=1") - if !reflect.DeepEqual(second, []string{b}) || page["next_cursor"] != "4" { + second, page := browseIDs(t, s, "?category=computer&limit=1&cursor="+page["next_cursor"].(string)) + if !reflect.DeepEqual(second, []string{b}) || page["next_cursor"] != hx(s.logID[:])+":4" { t.Fatalf("second page: %v", page) } - last, page := browseIDs(t, s, "?category=computer&limit=1&cursor=4") + last, page := browseIDs(t, s, "?category=computer&limit=1&cursor="+page["next_cursor"].(string)) if !reflect.DeepEqual(last, []string{c}) || page["next_cursor"] != nil { t.Fatalf("last page: %v", page) } diff --git a/internal/consumerapi/market_pagination_test.go b/internal/consumerapi/market_pagination_test.go index 0fb4707..554abf0 100644 --- a/internal/consumerapi/market_pagination_test.go +++ b/internal/consumerapi/market_pagination_test.go @@ -8,6 +8,7 @@ import ( func TestMarketplaceBrowsePageBounds(t *testing.T) { s := browseServer(t) + prefix := hx(s.logID[:]) + ":" for i := 0; i < 103; i++ { browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) } @@ -17,10 +18,10 @@ func TestMarketplaceBrowsePageBounds(t *testing.T) { next any }{ {"?category=computer", 103, nil}, - {"?category=computer&cursor=0", 50, "50"}, - {"?category=computer&limit=100", 100, "100"}, - {"?category=computer&limit=100&cursor=100", 3, nil}, - {"?category=computer&limit=1&cursor=103", 0, nil}, + {"?category=computer&cursor=0", 50, prefix + "50"}, + {"?category=computer&limit=100", 100, prefix + "100"}, + {"?category=computer&limit=100&cursor=" + prefix + "100", 3, nil}, + {"?category=computer&limit=1&cursor=" + prefix + "103", 0, nil}, } { t.Run(tc.query, func(t *testing.T) { ids, page := browseIDs(t, s, tc.query) diff --git a/internal/consumerapi/market_query.go b/internal/consumerapi/market_query.go index 134824f..07209f5 100644 --- a/internal/consumerapi/market_query.go +++ b/internal/consumerapi/market_query.go @@ -5,13 +5,14 @@ import ( "net/url" "slices" "strconv" + "strings" "github.com/NTARI-RAND/Cloudy/internal/market" ) var errMarketQuery = errors.New("invalid marketplace query") -func parseMarketQuery(raw string) (market.ListingQuery, bool, error) { +func (s *Server) parseMarketQuery(raw string) (market.ListingQuery, bool, error) { values, err := url.ParseQuery(raw) if err != nil { return market.ListingQuery{}, false, errMarketQuery @@ -27,7 +28,7 @@ func parseMarketQuery(raw string) (market.ListingQuery, bool, error) { } paged := values.Has("limit") || values.Has("cursor") if paged { - q.Limit, q.Start, err = marketPageBounds(values) + q.Limit, q.Start, err = marketPageBounds(values, hx(s.logID[:])) } return q, paged, err } @@ -57,7 +58,7 @@ func marketFilters(values url.Values) (market.ListingQuery, error) { return q, nil } -func marketPageBounds(values url.Values) (int, int, error) { +func marketPageBounds(values url.Values, instance string) (int, int, error) { limit, start := 50, 0 var err error if values.Has("limit") { @@ -67,7 +68,7 @@ func marketPageBounds(values url.Values) (int, int, error) { } } if values.Has("cursor") { - start, err = marketPageNumber(values.Get("cursor")) + start, err = marketCursorPosition(values.Get("cursor"), instance) } return limit, start, err } @@ -84,3 +85,14 @@ func marketPageNumber(value string) (int, error) { n, err := strconv.Atoi(value) return n, err } + +func marketCursorPosition(cursor, instance string) (int, error) { + if cursor == "0" { + return 0, nil + } + prefix, position, ok := strings.Cut(cursor, ":") + if !ok || prefix != instance { + return 0, errMarketQuery + } + return marketPageNumber(position) +} diff --git a/internal/consumerapi/market_restart_test.go b/internal/consumerapi/market_restart_test.go new file mode 100644 index 0000000..f26dfd8 --- /dev/null +++ b/internal/consumerapi/market_restart_test.go @@ -0,0 +1,57 @@ +package consumerapi + +import ( + "net/http" + "net/url" + "reflect" + "testing" + + "github.com/NTARI-RAND/Cloudy/internal/market" +) + +// A stale position must not silently skip new offers after the catalogue restarts. +func TestMarketplaceBrowseRejectsCursorFromPreviousInstance(t *testing.T) { + original := browseServer(t) + for i := 0; i < 2; i++ { + browseListing(t, original, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + } + _, first := browseIDs(t, original, "?category=computer&limit=1") + cursor, ok := first["next_cursor"].(string) + if !ok || cursor == "" { + t.Fatal("first page has no continuation token") + } + restarted := browseServer(t) + var want []string + for i := 0; i < 3; i++ { + want = append(want, browseListing(t, restarted, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true})) + } + rec, _ := do(t, restarted.Handler(), http.MethodGet, + "/api/v1/market/listings?category=computer&limit=1&cursor="+url.QueryEscape(cursor), nil) + if rec.Code != http.StatusBadRequest { + t.Fatalf("stale cursor returned %d, want 400: %s", rec.Code, rec.Body.String()) + } + got, _ := browseIDs(t, restarted, "?category=computer&cursor=0") + if !reflect.DeepEqual(got, want) { + t.Fatalf("fresh traversal = %v, want all new offers %v", got, want) + } +} + +// Instance binding must not bypass numeric or catalogue-bound validation. +func TestMarketplaceBrowseRejectsMalformedInstanceCursor(t *testing.T) { + s := browseServer(t) + browseListing(t, s, 1, market.CategoryComputer, market.AcceptedRails{Fiat: true}) + prefix := hx(s.logID[:]) + ":" + for _, cursor := range []string{ + "1", "00", prefix, prefix + "-1", prefix + "+1", prefix + " 1", + prefix + "1.0", prefix + "1:0", prefix + "999999999999999999999999", + prefix + "2", "wrong-instance:0", + } { + t.Run(cursor, func(t *testing.T) { + rec, _ := do(t, s.Handler(), http.MethodGet, + "/api/v1/market/listings?category=computer&cursor="+url.QueryEscape(cursor), nil) + if rec.Code != http.StatusBadRequest { + t.Fatalf("cursor %q returned %d, want 400", cursor, rec.Code) + } + }) + } +} From c7b0a7fd01727b2f212ca8b491b7c96a33489cdc Mon Sep 17 00:00:00 2001 From: Nirmal Khedkar Date: Thu, 5 Nov 2026 15:46:42 -0800 Subject: [PATCH 8/8] refactor: share category browsing traversal Signed-off-by: Nirmal Khedkar --- internal/market/browse.go | 9 +++++++-- internal/market/catalog.go | 16 +++------------- 2 files changed, 10 insertions(+), 15 deletions(-) diff --git a/internal/market/browse.go b/internal/market/browse.go index e5a514f..03fc3d9 100644 --- a/internal/market/browse.go +++ b/internal/market/browse.go @@ -32,6 +32,11 @@ func (c *Catalog) Browse(q ListingQuery) (ListingPage, error) { if q.Start < 0 || q.Start > len(c.log) || q.Limit < 0 { return ListingPage{}, errors.New("market: invalid listing page bounds") } + return c.browse(q), nil +} + +// browse shares traversal with queries whose bounds are valid by construction. +func (c *Catalog) browse(q ListingQuery) ListingPage { page := ListingPage{} for pos := q.Start; pos < len(c.log); pos++ { l := c.log[pos].Listing @@ -39,13 +44,13 @@ func (c *Catalog) Browse(q ListingQuery) (ListingPage, error) { continue } if q.Limit > 0 && len(page.IDs) == q.Limit { - return page, nil + return page } page.IDs = append(page.IDs, l.ID()) page.Next = pos + 1 } page.Next = 0 - return page, nil + return page } func (q ListingQuery) matches(l Listing) bool { diff --git a/internal/market/catalog.go b/internal/market/catalog.go index 865318b..66dff2a 100644 --- a/internal/market/catalog.go +++ b/internal/market/catalog.go @@ -138,9 +138,8 @@ func (c *Catalog) Listing(id ListingID) (Listing, bool) { } // SalesOf returns the exchange refs recorded against a listing, in append -// order. The composition root feeds these to the covenant to build the -// per-product LBTAS distribution, and they are the listing's provenance for -// secondary-market resale. +// order. They are the listing's provenance for secondary-market resale; +// SalesCount provides provenance depth without copying this history. func (c *Catalog) SalesOf(id ListingID) []ExchangeRef { out := make([]ExchangeRef, len(c.sales[id])) copy(out, c.sales[id]) @@ -152,16 +151,7 @@ func (c *Catalog) SalesOf(id ListingID) []ExchangeRef { // would be paid placement, which is off-architecture). A consumer applies its // own legible ordering (e.g. covenant distribution, citation weight, recency). func (c *Catalog) ByCategory(cat Category) []ListingID { - var out []ListingID - for _, it := range c.log { - if it.Listing == nil { - continue - } - if it.Listing.Category == cat { - out = append(out, it.Listing.ID()) - } - } - return out + return c.browse(ListingQuery{Category: cat}).IDs } // Log returns the append-ordered log (defensive copies), for replay and