Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Community realm. Read the code first. Community realm, deployed by its author. Read the code before you interact or send coins.

kitindexdemo.gno

5.91 Kb · 180 lines
  1// untrusted-render: the tag is charset-checked to [a-z0-9-] at write time and
  2// is the only stored string interpolated raw; the body is a caller's text and
  3// goes through ui.Cell at every call site that renders it.
  4
  5// Package kitindexdemo is a notes board whose only job is to show
  6// gno.land/p/moul/kit/index doing the thing a realm with a store always ends
  7// up needing: answering "every note tagged gno" as cheaply as it answers
  8// "note 7".
  9//
 10// There is no logic of its own here. The records are a kit/store, the two
 11// lookups are kit/index, the page is kit/ui, and what is worth reading is the
 12// shape: every write touches the store and both indexes in ONE function, which
 13// is the entire correctness argument for keeping them in separate containers.
 14//
 15// Demo of the p/moul/kit/index library.
 16package kitindexdemo
 17
 18import (
 19	"chain/markdown"
 20	"strconv"
 21	"strings"
 22
 23	"chain/runtime"
 24
 25	"gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/kit/index/v0"
 26	"gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/kit/store/v0"
 27)
 28
 29// MaxBody is the longest note this realm accepts, in bytes.
 30//
 31// A bound rather than none: every byte stored here locks a storage deposit,
 32// paid by whoever signs the write and refunded to whoever signs the delete
 33// (EFFECTIVE_GNO.md section 9.2), and an unbounded write is an unbounded
 34// state the realm carries forever.
 35const MaxBody = 280
 36
 37// MaxTagLen bounds the index key for the same reason, and small because a tag
 38// is a label rather than a sentence.
 39const MaxTagLen = 24
 40
 41// PageSize is how many tags the root page shows.
 42const PageSize = 20
 43
 44// MaxNotes and MaxPerAuthor bound the WHOLE board, which MaxBody does not.
 45//
 46// A per-call length limit bounds one write and nothing else: a caller posting
 47// one-byte notes in a loop grows the store and both indexes without limit. "An unbounded container a third party can grow is an
 48// unbounded storage deposit someone is paying for" is a rule this realm exists
 49// to demonstrate, so it had better obey it.
 50//
 51// Two caps rather than one, and what each buys is narrower than it looks.
 52// MaxNotes bounds the state, which is the property this realm promises.
 53// MaxPerAuthor stops one ADDRESS, not one actor: addresses are free, so fifty
 54// fresh ones at twenty notes each still fill the board and lock everyone else
 55// out until somebody retracts. Keeping a board open to strangers needs
 56// something a griefer cannot mint for free, a deposit or an expiry, which this
 57// demo does not carry. Retracting frees a slot, so neither cap is a one-way door.
 58//
 59// MaxPerAuthor is answered by byAuthor.Count, which is the index doing the job
 60// it was added for.
 61const (
 62	MaxNotes     = 1000
 63	MaxPerAuthor = 20
 64)
 65
 66type note struct {
 67	Author address
 68	Tag    string
 69	Body   string
 70	Height int64
 71}
 72
 73var (
 74	notes    = store.Named("note")
 75	byTag    index.Index
 76	byAuthor index.Index
 77)
 78
 79// Post files a note under a tag and returns its id.
 80//
 81// The store write and both index writes happen here, in this order, in one
 82// frame. An abort anywhere in it leaves none of them applied, which is what
 83// makes three containers safe to keep apart.
 84func Post(cur realm, tag, body string) int64 {
 85	who := caller(cur)
 86	tag = normaliseTag(tag)
 87	assertBody(body)
 88	assertRoom(who)
 89
 90	id := notes.Add(&note{
 91		Author: who,
 92		Tag:    tag,
 93		Body:   body,
 94		Height: runtime.ChainHeight(),
 95	})
 96	mustIndex(byTag.Add(tag, id))
 97	mustIndex(byAuthor.Add(who.String(), id))
 98	return int64(id)
 99}
100
101// Retract removes a note. Only its author may, and the store and both indexes
102// are unwound together.
103func Retract(cur realm, id int64) {
104	who := caller(cur)
105	sid, ok := store.ParseID(strconv.FormatInt(id, 10))
106	if !ok {
107		panic("kitindexdemo: not an id: " + strconv.FormatInt(id, 10))
108	}
109	n, ok := notes.Get(sid)
110	if !ok {
111		panic("kitindexdemo: note #" + sid.String() + " not found")
112	}
113	rec := n.(*note)
114	if rec.Author != who {
115		panic("kitindexdemo: note #" + sid.String() + " is not yours")
116	}
117	notes.Remove(sid)
118	byTag.Remove(rec.Tag, sid)
119	byAuthor.Remove(rec.Author.String(), sid)
120}
121
122// caller is the one place this realm decides who is acting: the realm token is
123// checked before it is walked, because an unchecked token is not a caller.
124func caller(cur realm) address {
125	if !cur.IsCurrent() {
126		panic("kitindexdemo: spoofed realm")
127	}
128	return cur.Previous().Address()
129}
130
131func mustIndex(err error) {
132	if err != nil {
133		panic(err)
134	}
135}
136
137// normaliseTag lowercases and validates the tag.
138//
139// Validated at WRITE time rather than escaped at render time, deliberately: a
140// tag is also an index key and a path segment, so a tag that could carry a
141// pipe or a slash would break the table and the URL as well as the page. The
142// charset is the narrowest thing that still reads as a label.
143func normaliseTag(tag string) string {
144	tag = strings.ToLower(strings.TrimSpace(tag))
145	if tag == "" || len(tag) > MaxTagLen {
146		panic("kitindexdemo: a tag is 1 to " + strconv.Itoa(MaxTagLen) + " characters")
147	}
148	for _, r := range tag {
149		switch {
150		case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-':
151		default:
152			panic("kitindexdemo: a tag is [a-z0-9-], got " + strconv.Quote(tag))
153		}
154	}
155	return tag
156}
157
158// assertRoom refuses a write the board has no room for, globally or for this
159// address. Checked before the store write, so a refusal costs the caller the
160// gas of three reads and nothing is half-applied.
161func assertRoom(who address) {
162	if notes.Len() >= MaxNotes {
163		panic("kitindexdemo: the board is full at " + strconv.Itoa(MaxNotes) +
164			" notes; retract one to free a slot")
165	}
166	if n := byAuthor.Count(who.String()); n >= MaxPerAuthor {
167		panic("kitindexdemo: " + who.String() + " already has " + strconv.Itoa(n) +
168			" notes, the limit is " + strconv.Itoa(MaxPerAuthor))
169	}
170}
171
172func assertBody(body string) {
173	if strings.TrimSpace(markdown.StripBidiAndZeroWidth(body)) == "" {
174		panic("kitindexdemo: the body is empty")
175	}
176	if len(body) > MaxBody {
177		panic("kitindexdemo: the body is " + strconv.Itoa(len(body)) +
178			" bytes, the limit is " + strconv.Itoa(MaxBody))
179	}
180}