Migration This is my new public git source viewer. Source available. Please contact with concerns/bugs. Contact me

internal/core/core.go

d640ddbb8ad06f0e54d9c6e33c347acf247818e6 · 16.1 KB · 513 lines raw

1 // Package core is the extension point. A module computes one piece of a
2 // view; a route binds modules to an output file. Adding a feature means
3 // adding a module and using it from a template -- nothing here changes.
4 package core
5
6 import (
7 "fmt"
8 "sort"
9 "strconv"
10 "strings"
11 "sync"
12 "sync/atomic"
13 "time"
14
15 "gsg/internal/access"
16 "gsg/internal/gitx"
17 )
18
19 // ------------------------------------------------------------------ config
20
21 type Site struct {
22 Name string
23 BaseURL string
24 Root string // directory containing bare repos
25
26 // RevFn, when set, returns a token that changes whenever site-level
27 // configuration changes without a commit moving -- operator notices,
28 // for example. Ctx.contentIdentity() folds it into both the module
29 // cache key and the response ETag, so a module reading that config
30 // cannot serve a result that predates the change. Set once at startup,
31 // before the server begins serving.
32 RevFn func() string
33
34 idx atomic.Pointer[repoIndex]
35 mu sync.Mutex // serializes upsert/remove; RepoList/Lookup never block
36
37 // configRev counts every upsert/remove, i.e. every time a repo's own
38 // git config or existence changes (watch.go's reconcile calls mutate
39 // for exactly this). Folded into Revision() so that ETags and the
40 // module cache invalidate when a repo's config changes -- gsg.hide,
41 // gsg.visible-to, gsg.share-revoked-after -- not just when notices do.
42 // Without this, a browser could revalidate a stale, cached page whose
43 // ETag predates a config change that was supposed to take effect
44 // immediately, such as a share-link revocation.
45 configRev atomic.Uint64
46 }
47
48 // repoIndex is an immutable snapshot, swapped in whole by upsert/remove so
49 // readers (RepoList, Lookup) never need a lock.
50 type repoIndex struct {
51 list []Handle // every known repo, hidden or not -- repos.go filters Hidden itself
52 bySlug map[string]Handle // every known repo, hidden or not -- Server.buildCtx enforces visibility
53 }
54
55 // RepoList is every discovered repository. Site-scoped routes (the index
56 // page, the index endpoint) read it through the `repos` module.
57 func (s *Site) RepoList() []Handle {
58 if idx := s.idx.Load(); idx != nil {
59 return idx.list
60 }
61 return nil
62 }
63
64 // Lookup resolves a repo by slug for per-repo routes, hidden or not -- the
65 // caller (Server.buildCtx) is responsible for enforcing the access policy
66 // before using the result.
67 func (s *Site) Lookup(slug string) (Handle, bool) {
68 idx := s.idx.Load()
69 if idx == nil {
70 return Handle{}, false
71 }
72 h, ok := idx.bySlug[slug]
73 return h, ok
74 }
75
76 // Revision is the site-level analogue of RepoInfo.GPGKeyring: a token for
77 // inputs that change outside a commit -- notices, and any repo's own git
78 // config (gsg.hide, gsg.visible-to, gsg.share-revoked-after, ...). Nil-safe
79 // because tests construct bare *Ctx values and LoadTemplates parses with
80 // &Ctx{}.
81 func (s *Site) Revision() string {
82 if s == nil {
83 return ""
84 }
85 rev := strconv.FormatUint(s.configRev.Load(), 10)
86 if s.RevFn != nil {
87 rev += "|" + s.RevFn()
88 }
89 return rev
90 }
91
92 // upsert and remove are the only writers of the repo index, both called
93 // exclusively from watch.go's reconcile -- at startup and at runtime alike,
94 // through the same code path.
95 func (s *Site) upsert(h Handle) {
96 s.mutate(func(list []Handle) []Handle {
97 for i, e := range list {
98 if e.Info.Slug == h.Info.Slug {
99 list[i] = h
100 return list
101 }
102 }
103 return append(list, h)
104 })
105 }
106
107 func (s *Site) remove(slug string) {
108 s.mutate(func(list []Handle) []Handle {
109 for i, e := range list {
110 if e.Info.Slug == slug {
111 return append(list[:i], list[i+1:]...)
112 }
113 }
114 return list
115 })
116 }
117
118 func (s *Site) mutate(f func([]Handle) []Handle) {
119 s.mu.Lock()
120 defer s.mu.Unlock()
121
122 var cur []Handle
123 if idx := s.idx.Load(); idx != nil {
124 cur = append([]Handle(nil), idx.list...)
125 }
126 next := f(cur)
127
128 bySlug := make(map[string]Handle, len(next))
129 for _, h := range next {
130 bySlug[h.Info.Slug] = h
131 }
132 s.idx.Store(&repoIndex{list: next, bySlug: bySlug})
133 s.configRev.Add(1)
134 }
135
136 // Handle pairs an open repository with its configuration.
137 type Handle struct {
138 Repo *gitx.Repo
139 Info RepoInfo
140 }
141
142 // RepoInfo is the per-repository configuration, read from the repo's own
143 // git config the way cgit does. Keys, in priority order:
144 //
145 // [gsg] [gitweb]
146 // title = ... owner = ...
147 // description = ... description = ...
148 // owner = ...
149 // clone = git://...
150 // hide = true
151 // section = infra
152 // gpgkeyring = /path/to/keys.asc
153 // visible-to = alice,bob
154 // cache-max-age = 2m
155 //
156 // Set them with: git --git-dir=/srv/git/foo.git config gsg.title "Foo"
157 type RepoInfo struct {
158 Slug string
159 Title string
160 Description string
161 Owner string
162 Clone string
163 Section string
164 Hidden bool
165
166 // VisibleTo is the gsg.visible-to allowlist: usernames (matched against
167 // an authenticated session, case-insensitively) who may see this repo
168 // even though Hidden is set. A separate key from Owner deliberately --
169 // Owner is a free-text display field (and falls back to gitweb.owner
170 // for cgit-migrated repos), so reusing it as an ACL could silently
171 // grant access nobody intended.
172 VisibleTo []string
173
174 // ShareMaxAge is gsg.share-max-age: both the ceiling no share-link
175 // expiry for this repo may exceed, and the default when a mint request
176 // doesn't specify one. Falls back to defaultShareMaxAge when unset.
177 ShareMaxAge time.Duration
178
179 // ShareRevokedAfter is gsg.share-revoked-after: any share-link grant
180 // for this repo issued at or before this instant is rejected,
181 // regardless of the link's own expiry. It is the only revocation lever
182 // a stateless share token has -- see internal/share.
183 ShareRevokedAfter time.Time
184
185 // GPGKeyring is the configured path to a file of armored public keys
186 // (gsg.gpgkeyring), if any. Reading it here is just config; the import
187 // into an isolated keyring happens in watch.go's reconcile (see
188 // gitx.Repo.WithKeyring). If that import fails, reconcile overwrites
189 // this with the keyring the Handle's Repo actually has -- the previous
190 // one, or "" -- so templates and cache keys describe what is backing
191 // verification, not what was configured.
192 GPGKeyring string
193
194 // CacheMaxAge is gsg.cache-max-age: how long an anonymous (no session,
195 // no share grant) response for this repo may be reused -- both by the
196 // requesting browser (Cache-Control: public, max-age=...) and by gsg's
197 // own in-memory response cache (Server.respCache) -- before either has
198 // to ask again. Falls back to defaultAnonCacheMaxAge when unset.
199 CacheMaxAge time.Duration
200 }
201
202 func LoadRepoInfo(r *gitx.Repo) RepoInfo {
203 title := r.ConfigFirst("gsg.title")
204 if title == "" {
205 title = r.Slug
206 }
207 desc := r.ConfigFirst("gsg.description", "gitweb.description")
208 if desc == "" {
209 desc = r.DescriptionFile() // cgit-compatible fallback
210 }
211 return RepoInfo{
212 Slug: r.Slug,
213 Title: title,
214 Description: desc,
215 Owner: r.ConfigFirst("gsg.owner", "gitweb.owner"),
216 Clone: r.ConfigFirst("gsg.clone", "gitweb.url"),
217 Section: r.ConfigFirst("gsg.section", "gitweb.category"),
218 Hidden: strings.EqualFold(r.Config("gsg.hide"), "true"),
219 VisibleTo: splitUsers(r.Config("gsg.visible-to")),
220 ShareMaxAge: parseShareMaxAge(r.Config("gsg.share-max-age")),
221 ShareRevokedAfter: parseUnixTime(r.Config("gsg.share-revoked-after")),
222 GPGKeyring: r.Config("gsg.gpgkeyring"),
223 CacheMaxAge: parseCacheMaxAge(r.Config("gsg.cache-max-age")),
224 }
225 }
226
227 // defaultShareMaxAge is the ceiling/default applied when a repo doesn't set
228 // gsg.share-max-age.
229 const defaultShareMaxAge = 30 * 24 * time.Hour
230
231 func parseShareMaxAge(v string) time.Duration {
232 if v == "" {
233 return defaultShareMaxAge
234 }
235 d, err := time.ParseDuration(v)
236 if err != nil || d <= 0 {
237 return defaultShareMaxAge
238 }
239 return d
240 }
241
242 // defaultAnonCacheMaxAge is the ceiling/default applied when a repo doesn't
243 // set gsg.cache-max-age.
244 const defaultAnonCacheMaxAge = 2 * time.Minute
245
246 func parseCacheMaxAge(v string) time.Duration {
247 if v == "" {
248 return defaultAnonCacheMaxAge
249 }
250 d, err := time.ParseDuration(v)
251 if err != nil || d <= 0 {
252 return defaultAnonCacheMaxAge
253 }
254 return d
255 }
256
257 func parseUnixTime(v string) time.Time {
258 if v == "" {
259 return time.Time{}
260 }
261 sec, err := strconv.ParseInt(v, 10, 64)
262 if err != nil {
263 return time.Time{}
264 }
265 return time.Unix(sec, 0)
266 }
267
268 // splitUsers parses a comma-separated gsg.visible-to value into trimmed,
269 // non-empty usernames.
270 func splitUsers(v string) []string {
271 if v == "" {
272 return nil
273 }
274 parts := strings.Split(v, ",")
275 out := make([]string, 0, len(parts))
276 for _, p := range parts {
277 if p = strings.TrimSpace(p); p != "" {
278 out = append(out, p)
279 }
280 }
281 return out
282 }
283
284 // AccessPolicy is the authorization-relevant subset of RepoInfo. The rules
285 // themselves live in internal/access so core, modules, share minting and
286 // share redemption cannot drift into slightly different answers.
287 func (info RepoInfo) AccessPolicy() access.Policy {
288 return access.Policy{
289 Slug: info.Slug,
290 Hidden: info.Hidden,
291 VisibleTo: info.VisibleTo,
292 ShareRevokedAfter: info.ShareRevokedAfter,
293 }
294 }
295
296 // ----------------------------------------------------------------- context
297
298 // Ctx is what a module is given: which repo, at which ref, at which path.
299 // The cache makes `mod` idempotent within a single page render, so two
300 // templates asking for the same module do not pay for it twice.
301 type Ctx struct {
302 Site *Site
303 Repo *gitx.Repo
304 Info RepoInfo
305 Ref string // the ref as the user spelled it ("main", "v0.1.0", a sha)
306 Path string
307 Vars map[string]string
308
309 // User is the authenticated username from the gsg_user session cookie,
310 // or "" for an anonymous request. Resolved once in Server.buildCtx.
311 // Never derived from a request header directly -- see internal/session.
312 User string
313
314 // SharedSlugs and SharedIssuedAt come from a verified gsg_share cookie,
315 // if one was present (SharedSlugs is nil otherwise). They are not yet
316 // filtered for revocation -- access.Policy applies gsg.share-revoked-after
317 // against SharedIssuedAt at the point of use, since revocation is per-repo
318 // and this Ctx may span several.
319 SharedSlugs []string
320 SharedIssuedAt time.Time
321
322 // Nav is the repo-scoped tab bar, built once in Server.serve from the
323 // route table (see nav.go). Empty for site-scoped routes.
324 Nav []NavItem
325
326 // Commit is Ref resolved to a full SHA. Everything a module computes
327 // at a given Commit is immutable, which is what makes the shared
328 // cache and ETags correct rather than merely convenient.
329 Commit string
330
331 // Immutable is true when this response is served with the year-long
332 // immutable cache policy (see Server.serve). Page chrome that can change
333 // without the commit moving must not be rendered into it, because the
334 // browser is told never to revalidate. Operator notices are the first
335 // such thing; this is deliberately the *computed* condition, not just
336 // Route.Immutable, so it follows whatever the caching rule becomes.
337 Immutable bool
338
339 // Store is the process-wide cache, nil in tests. Only consulted when
340 // Commit is set.
341 Store Store
342
343 // StaticTag is Server.StaticTag, threaded through so the `static`
344 // template func can build cache-busting asset URLs without a package
345 // import cycle back to Server.
346 StaticTag string
347
348 mu sync.Mutex
349 cache map[string]result
350 }
351
352 // Store is the cross-request cache. Implemented by internal/core.LRU.
353 type Store interface {
354 Get(key string) (any, bool)
355 Put(key string, v any)
356 }
357
358 type result struct {
359 val any
360 err error
361 }
362
363 func NewCtx(site *Site, r *gitx.Repo, info RepoInfo, ref string) *Ctx {
364 return &Ctx{Site: site, Repo: r, Info: info, Ref: ref,
365 Vars: map[string]string{}, cache: map[string]result{}}
366 }
367
368 // contentIdentity captures every input that can change what a route
369 // renders at a fixed commit -- the commit itself, plus anything that can
370 // change without the commit moving. Vars are part of it: /compare/a..b and
371 // /compare/a...b resolve to the same head commit, so without the base ref
372 // in here the second request was served the first one's diff. GPGKeyring
373 // is part of it for the same reason: watch.go's reconcile can change a
374 // repo's keyring under commits whose SHAs haven't moved, and a page
375 // fetched before that would otherwise cache "unsigned" forever.
376 // Site.Revision() is the site-level equivalent of the keyring: operator
377 // notices change without a commit moving, so a page cached before a notice
378 // edit would otherwise keep serving the old banners forever.
379 //
380 // CacheKey and the response ETag (server.go) are both built from this, so
381 // a new Var or a keyring change can't invalidate one without invalidating
382 // the other -- that used to be two hand-maintained lists that had already
383 // drifted (the ETag was missing GPGKeyring and any Var besides baseSHA).
384 func (c *Ctx) contentIdentity() string {
385 keys := make([]string, 0, len(c.Vars))
386 for k := range c.Vars {
387 keys = append(keys, k)
388 }
389 sort.Strings(keys)
390 var b strings.Builder
391 b.WriteString(c.Commit + "|" + c.Info.GPGKeyring + "|" + c.Site.Revision())
392 for _, k := range keys {
393 b.WriteString("|" + k + "=" + c.Vars[k])
394 }
395 return b.String()
396 }
397
398 // CacheKey identifies an immutable module result. Empty when the result
399 // cannot be cached (no resolved commit).
400 func (c *Ctx) CacheKey(name string, args []string) string {
401 if c.Commit == "" || c.Store == nil {
402 return ""
403 }
404 return c.Info.Slug + "|" + c.Path + "|" + name + "|" +
405 strings.Join(args, "\x00") + "|" + c.contentIdentity()
406 }
407
408 // Derive returns a shallow copy for a different path, with a fresh cache.
409 func (c *Ctx) Derive(path string, vars map[string]string) *Ctx {
410 n := NewCtx(c.Site, c.Repo, c.Info, c.Ref)
411 n.User = c.User
412 n.SharedSlugs = c.SharedSlugs
413 n.SharedIssuedAt = c.SharedIssuedAt
414 n.Path = path
415 for k, v := range c.Vars {
416 n.Vars[k] = v
417 }
418 for k, v := range vars {
419 n.Vars[k] = v
420 }
421 return n
422 }
423
424 func (c *Ctx) Var(k string) string { return c.Vars[k] }
425
426 // cacheMaxAge is how long an anonymous response for this repo may be
427 // reused before revalidating. Server.buildResponseHead (the browser-facing
428 // Cache-Control header) and Server.fillResponse (the server-side response
429 // cache's own TTL) both read this, so the two never disagree about
430 // staleness.
431 func (c *Ctx) cacheMaxAge() time.Duration {
432 if c.Info.CacheMaxAge > 0 {
433 return c.Info.CacheMaxAge
434 }
435 return defaultAnonCacheMaxAge
436 }
437
438 // ---------------------------------------------------------------- registry
439
440 // Module computes one piece of a view. Anything a template or an endpoint
441 // might want is a module: readme, tree, log, refs, graph, blame, stats.
442 type Module func(c *Ctx, args ...string) (any, error)
443
444 var (
445 regMu sync.RWMutex
446 registry = map[string]Module{}
447 )
448
449 // Register adds a module. Call it from an init() in the modules package.
450 func Register(name string, m Module) {
451 regMu.Lock()
452 defer regMu.Unlock()
453 if _, dup := registry[name]; dup {
454 panic("core: duplicate module " + name)
455 }
456 registry[name] = m
457 }
458
459 func Names() []string {
460 regMu.RLock()
461 defer regMu.RUnlock()
462 out := make([]string, 0, len(registry))
463 for n := range registry {
464 out = append(out, n)
465 }
466 return out
467 }
468
469 // Mod runs a module, memoized per Ctx. This is the single entry point
470 // used by both templates (via the funcmap) and JSON endpoints.
471 func (c *Ctx) Mod(name string, args ...string) (any, error) {
472 key := name + "\x00" + strings.Join(args, "\x00")
473
474 c.mu.Lock()
475 if c.cache == nil {
476 c.cache = map[string]result{}
477 }
478 if r, ok := c.cache[key]; ok {
479 c.mu.Unlock()
480 return r.val, r.err
481 }
482 c.mu.Unlock()
483
484 regMu.RLock()
485 m, ok := registry[name]
486 regMu.RUnlock()
487 if !ok {
488 return nil, fmt.Errorf("no such module %q (have: %s)", name, strings.Join(Names(), ", "))
489 }
490
491 // Cross-request cache: a module's output at a fixed commit SHA cannot
492 // change, so this is safe without any invalidation logic. Nothing here
493 // is keyed on a ref name -- refs move, SHAs do not.
494 shared := c.CacheKey(name, args)
495 if shared != "" {
496 if v, ok := c.Store.Get(shared); ok {
497 c.mu.Lock()
498 c.cache[key] = result{v, nil}
499 c.mu.Unlock()
500 return v, nil
501 }
502 }
503
504 val, err := m(c, args...)
505 if err == nil && shared != "" {
506 c.Store.Put(shared, val)
507 }
508
509 c.mu.Lock()
510 c.cache[key] = result{val, err}
511 c.mu.Unlock()
512 return val, err
513 }