blog.gno
9.28 Kb · 304 lines
1// Package blog is moul's personal blog on gno.land: one realm, one author,
2// posts that live in chain storage rather than in the code.
3//
4// # The shape
5//
6// A post is markdown plus four fields (slug, title, date, tags). Writing one
7// is a single Set transaction, so publishing never redeploys the realm and
8// fixing a typo costs one small call instead of a new package path.
9//
10// The reader-facing paths are deliberately short, because they get pasted into
11// other people's chats:
12//
13// gno.land/r/moul/blog the index, newest first
14// gno.land/r/moul/blog:<slug> one post
15// gno.land/r/moul/blog:t/<tag> every post carrying a tag
16//
17// # Ordering without sort
18//
19// gno has no sort.Slice, and avl.Tree iterates by key. So posts live in two
20// trees: `posts` keyed by slug, for the O(log n) lookup a permalink needs, and
21// `order` keyed by "<date>/<slug>", walked in reverse for newest-first. The
22// date is YYYY-MM-DD precisely so that lexical order is chronological order,
23// which is what makes the second tree free.
24//
25// # Versioning
26//
27// gnomod.toml declares private = true, which lets the creator re-add the
28// package at this exact path. That redeploy re-runs init() and WIPES every
29// post here, so the markdown kept off chain is the source of truth and
30// tools/gnoblog pushes it back. Trading that risk for a stable URL is the
31// whole design: a /v1 would break every link already shared, a redeploy does
32// not, and Manifest() makes restoring the content one diff.
33package blog
34
35import (
36 "crypto/sha256"
37 "encoding/hex"
38 "strconv"
39 "strings"
40
41 "chain/runtime"
42
43 "gno.land/p/nt/avl/v0"
44)
45
46// author is the only address allowed to write. Deliberately a constant rather
47// than transferable ownership: this is one person's blog, and the same address
48// is the only one the chain lets redeploy the realm anyway, so a second owner
49// could publish posts it could never restore after a wipe.
50const author = address("g1manfred47kzduec920z88wfr64ylksmdcedlf5")
51
52// realmPath is this realm's own path, used to build the links Render emits.
53const realmPath = "gno.land/r/moul/blog"
54
55// maxSlugLen bounds a slug so a permalink stays typable and a key stays cheap.
56const maxSlugLen = 64
57
58// excerptLen is how much of a post body the index shows.
59const excerptLen = 200
60
61// introKey is the manifest key of the index header. It starts with '!', which
62// validSlug rejects, so it can never collide with a post.
63const introKey = "!intro"
64
65// introSlug is refused as a post slug. Not because this realm needs it: the
66// intro lives in its own variable. It is refused so that the local half stays
67// representable, where a post is <slug>.md and the header is intro.md. A post
68// published at this slug by a hand-written transaction would have no file it
69// could live in, and tools/gnoblog would report it as an extra forever.
70const introSlug = "intro"
71
72type post struct {
73 slug string
74 title string
75 date string // YYYY-MM-DD, the sort key
76 tags string // comma-separated, normalized by splitTags
77 body string // raw markdown, authored by `author`, rendered unescaped
78 rev int // rev at the time of the last write to this post
79 updated int64 // block height of the last write
80}
81
82var (
83 posts = avl.NewTree() // slug -> *post
84 order = avl.NewTree() // "<date>/<slug>" -> *post
85 intro string // markdown shown above the index
86 rev int // total writes accepted, bumped by every mutation
87)
88
89func assertAuthor(cur realm) {
90 if cur.Previous().Address() != author {
91 panic("restricted to the author")
92 }
93}
94
95// validSlug reports whether slug is a legal permalink: 1..maxSlugLen bytes of
96// [a-z0-9._-]. The character set excludes ':' and '/' so a slug can never
97// break out of its own render path, and excludes uppercase so a post has
98// exactly one URL.
99func validSlug(slug string) bool {
100 if len(slug) == 0 || len(slug) > maxSlugLen {
101 return false
102 }
103 for i := 0; i < len(slug); i++ {
104 c := slug[i]
105 switch {
106 case c >= 'a' && c <= 'z', c >= '0' && c <= '9':
107 case c == '-', c == '_', c == '.':
108 default:
109 return false
110 }
111 }
112 return true
113}
114
115// validDate reports whether date is exactly YYYY-MM-DD. The format is not
116// cosmetic: `order` relies on lexical order being chronological order, so a
117// date of any other shape would silently sort into the wrong place.
118func validDate(date string) bool {
119 if len(date) != 10 {
120 return false
121 }
122 for i := 0; i < 10; i++ {
123 c := date[i]
124 if i == 4 || i == 7 {
125 if c != '-' {
126 return false
127 }
128 continue
129 }
130 if c < '0' || c > '9' {
131 return false
132 }
133 }
134 return true
135}
136
137// orderKey is the key a post takes in `order`. The slug is appended so two
138// posts published on the same day do not collide.
139func orderKey(date, slug string) string { return date + "/" + slug }
140
141// splitTags normalizes a comma-separated tag list: trimmed, lowercased,
142// deduplicated, empties dropped. It returns the canonical string that gets
143// stored, so the hash a client computes locally matches the one on chain.
144func splitTags(tags string) []string {
145 var out []string
146 for _, t := range strings.Split(tags, ",") {
147 t = strings.ToLower(strings.TrimSpace(t))
148 if t == "" {
149 continue
150 }
151 dup := false
152 for _, seen := range out {
153 if seen == t {
154 dup = true
155 break
156 }
157 }
158 if !dup {
159 out = append(out, t)
160 }
161 }
162 return out
163}
164
165func joinTags(tags []string) string { return strings.Join(tags, ",") }
166
167// record is the canonical serialization a post hashes to. Both this realm and
168// tools/gnoblog build it the same way, which is what lets one Manifest() read
169// decide whether a local file needs a transaction at all.
170func record(title, date, tags, body string) string {
171 return title + "\n" + date + "\n" + tags + "\n" + body
172}
173
174func hashOf(s string) string {
175 sum := sha256.Sum256([]byte(s))
176 return hex.EncodeToString(sum[:])
177}
178
179// Set creates or replaces the post at slug. This is the ordinary publish: one
180// post, one transaction, idempotent.
181//
182// Changing the date moves the post in the index, so the old order entry is
183// removed before the new one is written.
184func Set(cur realm, slug, title, date, tags, body string) {
185 assertAuthor(cur)
186 if !validSlug(slug) {
187 panic("invalid slug: want 1-" + strconv.Itoa(maxSlugLen) + " bytes of [a-z0-9._-], got " + strconv.Quote(slug))
188 }
189 if slug == introSlug {
190 panic("reserved slug: " + introSlug + " names the index header, set it with SetIntro")
191 }
192 if !validDate(date) {
193 panic("invalid date: want YYYY-MM-DD, got " + strconv.Quote(date))
194 }
195 title = strings.TrimSpace(title)
196 if title == "" {
197 panic("a post needs a title")
198 }
199
200 if v := posts.Get(slug); v != nil {
201 order.Remove(orderKey(v.(*post).date, slug))
202 }
203
204 rev++
205 p := &post{
206 slug: slug,
207 title: title,
208 date: date,
209 tags: joinTags(splitTags(tags)),
210 body: body,
211 rev: rev,
212 updated: runtime.ChainHeight(),
213 }
214 posts.Set(slug, p)
215 order.Set(orderKey(date, slug), p)
216}
217
218// Append adds to the end of a post's body. It exists for a body too large to
219// fit in one transaction: Set the first chunk, Append the rest. An ordinary
220// edit uses Set, which is idempotent and therefore safe to retry.
221func Append(cur realm, slug, body string) {
222 assertAuthor(cur)
223 v := posts.Get(slug)
224 if v == nil {
225 panic("no such post: " + strconv.Quote(slug))
226 }
227 p := v.(*post)
228 rev++
229 p.body += body
230 p.rev = rev
231 p.updated = runtime.ChainHeight()
232}
233
234// Delete removes a post and its index entry.
235func Delete(cur realm, slug string) {
236 assertAuthor(cur)
237 v, removed := posts.Remove(slug)
238 if !removed {
239 panic("no such post: " + strconv.Quote(slug))
240 }
241 order.Remove(orderKey(v.(*post).date, slug))
242 rev++
243}
244
245// SetIntro replaces the markdown shown above the index. Passing "" restores
246// the built-in header.
247func SetIntro(cur realm, body string) {
248 assertAuthor(cur)
249 rev++
250 intro = body
251}
252
253// Get returns a post's raw markdown body, or "" when there is no such post.
254func Get(slug string) string {
255 v := posts.Get(slug)
256 if v == nil {
257 return ""
258 }
259 return v.(*post).body
260}
261
262// Count returns the number of published posts.
263func Count() int { return posts.Size() }
264
265// Revision returns the total number of writes this realm has accepted. It
266// changes on every mutation, so a client can cheaply tell "nothing moved".
267func Revision() int { return rev }
268
269// Manifest returns one tab-separated line per post, plus one for the intro:
270//
271// <slug>\t<rev>\t<date>\t<len of body>\t<sha256 of the canonical record>
272//
273// It is the diff surface tools/gnoblog reads with a single vm/qeval: the hash
274// covers the title, date, tags and body together, so one read says exactly
275// which local file needs a transaction without downloading a single body.
276//
277// The intro is reported under the key "!intro" with an empty date. '!' is not
278// a legal slug character, so that row can never be confused with a post.
279func Manifest() string {
280 var b strings.Builder
281
282 b.WriteString(introKey)
283 b.WriteString("\t0\t\t")
284 b.WriteString(strconv.Itoa(len(intro)))
285 b.WriteString("\t")
286 b.WriteString(hashOf(intro))
287 b.WriteString("\n")
288
289 posts.Iterate("", "", func(key string, value any) bool {
290 p := value.(*post)
291 b.WriteString(p.slug)
292 b.WriteString("\t")
293 b.WriteString(strconv.Itoa(p.rev))
294 b.WriteString("\t")
295 b.WriteString(p.date)
296 b.WriteString("\t")
297 b.WriteString(strconv.Itoa(len(p.body)))
298 b.WriteString("\t")
299 b.WriteString(hashOf(record(p.title, p.date, p.tags, p.body)))
300 b.WriteString("\n")
301 return false
302 })
303 return b.String()
304}
