S4 page by cursor: a state page continues from an opaque cursor in sequence order

The runtime's mesh/state.page takes the cursor the page before answered as
next, so a state is read once however many pages it takes; a key written
again since an earlier page comes marked seen-again.

Builds: design 47 H2 §779
This commit is contained in:
2026-11-21 23:56:07 +01:00
parent 6d290eb46b
commit 92cb6a8d6d
4 changed files with 45 additions and 18 deletions
+14 -7
View File
@@ -22,6 +22,9 @@ type StateEntry struct {
Value json.RawMessage `json:"value"` Value json.RawMessage `json:"value"`
Revision uint64 `json:"revision"` Revision uint64 `json:"revision"`
At time.Time `json:"at,omitzero"` At time.Time `json:"at,omitzero"`
// SeenAgain is set in a page (Page) on a key written again since an earlier page of the same read handed it over,
// so a reader knows this value replaces the one it holds (design 47 H2 §779). Get never sets it.
SeenAgain bool `json:"seen-again,omitempty"`
} }
// The operations a watch hands over (StateChange.Op). // The operations a watch hands over (StateChange.Op).
@@ -107,18 +110,22 @@ func (s KeptState) Get(key string) (*StateEntry, error) {
return &e, json.Unmarshal(raw, &e) return &e, json.Unmarshal(raw, &e)
} }
// StatePage is the values of one bulk read: those after a key, in key order, and the key to ask after for the rest. // StatePage is the values of one page of a read: those the bus wrote after the cursor's sequence, in sequence order,
// and the cursor to hand back for the rest (design 47 H2 §779).
type StatePage struct { type StatePage struct {
Entries []StateEntry `json:"entries"` Entries []StateEntry `json:"entries"`
// Next is the last key of Entries when more follow it, else empty. // Next is the opaque cursor that continues the read, empty at its end.
Next string `json:"next,omitempty"` Next string `json:"next,omitempty"`
} }
// Page is the current values in key order after the key `after`, as many as fit maxBytes (keys and values) or the time budget allows, at least // Page is one page of the state's values, in the order the bus wrote them, after the opaque cursor (empty: from the
// one: one request for many values, where Get is one request each. A runtime that does not answer it gives an error // start), as many as fit maxBytes (keys and values; the runtime holds a page to 768 KB at most) or the time budget
// satisfying errors.Is(err, errors.ErrUnsupported), and the reader asks Get per key instead. // allows, at least one: runtime verb `mesh/state.page`, read from an ordered consumer after the cursor's sequence, so a
func (s KeptState) Page(after string, maxBytes int, budget time.Duration) (StatePage, error) { // state is read once however many pages it takes (design 47 H2 §779). A key written again between two pages comes
raw, err := s.ask("page", map[string]any{"after": after, "max_bytes": maxBytes, "budget_ms": budget.Milliseconds()}) // again in a later page with SeenAgain set. Hand Next back for the next page. A runtime that does not answer it gives an
// error satisfying errors.Is(err, errors.ErrUnsupported), and the reader asks Get per key instead.
func (s KeptState) Page(cursor string, maxBytes int, budget time.Duration) (StatePage, error) {
raw, err := s.ask("page", map[string]any{"cursor": cursor, "max_bytes": maxBytes, "budget_ms": budget.Milliseconds()})
if err != nil { if err != nil {
return StatePage{}, err return StatePage{}, err
} }
+17
View File
@@ -59,6 +59,9 @@ func TestABundleKeepsAndWatchesStateThroughTheRuntime(t *testing.T) {
{Name: "take", Run: func(a map[string]any) (any, error) { {Name: "take", Run: func(a map[string]any) (any, error) {
return State("servers").TakeOnce(a["seat"].(string), a["ask"].(string), 10*time.Minute) return State("servers").TakeOnce(a["seat"].(string), a["ask"].(string), 10*time.Minute)
}}, }},
{Name: "page", Run: func(a map[string]any) (any, error) {
return State("servers").Page(a["cursor"].(string), 1000, time.Second)
}},
}, inR, outW) }, inR, outW)
}() }()
lines := bufio.NewScanner(outR) lines := bufio.NewScanner(outR)
@@ -247,6 +250,20 @@ func TestABundleKeepsAndWatchesStateThroughTheRuntime(t *testing.T) {
if r := next(); r["id"] != float64(42) || !strings.Contains(fmt.Sprint(r), "is not an ask id") { if r := next(); r["id"] != float64(42) || !strings.Contains(fmt.Sprint(r), "is not an ask id") {
t.Fatalf("a take with no ask id answered %v", r) t.Fatalf("a take with no ask id answered %v", r)
} }
// Design 47 H2 §779: a page read hands the runtime the opaque cursor and answers the cursor that continues it, and a
// key written again since an earlier page comes marked seen-again.
send(map[string]any{"jsonrpc": "2.0", "id": 43, "method": "tools/call", "params": map[string]any{"name": "page",
"arguments": map[string]any{"cursor": "c.17"}}})
if asked := next(); asked["method"] != "mesh/state.page" || asked["params"].(map[string]any)["cursor"] != "c.17" || asked["params"].(map[string]any)["after"] != nil {
t.Fatalf("asked %v", asked)
} else {
send(map[string]any{"jsonrpc": "2.0", "id": asked["id"], "result": map[string]any{"next": "c.19", "entries": []any{
map[string]any{"key": "a", "value": 1, "revision": 18}, map[string]any{"key": "b", "value": 2, "revision": 19, "seen-again": true}}}})
}
if r := next(); r["id"] != float64(43) || !strings.Contains(fmt.Sprint(r), `"next":"c.19"`) || !strings.Contains(fmt.Sprint(r), `"revision":19,"seen-again":true`) ||
strings.Count(fmt.Sprint(r), "seen-again") != 1 {
t.Fatalf("the page answered %v", r)
}
if !errors.Is(&refused{code: CodeChanged, message: "x"}, ErrChanged) { if !errors.Is(&refused{code: CodeChanged, message: "x"}, ErrChanged) {
t.Fatal("a refusal coded -32010 is not ErrChanged") t.Fatal("a refusal coded -32010 is not ErrChanged")
} }
+7 -6
View File
@@ -25,9 +25,10 @@ func (k KeptSource) Get(key string) (*Entry, bool, error) {
return &Entry{Value: e.Value, Revision: e.Revision, Written: e.At}, true, nil return &Entry{Value: e.Value, Revision: e.Revision, Written: e.At}, true, nil
} }
// Page is the values after a key in one request (stdio.KeptState.Page), as FirstView prefers them to Get per key. // Page is the values after the opaque cursor in one request (stdio.KeptState.Page, in the order the bus wrote them),
func (k KeptSource) Page(after string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error) { // as FirstView prefers them to Get per key, and the cursor that continues them.
p, err := k.State.Page(after, maxBytes, budget) func (k KeptSource) Page(cursor string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error) {
p, err := k.State.Page(cursor, maxBytes, budget)
if err != nil { if err != nil {
return nil, "", err return nil, "", err
} }
@@ -61,10 +62,10 @@ func FirstViewTool(owner, name, state, words string, values, marks Source, now f
Name: name, Name: name,
Description: fmt.Sprintf("The first view of %s's state %s (novox/hq ADR 0615, ADR 0621): %s Each value whole by key, at the revision "+ Description: fmt.Sprintf("The first view of %s's state %s (novox/hq ADR 0615, ADR 0621): %s Each value whole by key, at the revision "+
"the owner said its views family up to, so a reader then follows the events on that family and asks again only on a gap in "+ "the owner said its views family up to, so a reader then follows the events on that family and asks again only on a gap in "+
"revisions. One page at a time: next is the key to ask after for the rest.", "revisions. One page at a time: hand next back as after for the rest.",
owner, state, words), owner, state, words),
Input: map[string]any{"type": "object", "properties": map[string]any{ Input: map[string]any{"type": "object", "properties": map[string]any{
"after": map[string]any{"type": "string", "description": "the key the page before ended at (its next); none starts at the first"}}}, "after": map[string]any{"type": "string", "description": "the next of the page before; none starts at the first"}}},
Run: func(args map[string]any) (any, error) { Run: func(args map[string]any) (any, error) {
after, _ := args["after"].(string) after, _ := args["after"].(string)
return FirstView(owner, state, values, marks, strings.TrimSpace(after), now()) return FirstView(owner, state, values, marks, strings.TrimSpace(after), now())
@@ -87,7 +88,7 @@ func ReadTool(owner, name, state, words string, values, marks Source, now func()
"key": map[string]any{"type": "string", "description": "one key: its value and revision"}, "key": map[string]any{"type": "string", "description": "one key: its value and revision"},
"history": map[string]any{"type": "boolean", "description": "with key: every value the state keeps for it, oldest first"}, "history": map[string]any{"type": "boolean", "description": "with key: every value the state keeps for it, oldest first"},
"values": map[string]any{"type": "boolean", "description": "a page of values whole by key"}, "values": map[string]any{"type": "boolean", "description": "a page of values whole by key"},
"after": map[string]any{"type": "string", "description": "with values: the key the page before ended at"}}}, "after": map[string]any{"type": "string", "description": "with values: the next of the page before"}}},
Run: func(args map[string]any) (any, error) { Run: func(args map[string]any) (any, error) {
key, _ := args["key"].(string) key, _ := args["key"].(string)
after, _ := args["after"].(string) after, _ := args["after"].(string)
+7 -5
View File
@@ -174,7 +174,7 @@ func DecodeMark(data []byte) (Mark, error) {
} }
// Answer is a first view, or one page of an ordinary read: the state's values by key, from After on, at the revision // Answer is a first view, or one page of an ordinary read: the state's values by key, from After on, at the revision
// of the state the owner said up to (Mark) before it read them; Next is the key to ask after for the rest, empty when // of the state the owner said up to (Mark) before it read them; Next is handed back as after for the rest, empty when
// the answer is whole. A reader keeps the first page's revision: a value on a later page may be newer, and the events // the answer is whole. A reader keeps the first page's revision: a value on a later page may be newer, and the events
// after that revision bring every key to its newest in order. // after that revision bring every key to its newest in order.
type Answer struct { type Answer struct {
@@ -222,15 +222,17 @@ type KeyedEntry struct {
Entry Entry
} }
// Pager is a Source that answers many values in one request: the values in key order after a key, as many as fit // Pager is a Source that answers many values in one request: the values after an opaque cursor (empty: from the
// maxBytes or the time budget and at least one, and the key to ask after for the rest. FirstView uses it when its source has it, unless // start), as many as fit maxBytes or the time budget and at least one, and the cursor that continues them, empty at
// the end (design 47 H2 §779). FirstView uses it when its source has it, unless
// it answers errors.Is(err, errors.ErrUnsupported), when it reads per key. // it answers errors.Is(err, errors.ErrUnsupported), when it reads per key.
type Pager interface { type Pager interface {
Page(after string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error) Page(cursor string, maxBytes int, budget time.Duration) ([]KeyedEntry, string, error)
} }
// FirstView answers one page of state from its owner's source: the mark first, so no change after the revision it // FirstView answers one page of state from its owner's source: the mark first, so no change after the revision it
// answers at is missed, then the values in key order after after, until PageBytes or PageBudget. A state not said yet (no mark) // answers at is missed, then the values after after (the next of the page before: the Pager's cursor, or with a source
// that reads per key the last key, in key order), until PageBytes or PageBudget. A state not said yet (no mark)
// answers revision 0: a first view of whatever it holds, which the reader takes as a gap at the first event. // answers revision 0: a first view of whatever it holds, which the reader takes as a gap at the first event.
func FirstView(owner, state string, values, marks Source, after string, now time.Time) (Answer, error) { func FirstView(owner, state string, values, marks Source, after string, now time.Time) (Answer, error) {
a := Answer{V: Version, Owner: owner, State: state, Values: map[string]json.RawMessage{}, At: now.UTC()} a := Answer{V: Version, Owner: owner, State: state, Values: map[string]json.RawMessage{}, At: now.UTC()}