Compare

+internal/access/ repo visibility + share-grant policy (imports no core)

+internal/authn/ login/logout endpoints

+internal/httpx/ shared admin/share HTTP security helpers

+internal/notices/ operator notices: YAML store + admin UI (imports no core)

+internal/site/ the route table and route-specific request parsers

+**`internal/access`** owns the rule for whether an identity may view or

+share a repo. It deliberately imports nothing from `core`, so the 404 gate,

+the index module, share minting and share redemption all call the same

+policy. Do not grow a second visibility check elsewhere.

+

+`Ctx.contentIdentity()` also folds in inputs that change *without* the commit

+moving: `RepoInfo.GPGKeyring` and `Site.Revision()`. Site revision is the

+site-level analogue of the keyring; operator notices use it so a banner edit

+invalidates both the module cache and every ETag. Anything else with that

+shape belongs there too.

+

+`Ctx.Immutable` marks responses served with the year-long immutable cache

+(see `Server.serve`). Commit-independent chrome must not be rendered into

+them, because the browser is told never to revalidate; the notices partial

+skips those pages for exactly this reason.

+

+`Content-Disposition: attachment` for binaries) with

+The one deliberate exception is a validated raster image (PNG, JPEG, GIF,

+WebP, BMP, ICO, AVIF): `modules/image.go` requires the extension and the

+magic bytes to agree before `/raw/` may declare `image/*`, so an `.png`

+holding HTML is not relabelled. SVG is never in that list — it is an XML

+document that can carry a script, so it stays `text/plain`. A raster image

+is safe to serve inline because it cannot execute and `nosniff` stops the

+declared type from being re-sniffed; the blob page needs those bytes on the

+same origin for its `<img>` preview, and the same URL is the download link.

+everything together. If the route needs a new path grammar, declare a

+`Route.Request` parser in `internal/site`; core still resolves every ref it

+returns. Pagination is declared with `Route.PageSize`.

+### Add an operator notice source

+

+Notices (global and per-repo banners) live in `internal/notices`: a

+file-backed store watched for changes, plus the admin listener. The

+`notices` module merges the global list with the current repo's, and

+`templates/layouts/notices.html` renders them — but only when

+`Ctx.Immutable` is false. `main.go` wires the store to `Site.RevFn` so a

+change invalidates caches. `internal/notices` deliberately does not import

+`internal/core`; keep it that way so the module and the admin handler can

+both reach it without a cycle. The admin listener is the one deliberate

+write path, and it writes a config file, never a repository.

+

+- Path queries in the structured JSON/YAML search store the deepest path

+ found for a line. Flow style (`{"a": 1, "b": 2}`) puts several values on

+ one row and keeps only the last path; a container query still reaches the

+ others through the prefix match, but a sibling's exact path does not.

+FROM --platform=$BUILDPLATFORM golang:1.23-alpine AS build

+WORKDIR /src

+COPY go.mod go.sum ./

+RUN go mod download

+COPY . .

+ARG TARGETOS=linux

+ARG TARGETARCH=amd64

+RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/gsg .

+

+FROM alpine:3.20

+RUN apk add --no-cache git gnupg

+COPY --from=build /out/gsg /usr/local/bin/gsg

+

+EXPOSE 8080

+ENTRYPOINT ["gsg"]

+CMD ["-root", "/srv/git", "-addr", ":8080"]

+# My git viewer

+

+### Why I did this

+

+So, the premise behind this project was a few different things:

+

+- I wanted a git viewer stack that, while modular, remained light.

+- I liked the idea of having reusable "templates" rather than generating the HTML dynamically in the code. This is much closer to how things like Hugo operate.

+- It needs to be easy to extend (modularity!). A core is responsible for loading a git repo's context and other request state, but all "real" functionality is implemented via modules. I could add/remove things without needing to worry (too much...) about breaking unrelated things.

+- I wanted something that was modern, but didn't require javascript to operate. All features on this site work without javascript, though your experience is improved with it.

+- I wanted to have a way to view private git repositories using systems I already have.

+ - I don't want to/have the capability to SSH clone my repos to show something off.

+ - Could I have done this in cgit? Perhaps, but it wasn't built for it.

+- And, probably most visibly, this was a trial in "vibe coding". While the idea around the design of this software was mine, I wrote very little of the code. Especially the UI, and this is for the better. I am not a graphics designer and whatever slop the LLM pumps out (with my input here and there) will be leagues better than whatever I do; for better or worse.

+

+The name "gsg" doesn't mean much (I don't name things). It're pretty much "git static generator". It was the placeholder when I was thinking of a system that was "kind of a combination of cgit's lightness and hugo's composability and templating".

+

+### The design

+

+First and foremost, the AI writeup is in ./llm_readme.md. Read that if you want all of the verbose details.

+

+Also, as alluded to above, no javascript is strictly required. The few places it is used it is just used to make the experience nicer, and a fallback always exists. For example, the JSON/YAML codepath has a JS module that allows you to search for values/keys, perform folding, etc. This is a core design tenant: JS always hydrates what exists already.

+

+(Not) Broadly speaking, as stated above, this project is split up into:

+

+- The core

+ - gitx - the module that actually interfaces with git. This transforms a context into a re-usable struct (should I ever want to use a real implementation)

+ - access - Consolidated checks for whether someone can see/not see a repo

+ - session - Owns all privileged access logic. It generates/verifies tokens that are used across the site. Everything is stateless once authenticated.

+ - authn - Route owner that defines login/logout flows. Uses session internally

+ - httpx - Shared helpers used when generating responses/evaling a req

+ - notices - Logic for me to post notices to the site or repos

+ - share - Logic for authenticated users to mint links to private repos they are allowed to. Uses same auth logic as users under the hood.

+ - api - Exposes repo details as a JSON endpoint, will be used by my main site later on

+ - core/site - All the main things needed to make this tick. Build req context, define routes and where they live, define module registration structs.

+- The modules

+ - blob - Responsible for returning files (raw or templated)

+ - commit - Render a commit

+ - compare - Render a diff between two commits/refs

+ - graph - Render commit log graph

+ - image - Image preview, defines compatible file types and max size

+ - markdown - Render markdown

+ - readme - Inherits markdown to render a readme (what you see here!)

+ - notices - Handles cache invalidation for repos that need one rendered

+ - log - View the git log

+ - repos - Aggregates the repos you may view based on session

+ - structured - Whether a file is a YAML or JSON. If so, it prepares data for JS in the frontend to perform folding and suchA

+ - tree - the directory-structure viewer

+

+As time goes on, I am sure I will find more things to add to this. This is really meant to be a project for me, not necessarily building "the next git viewer for everyone".

+

+I figured I would upload this here in case my tokens are useful for others. Enjoy!

+go 1.23.0

+require (

+ github.com/alecthomas/chroma/v2 v2.24.1

+ github.com/fsnotify/fsnotify v1.10.1

+ github.com/yuin/goldmark v1.8.5

+ golang.org/x/sync v0.14.0

+ gopkg.in/yaml.v3 v3.0.1

+)

+

+require (

+ github.com/dlclark/regexp2 v1.12.0 // indirect

+ golang.org/x/sys v0.13.0 // indirect

+)

+github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=

+github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=

+github.com/alecthomas/chroma/v2 v2.24.1 h1:m5ffpfZbIb++k8AqFEKy9uVgY12xIQtBsQlc6DfZJQM=

+github.com/alecthomas/chroma/v2 v2.24.1/go.mod h1:l+ohZ9xRXIbGe7cIW+YZgOGbvuVLjMps/FYN/CwuabI=

+github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs=

+github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=

+github.com/dlclark/regexp2 v1.12.0 h1:0j4c5qQmnC6XOWNjP3PIXURXN2gWx76rd3KvgdPkCz8=

+github.com/dlclark/regexp2 v1.12.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=

+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=

+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=

+github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=

+github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=

+golang.org/x/sync v0.14.0 h1:woo0S4Yywslg6hp4eUFjTVOyKt0RookbpAHG4c1HmhQ=

+golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=

+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=

+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=

+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

+Config (per-repo, cgit-style, matching the existing pattern): git --git-dir=/srv/git/foo.git config gsg.gpgkeyring /path/to/keys.asc, where the file is one or more ASCII-armored public keys.

+

+How it works:

+- At startup, if a repo has gsg.gpgkeyring set, Repo.UseKeyring builds an isolated GNUPGHOME (under /tmp, not os.TempDir() — macOS's longer default temp path pushes gpg-agent's Unix socket past its ~104-byte limit and silently breaks) and imports only that file's keys into it.

+- On import failure, it logs a warning and disables verification for that repo rather than failing the whole server.

+- Repo.Log (used by the log module, n=20) now optionally asks git for %G? %GS %GK per commit — gated on both the caller wanting it and the repo actually having a keyring, so no wasted gpg forks. LogAll (the unbounded graph walk) deliberately never requests it — verifying every signed commit across full history would risk blowing the per-request timeout.

+- A commit is "verified" if %G? is G or U — a signature valid against an imported key gets U, not G, since a bare keyring has no ownertrust database. Trust here comes from the operator putting the key in the file, not GPG's web-of-trust.

+- Signed-but-unknown-key commits (%G? = E, the common case on a partial keyring) render as a neutral "unknown key" badge, not a red failure — confirmed this distinction empirically since it's easy to get backwards.

+

+UI: log.html gains a "Signature" column, shown only when the repo has verification configured. Green verified / neutral unknown key / red bad signature (and expired/revoked variants) / dash for unsigned.

+

+Tested end-to-end against real signed/unsigned/foreign-key commits across three repo configs (verified, plain, bad-keyring-path), including the misconfiguration path.

+// Package access holds the rules that decide who may see or share a

+// repository. It deliberately imports nothing from core: the visibility

+// rule is used by the 404 gate, the index module, share-link minting, and

+// share-link redemption, and putting it in one dependency-free place is

+// what keeps those four from drifting apart.

+package access

+

+import (

+ "strings"

+ "time"

+)

+

+// Policy is the authorization-relevant subset of a repository's config.

+// core.RepoInfo is the full config; Policy is what the rules below need.

+type Policy struct {

+ Slug string

+ Hidden bool

+ VisibleTo []string

+ ShareRevokedAfter time.Time

+}

+

+// Identity is the verified caller. SharedSlugs/SharedIssuedAt come from a

+// valid gsg_share cookie and are empty when the caller has no share grant.

+type Identity struct {

+ User string

+ SharedSlugs []string

+ SharedIssuedAt time.Time

+}

+

+// CanView reports whether id may see the repository at all. Public repos

+// are visible to everyone; a hidden repo is visible to an owner named in

+// gsg.visible-to or to an unrevoked share grant.

+func (p Policy) CanView(id Identity) bool {

+ if !p.Hidden {

+ return true

+ }

+ return p.canViewAsOwner(id.User) ||

+ (p.coversShare(id.SharedSlugs) && ShareLive(p.ShareRevokedAfter, id.SharedIssuedAt))

+}

+

+// CanShare reports whether user may mint a share link for this repository.

+// Only hidden repos are shareable (sharing a public repo would grant

+// nothing new), and only an owner may mint -- a share grant cannot be

+// amplified into a broader grant.

+func (p Policy) CanShare(user string) bool {

+ return p.Hidden && p.canViewAsOwner(user)

+}

+

+// canViewAsOwner matches gsg.visible-to case-insensitively. Anonymous

+// callers never match: "" would otherwise vacuous-match a blank entry.

+func (p Policy) canViewAsOwner(user string) bool {

+ if user == "" {

+ return false

+ }

+ for _, u := range p.VisibleTo {

+ if strings.EqualFold(u, user) {

+ return true

+ }

+ }

+ return false

+}

+

+func (p Policy) coversShare(slugs []string) bool {

+ for _, s := range slugs {

+ if s == p.Slug {

+ return true

+ }

+ }

+ return false

+}

+

+// ShareLive reports whether a grant issued at issuedAt survives a

+// repository's gsg.share-revoked-after value. A zero revokedAfter means no

+// revocation; a grant issued at or before the timestamp is revoked, which

+// is why the comparison is strict -- the operator's intent is "everything

+// issued before this moment is dead", and the two sides are second-granular.

+//

+// The free function is for callers (share redemption) that only have the

+// timestamp, not a full Policy.

+func ShareLive(revokedAfter, issuedAt time.Time) bool {

+ return revokedAfter.IsZero() || issuedAt.After(revokedAfter)

+}

+package access

+

+import (

+ "testing"

+ "time"

+)

+

+func TestCanView(t *testing.T) {

+ revoked := time.Unix(1_700_000_000, 0)

+ granted := revoked.Add(time.Minute)

+

+ cases := []struct {

+ name string

+ p Policy

+ id Identity

+ want bool

+ }{

+ {

+ name: "public repo",

+ p: Policy{Slug: "demo"},

+ want: true,

+ },

+ {

+ name: "hidden anonymous",

+ p: Policy{Slug: "demo", Hidden: true},

+ want: false,

+ },

+ {

+ name: "hidden owner",

+ p: Policy{Slug: "demo", Hidden: true, VisibleTo: []string{"Alice"}},

+ id: Identity{User: "alice"},

+ want: true,

+ },

+ {

+ name: "hidden non-owner",

+ p: Policy{Slug: "demo", Hidden: true, VisibleTo: []string{"alice"}},

+ id: Identity{User: "bob"},

+ want: false,

+ },

+ {

+ name: "hidden share grant",

+ p: Policy{Slug: "demo", Hidden: true},

+ id: Identity{SharedSlugs: []string{"demo"}, SharedIssuedAt: granted},

+ want: true,

+ },

+ {

+ name: "share grant for another repo",

+ p: Policy{Slug: "demo", Hidden: true},

+ id: Identity{SharedSlugs: []string{"other"}, SharedIssuedAt: granted},

+ want: false,

+ },

+ {

+ name: "share grant before revocation",

+ p: Policy{Slug: "demo", Hidden: true, ShareRevokedAfter: revoked},

+ id: Identity{SharedSlugs: []string{"demo"}, SharedIssuedAt: revoked},

+ want: false,

+ },

+ {

+ name: "share grant after revocation",

+ p: Policy{Slug: "demo", Hidden: true, ShareRevokedAfter: revoked},

+ id: Identity{SharedSlugs: []string{"demo"}, SharedIssuedAt: granted},

+ want: true,

+ },

+ }

+

+ for _, tc := range cases {

+ t.Run(tc.name, func(t *testing.T) {

+ if got := tc.p.CanView(tc.id); got != tc.want {

+ t.Fatalf("CanView() = %v, want %v", got, tc.want)

+ }

+ })

+ }

+}

+

+func TestCanShare(t *testing.T) {

+ p := Policy{Slug: "demo", Hidden: true, VisibleTo: []string{"alice"}}

+

+ if !p.CanShare("alice") {

+ t.Fatal("owner should be able to share a hidden repo")

+ }

+ if p.CanShare("bob") {

+ t.Fatal("non-owner should not be able to share")

+ }

+ if p.CanShare("") {

+ t.Fatal("anonymous should not be able to share")

+ }

+ if (Policy{Slug: "public", VisibleTo: []string{"alice"}}).CanShare("alice") {

+ t.Fatal("public repo should not be shareable")

+ }

+}

+

+func TestShareLive(t *testing.T) {

+ revoked := time.Unix(1_700_000_000, 0)

+

+ if !ShareLive(time.Time{}, revoked) {

+ t.Fatal("zero revokedAfter should not revoke")

+ }

+ if ShareLive(revoked, revoked) {

+ t.Fatal("grant issued at the revocation time should be revoked")

+ }

+ if ShareLive(revoked, revoked.Add(-time.Second)) {

+ t.Fatal("grant issued before revocation should be revoked")

+ }

+ if !ShareLive(revoked, revoked.Add(time.Second)) {

+ t.Fatal("grant issued after revocation should survive")

+ }

+}

+// Package authn owns gsg's browser session endpoints. Login trusts the

+// identity header that the reverse proxy sets after forward_auth; logout

+// only clears gsg's own cookie. Keeping both here means main.go composes

+// listeners rather than implementing authentication.

+//

+// The two handlers are returned separately on purpose: login must only ever

+// be mounted on the admin listener, while logout belongs on the public one.

+// A single combined handler would make that distinction a calling

+// convention instead of a structural one.

+package authn

+

+import (

+ "fmt"

+ "net/http"

+ "net/url"

+ "strings"

+

+ "gsg/internal/session"

+)

+

+// Config is the small amount of state the session endpoints need.

+type Config struct {

+ Sessions *session.Manager

+ UserHeader string // e.g. "X-Authentik-Username"; defaults to that

+}

+

+// Handlers are mounted individually by the caller.

+type Handlers struct {

+ Login http.Handler

+ Logout http.Handler

+}

+

+// NewHandlers builds the login and logout endpoints.

+func NewHandlers(cfg Config) (Handlers, error) {

+ if cfg.Sessions == nil {

+ return Handlers{}, fmt.Errorf("authn: no session manager")

+ }

+ if cfg.UserHeader == "" {

+ cfg.UserHeader = "X-Authentik-Username"

+ }

+ return Handlers{

+ Login: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { login(cfg, w, r) }),

+ Logout: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { logout(cfg, w, r) }),

+ }, nil

+}

+

+// login mints a session from the proxy-supplied identity. Reaching this

+// handler at all is the authorization decision: the admin listener is the

+// only place it is mounted, and Caddy's forward_auth runs before it.

+func login(cfg Config, w http.ResponseWriter, r *http.Request) {

+ user := r.Header.Get(cfg.UserHeader)

+ if user == "" {

+ http.Error(w, "missing identity header", http.StatusUnauthorized)

+ return

+ }

+ http.SetCookie(w, cfg.Sessions.Issue(user))

+ http.Redirect(w, r, safeNext(r.URL.Query().Get("next")), http.StatusSeeOther)

+}

+

+// logout needs no round trip through the identity provider; it only clears

+// the cookie this process issued.

+func logout(cfg Config, w http.ResponseWriter, r *http.Request) {

+ http.SetCookie(w, cfg.Sessions.Clear())

+ http.Redirect(w, r, "/", http.StatusSeeOther)

+}

+

+// safeNext returns next if it is a same-site relative path, else "/". next

+// comes from a query parameter on a login redirect; without this check it

+// would be an open redirect (?next=https://evil.example) off a trusted

+// domain, right after proving who the user is.

+func safeNext(next string) string {

+ if next == "" || !strings.HasPrefix(next, "/") || strings.HasPrefix(next, "//") {

+ return "/"

+ }

+ if u, err := url.Parse(next); err != nil || u.Scheme != "" || u.Host != "" {

+ return "/"

+ }

+ return next

+}

+package authn

+

+import (

+ "net/http"

+ "net/http/httptest"

+ "testing"

+

+ "gsg/internal/session"

+)

+

+func TestSafeNext(t *testing.T) {

+ cases := []struct {

+ in, want string

+ }{

+ {"", "/"},

+ {"/", "/"},

+ {"/demo/", "/demo/"},

+ {"/share/new?x=1", "/share/new?x=1"},

+ {"//evil.example", "/"},

+ {"https://evil.example", "/"},

+ {"http://evil.example/path", "/"},

+ {"relative", "/"},

+ }

+ for _, tc := range cases {

+ if got := safeNext(tc.in); got != tc.want {

+ t.Errorf("safeNext(%q) = %q, want %q", tc.in, got, tc.want)

+ }

+ }

+}

+

+func TestLoginRequiresIdentityHeader(t *testing.T) {

+ h := testHandlers(t)

+ req := httptest.NewRequest("GET", "/auth/login", nil)

+ rec := httptest.NewRecorder()

+ h.Login.ServeHTTP(rec, req)

+

+ if rec.Code != http.StatusUnauthorized {

+ t.Fatalf("status = %d, want %d", rec.Code, http.StatusUnauthorized)

+ }

+ if cookies := rec.Result().Cookies(); len(cookies) != 0 {

+ t.Fatalf("unauthenticated login set cookies: %v", cookies)

+ }

+}

+

+func TestLoginIssuesCookieAndHonorsSafeNext(t *testing.T) {

+ h := testHandlers(t)

+ req := httptest.NewRequest("GET", "/auth/login?next=/demo/", nil)

+ req.Header.Set("X-Authentik-Username", "alice")

+ rec := httptest.NewRecorder()

+ h.Login.ServeHTTP(rec, req)

+

+ if rec.Code != http.StatusSeeOther {

+ t.Fatalf("status = %d, want %d", rec.Code, http.StatusSeeOther)

+ }

+ if got := rec.Header().Get("Location"); got != "/demo/" {

+ t.Fatalf("Location = %q, want /demo/", got)

+ }

+ cookies := rec.Result().Cookies()

+ if len(cookies) != 1 || cookies[0].Name != session.CookieName {

+ t.Fatalf("cookies = %v, want one %s cookie", cookies, session.CookieName)

+ }

+}

+

+func TestLoginRejectsOffsiteNext(t *testing.T) {

+ h := testHandlers(t)

+ req := httptest.NewRequest("GET", "/auth/login?next=https://evil.example/", nil)

+ req.Header.Set("X-Authentik-Username", "alice")

+ rec := httptest.NewRecorder()

+ h.Login.ServeHTTP(rec, req)

+

+ if got := rec.Header().Get("Location"); got != "/" {

+ t.Fatalf("Location = %q, want /", got)

+ }

+}

+

+func TestLogoutClearsCookie(t *testing.T) {

+ h := testHandlers(t)

+ req := httptest.NewRequest("GET", "/auth/logout", nil)

+ rec := httptest.NewRecorder()

+ h.Logout.ServeHTTP(rec, req)

+

+ if rec.Code != http.StatusSeeOther {

+ t.Fatalf("status = %d, want %d", rec.Code, http.StatusSeeOther)

+ }

+ if got := rec.Header().Get("Location"); got != "/" {

+ t.Fatalf("Location = %q, want /", got)

+ }

+ cookies := rec.Result().Cookies()

+ if len(cookies) != 1 || cookies[0].Name != session.CookieName {

+ t.Fatalf("cookies = %v, want one %s cookie", cookies, session.CookieName)

+ }

+ if cookies[0].MaxAge >= 0 {

+ t.Fatalf("logout cookie MaxAge = %d, want negative", cookies[0].MaxAge)

+ }

+}

+

+func testHandlers(t *testing.T) Handlers {

+ t.Helper()

+ h, err := NewHandlers(Config{Sessions: session.NewManager()})

+ if err != nil {

+ t.Fatalf("NewHandlers: %v", err)

+ }

+ return h

+}

+ "strconv"

+ "sync/atomic"

+ "time"

+ "gsg/internal/access"

+ // RevFn, when set, returns a token that changes whenever site-level

+ // configuration changes without a commit moving -- operator notices,

+ // for example. Ctx.contentIdentity() folds it into both the module

+ // cache key and the response ETag, so a module reading that config

+ // cannot serve a result that predates the change. Set once at startup,

+ // before the server begins serving.

+ RevFn func() string

+

+ idx atomic.Pointer[repoIndex]

+ mu sync.Mutex // serializes upsert/remove; RepoList/Lookup never block

+

+ // configRev counts every upsert/remove, i.e. every time a repo's own

+ // git config or existence changes (watch.go's reconcile calls mutate

+ // for exactly this). Folded into Revision() so that ETags and the

+ // module cache invalidate when a repo's config changes -- gsg.hide,

+ // gsg.visible-to, gsg.share-revoked-after -- not just when notices do.

+ // Without this, a browser could revalidate a stale, cached page whose

+ // ETag predates a config change that was supposed to take effect

+ // immediately, such as a share-link revocation.

+ configRev atomic.Uint64

+}

+

+// repoIndex is an immutable snapshot, swapped in whole by upsert/remove so

+// readers (RepoList, Lookup) never need a lock.

+type repoIndex struct {

+ list []Handle // every known repo, hidden or not -- repos.go filters Hidden itself

+ bySlug map[string]Handle // every known repo, hidden or not -- Server.buildCtx enforces visibility

+}

+

+// RepoList is every discovered repository. Site-scoped routes (the index

+// page, the index endpoint) read it through the `repos` module.

+func (s *Site) RepoList() []Handle {

+ if idx := s.idx.Load(); idx != nil {

+ return idx.list

+ }

+ return nil

+}

+

+// Lookup resolves a repo by slug for per-repo routes, hidden or not -- the

+// caller (Server.buildCtx) is responsible for enforcing the access policy

+// before using the result.

+func (s *Site) Lookup(slug string) (Handle, bool) {

+ idx := s.idx.Load()

+ if idx == nil {

+ return Handle{}, false

+ }

+ h, ok := idx.bySlug[slug]

+ return h, ok

+}

+

+// Revision is the site-level analogue of RepoInfo.GPGKeyring: a token for

+// inputs that change outside a commit -- notices, and any repo's own git

+// config (gsg.hide, gsg.visible-to, gsg.share-revoked-after, ...). Nil-safe

+// because tests construct bare *Ctx values and LoadTemplates parses with

+// &Ctx{}.

+func (s *Site) Revision() string {

+ if s == nil {

+ return ""

+ }

+ rev := strconv.FormatUint(s.configRev.Load(), 10)

+ if s.RevFn != nil {

+ rev += "|" + s.RevFn()

+ }

+ return rev

+}

+

+// upsert and remove are the only writers of the repo index, both called

+// exclusively from watch.go's reconcile -- at startup and at runtime alike,

+// through the same code path.

+func (s *Site) upsert(h Handle) {

+ s.mutate(func(list []Handle) []Handle {

+ for i, e := range list {

+ if e.Info.Slug == h.Info.Slug {

+ list[i] = h

+ return list

+ }

+ }

+ return append(list, h)

+ })

+}

+

+func (s *Site) remove(slug string) {

+ s.mutate(func(list []Handle) []Handle {

+ for i, e := range list {

+ if e.Info.Slug == slug {

+ return append(list[:i], list[i+1:]...)

+ }

+ }

+ return list

+ })

+}

+

+func (s *Site) mutate(f func([]Handle) []Handle) {

+ s.mu.Lock()

+ defer s.mu.Unlock()

+

+ var cur []Handle

+ if idx := s.idx.Load(); idx != nil {

+ cur = append([]Handle(nil), idx.list...)

+ }

+ next := f(cur)

+

+ bySlug := make(map[string]Handle, len(next))

+ for _, h := range next {

+ bySlug[h.Info.Slug] = h

+ }

+ s.idx.Store(&repoIndex{list: next, bySlug: bySlug})

+ s.configRev.Add(1)

+// gpgkeyring = /path/to/keys.asc

+// visible-to = alice,bob

+// cache-max-age = 2m

+

+ // VisibleTo is the gsg.visible-to allowlist: usernames (matched against

+ // an authenticated session, case-insensitively) who may see this repo

+ // even though Hidden is set. A separate key from Owner deliberately --

+ // Owner is a free-text display field (and falls back to gitweb.owner

+ // for cgit-migrated repos), so reusing it as an ACL could silently

+ // grant access nobody intended.

+ VisibleTo []string

+

+ // ShareMaxAge is gsg.share-max-age: both the ceiling no share-link

+ // expiry for this repo may exceed, and the default when a mint request

+ // doesn't specify one. Falls back to defaultShareMaxAge when unset.

+ ShareMaxAge time.Duration

+

+ // ShareRevokedAfter is gsg.share-revoked-after: any share-link grant

+ // for this repo issued at or before this instant is rejected,

+ // regardless of the link's own expiry. It is the only revocation lever

+ // a stateless share token has -- see internal/share.

+ ShareRevokedAfter time.Time

+

+ // GPGKeyring is the configured path to a file of armored public keys

+ // (gsg.gpgkeyring), if any. Reading it here is just config; the actual

+ // import into an isolated keyring happens once at startup (see

+ // gitx.Repo.UseKeyring) and, on failure, this is cleared again so

+ // templates don't advertise a verification column that isn't backed

+ // by anything.

+ GPGKeyring string

+

+ // CacheMaxAge is gsg.cache-max-age: how long an anonymous (no session,

+ // no share grant) response for this repo may be reused -- both by the

+ // requesting browser (Cache-Control: public, max-age=...) and by gsg's

+ // own in-memory response cache (Server.respCache) -- before either has

+ // to ask again. Falls back to defaultAnonCacheMaxAge when unset.

+ CacheMaxAge time.Duration

+ Slug: r.Slug,

+ Title: title,

+ Description: desc,

+ Owner: r.ConfigFirst("gsg.owner", "gitweb.owner"),

+ Clone: r.ConfigFirst("gsg.clone", "gitweb.url"),

+ Section: r.ConfigFirst("gsg.section", "gitweb.category"),

+ Hidden: strings.EqualFold(r.Config("gsg.hide"), "true"),

+ VisibleTo: splitUsers(r.Config("gsg.visible-to")),

+ ShareMaxAge: parseShareMaxAge(r.Config("gsg.share-max-age")),

+ ShareRevokedAfter: parseUnixTime(r.Config("gsg.share-revoked-after")),

+ GPGKeyring: r.Config("gsg.gpgkeyring"),

+ CacheMaxAge: parseCacheMaxAge(r.Config("gsg.cache-max-age")),

+ }

+}

+

+// defaultShareMaxAge is the ceiling/default applied when a repo doesn't set

+// gsg.share-max-age.

+const defaultShareMaxAge = 30 * 24 * time.Hour

+

+func parseShareMaxAge(v string) time.Duration {

+ if v == "" {

+ return defaultShareMaxAge

+ }

+ d, err := time.ParseDuration(v)

+ if err != nil || d <= 0 {

+ return defaultShareMaxAge

+ }

+ return d

+}

+

+// defaultAnonCacheMaxAge is the ceiling/default applied when a repo doesn't

+// set gsg.cache-max-age.

+const defaultAnonCacheMaxAge = 2 * time.Minute

+

+func parseCacheMaxAge(v string) time.Duration {

+ if v == "" {

+ return defaultAnonCacheMaxAge

+ }

+ d, err := time.ParseDuration(v)

+ if err != nil || d <= 0 {

+ return defaultAnonCacheMaxAge

+ }

+ return d

+}

+

+func parseUnixTime(v string) time.Time {

+ if v == "" {

+ return time.Time{}

+ }

+ sec, err := strconv.ParseInt(v, 10, 64)

+ if err != nil {

+ return time.Time{}

+ }

+ return time.Unix(sec, 0)

+}

+

+// splitUsers parses a comma-separated gsg.visible-to value into trimmed,

+// non-empty usernames.

+func splitUsers(v string) []string {

+ if v == "" {

+ return nil

+ }

+ parts := strings.Split(v, ",")

+ out := make([]string, 0, len(parts))

+ for _, p := range parts {

+ if p = strings.TrimSpace(p); p != "" {

+ out = append(out, p)

+ }

+ }

+ return out

+}

+

+// AccessPolicy is the authorization-relevant subset of RepoInfo. The rules

+// themselves live in internal/access so core, modules, share minting and

+// share redemption cannot drift into slightly different answers.

+func (info RepoInfo) AccessPolicy() access.Policy {

+ return access.Policy{

+ Slug: info.Slug,

+ Hidden: info.Hidden,

+ VisibleTo: info.VisibleTo,

+ ShareRevokedAfter: info.ShareRevokedAfter,

+ // User is the authenticated username from the gsg_user session cookie,

+ // or "" for an anonymous request. Resolved once in Server.buildCtx.

+ // Never derived from a request header directly -- see internal/session.

+ User string

+

+ // SharedSlugs and SharedIssuedAt come from a verified gsg_share cookie,

+ // if one was present (SharedSlugs is nil otherwise). They are not yet

+ // filtered for revocation -- access.Policy applies gsg.share-revoked-after

+ // against SharedIssuedAt at the point of use, since revocation is per-repo

+ // and this Ctx may span several.

+ SharedSlugs []string

+ SharedIssuedAt time.Time

+

+ // Nav is the repo-scoped tab bar, built once in Server.serve from the

+ // route table (see nav.go). Empty for site-scoped routes.

+ Nav []NavItem

+

+ // Immutable is true when this response is served with the year-long

+ // immutable cache policy (see Server.serve). Page chrome that can change

+ // without the commit moving must not be rendered into it, because the

+ // browser is told never to revalidate. Operator notices are the first

+ // such thing; this is deliberately the *computed* condition, not just

+ // Route.Immutable, so it follows whatever the caching rule becomes.

+ Immutable bool

+

+ // StaticTag is Server.StaticTag, threaded through so the `static`

+ // template func can build cache-busting asset URLs without a package

+ // import cycle back to Server.

+ StaticTag string

+

+// contentIdentity captures every input that can change what a route

+// renders at a fixed commit -- the commit itself, plus anything that can

+// change without the commit moving. Vars are part of it: /compare/a..b and

+// /compare/a...b resolve to the same head commit, so without the base ref

+// in here the second request was served the first one's diff. GPGKeyring

+// is part of it for the same reason: watch.go's reconcile can change a

+// repo's keyring under commits whose SHAs haven't moved, and a page

+// fetched before that would otherwise cache "unsigned" forever.

+// Site.Revision() is the site-level equivalent of the keyring: operator

+// notices change without a commit moving, so a page cached before a notice

+// edit would otherwise keep serving the old banners forever.

+// CacheKey and the response ETag (server.go) are both built from this, so

+// a new Var or a keyring change can't invalidate one without invalidating

+// the other -- that used to be two hand-maintained lists that had already

+// drifted (the ETag was missing GPGKeyring and any Var besides baseSHA).

+func (c *Ctx) contentIdentity() string {

+ var b strings.Builder

+ b.WriteString(c.Commit + "|" + c.Info.GPGKeyring + "|" + c.Site.Revision())

+// CacheKey identifies an immutable module result. Empty when the result

+// cannot be cached (no resolved commit).

+func (c *Ctx) CacheKey(name string, args []string) string {

+ if c.Commit == "" || c.Store == nil {

+ return ""

+ }

+ return c.Info.Slug + "|" + c.Path + "|" + name + "|" +

+ strings.Join(args, "\x00") + "|" + c.contentIdentity()

+}

+

+ n.User = c.User

+ n.SharedSlugs = c.SharedSlugs

+ n.SharedIssuedAt = c.SharedIssuedAt

+// cacheMaxAge is how long an anonymous response for this repo may be

+// reused before revalidating. Server.buildResponseHead (the browser-facing

+// Cache-Control header) and Server.fillResponse (the server-side response

+// cache's own TTL) both read this, so the two never disagree about

+// staleness.

+func (c *Ctx) cacheMaxAge() time.Duration {

+ if c.Info.CacheMaxAge > 0 {

+ return c.Info.CacheMaxAge

+ }

+ return defaultAnonCacheMaxAge

+}

+

+package core

+

+import (

+ "strings"

+ "testing"

+)

+

+// The site revision is the site-level analogue of RepoInfo.GPGKeyring: it

+// must be part of contentIdentity or a notice change cannot invalidate the

+// module cache or the response ETag.

+func TestContentIdentityIncludesSiteRevision(t *testing.T) {

+ a := NewCtx(&Site{RevFn: func() string { return "rev-a" }}, nil, RepoInfo{}, "main")

+ b := NewCtx(&Site{RevFn: func() string { return "rev-b" }}, nil, RepoInfo{}, "main")

+ a.Commit, b.Commit = "sha", "sha"

+ if a.contentIdentity() == b.contentIdentity() {

+ t.Fatal("site revision is not part of contentIdentity")

+ }

+}

+

+// Tests construct bare *Ctx values (see blob_test.go) and LoadTemplates

+// parses with &Ctx{}; contentIdentity must tolerate a nil Site.

+func TestContentIdentityNilSite(t *testing.T) {

+ got := (&Ctx{}).contentIdentity()

+ if !strings.HasPrefix(got, "|") {

+ t.Fatalf("contentIdentity() = %q", got)

+ }

+}

+package core

+

+import (

+ "bytes"

+ "fmt"

+ "html/template"

+ "net/http"

+)

+

+// errorTmpl is compiled from a literal, not from the theme's template

+// files -- a broken view template is exactly the situation this page has

+// to survive, so it cannot depend on LoadTemplates succeeding.

+var errorTmpl = template.Must(template.New("error").Parse(`<!doctype html>

+<html lang="en">

+<head>

+<meta charset="utf-8">

+<meta name="viewport" content="width=device-width, initial-scale=1">

+<title>{{.Code}} {{.Status}} &middot; {{.Site}}</title>

+<link rel="stylesheet" href="/static/css/base.css">

+</head>

+<body>

+<main class="wrap error-page">

+ <p class="error-code">{{.Code}}</p>

+ <h1 class="page-title">{{.Status}}</h1>

+ <p class="page-subtitle">{{.Message}}</p>

+ <p><a href="/">&larr; back to {{.Site}}</a></p>

+</main>

+</body>

+</html>

+`))

+

+// renderErrorPage never returns an error: if the template somehow fails to

+// execute, it falls back to a plain-text body rather than propagating.

+func renderErrorPage(code int, site string) (body []byte, contentType string) {

+ data := struct {

+ Code int

+ Status, Message, Site string

+ }{

+ Code: code,

+ Status: http.StatusText(code),

+ Message: friendlyMessage(code),

+ Site: site,

+ }

+ var buf bytes.Buffer

+ if err := errorTmpl.Execute(&buf, data); err != nil {

+ return []byte(fmt.Sprintf("%d %s\n", code, http.StatusText(code))), "text/plain; charset=utf-8"

+ }

+ return buf.Bytes(), "text/html; charset=utf-8"

+}

+

+// friendlyMessage keeps the diagnostic detail out of the response body --

+// that stays in the server log -- while still telling a human what class

+// of problem they hit.

+func friendlyMessage(code int) string {

+ switch code {

+ case http.StatusNotFound:

+ return "We couldn't find that repository, ref, or path."

+ case http.StatusBadRequest:

+ return "That request doesn't look right."

+ case http.StatusRequestEntityTooLarge:

+ return "That response is too large to display in full."

+ default:

+ return "Something went wrong rendering this page. The details were logged."

+ }

+}

+ // static builds a cache-busting asset URL, e.g. "css/base.css" ->

+ // "/static/css/base.css?v=<tag>". The `v` param is what lets

+ // main.go's static handler hand out a year-long immutable

+ // Cache-Control instead of a short one -- a URL without it is

+ // still served, just not frozen for a year.

+ "static": func(p string) string {

+ return "/static/" + p + "?v=" + c.StaticTag

+ },

+ return s[:n] + "…"

+package core

+

+import "strings"

+

+// NavItem is one entry in the repo-scoped navigation -- the top tab bar

+// and the page-nav chips both render the same slice, built from the route

+// table so a new tab is a one-line addition to site/routes.go, not a

+// second place to remember.

+type NavItem struct {

+ Label string

+ Href string

+ Active bool

+}

+

+// BuildNav derives the repo-scoped nav from every route whose NavLabel is

+// set, in route-table order. current is the name of the route being

+// served, used to mark the matching tab active.

+func BuildNav(routes []Route, current, slug, ref string) []NavItem {

+ if slug == "" {

+ return nil

+ }

+ var items []NavItem

+ for _, rt := range routes {

+ if rt.Scope != ScopeRepo || rt.NavLabel == "" {

+ continue

+ }

+ items = append(items, NavItem{

+ Label: rt.NavLabel,

+ Href: navHref(rt, slug, ref),

+ // The "repo" route (bare /{repo}/) renders tree.html at its

+ // root, same as "tree" does at path "" -- so the files tab

+ // lights up on both, even though "repo" carries no NavLabel

+ // of its own and never appears in this loop as a tab.

+ Active: rt.Name == current || (rt.Name == "tree" && current == "repo"),

+ })

+ }

+ return items

+}

+

+// navHref builds the href for a nav tab from its route pattern: the fixed

+// segment right after {repo}, plus the ref if the route is ref-addressed

+// ({rest...} or {rev}). Routes addressed only by {$} (graph, refs) link to

+// their bare index instead.

+func navHref(rt Route, slug, ref string) string {

+ seg := navSegment(rt.Pattern)

+ href := "/" + slug + "/"

+ if seg != "" {

+ href += seg + "/"

+ }

+ if strings.Contains(rt.Pattern, "{rest...}") || strings.Contains(rt.Pattern, "{rev}") {

+ href += ref

+ }

+ return href

+}

+

+// navSegment extracts the literal path element between {repo} and the

+// next wildcard, e.g. "GET /{repo}/tree/{rest...}" -> "tree". Returns ""

+// for patterns with no such segment (e.g. "GET /{repo}/{$}").

+func navSegment(pattern string) string {

+ p := pattern

+ if i := strings.IndexByte(p, ' '); i >= 0 {

+ p = p[i+1:]

+ }

+ p = strings.TrimPrefix(p, "/{repo}/")

+ seg, _, _ := strings.Cut(p, "/")

+ if strings.HasPrefix(seg, "{") {

+ return ""

+ }

+ return seg

+}

+ // CacheableAnon opts a route into Server's in-memory response cache for

+ // anonymous, shareless requests (see Server.cacheEligible) -- a full

+ // rendered response is stored and replayed to the next matching

+ // request within Ctx.cacheMaxAge, without touching git at all. Reserved

+ // for the small-HTML page routes most likely to be a spike's hot page;

+ // left off routes whose bodies can be large or unboundedly numerous

+ // (blob, raw, compare -- see routes.go) and the JSON api-* endpoints,

+ // to keep this pass's scope and memory footprint bounded: respCache is

+ // an LRU bounded by entry count, not bytes.

+ CacheableAnon bool

+ // NavLabel, when set on a ScopeRepo route, adds a tab for it to the

+ // repo-scoped navigation (see nav.go) -- the top tab bar and the

+ // page-nav chips both derive from this instead of hardcoding links.

+ NavLabel string

+

+ // Request, when set, parses this route's path parameters. A nil parser

+ // uses the default {rest...}/{rev} handling. Parsers only split path

+ // text into ref candidates: core still calls gitx.Repo.Resolve, so user

+ // input never reaches git as raw ref syntax (see AGENTS invariant 1).

+ Request RequestFunc

+

+ // PageSize, when greater than zero, enables ?ofs= pagination at that

+ // page size and folds the normalized offset into Ctx.Vars["ofs"].

+ PageSize int

+// Request is the path-derived input a route hands back to core before any

+// ref is resolved. Ref is the head commit; Range is set only for routes

+// that compare two commits.

+type Request struct {

+ Ref string

+ Path string

+ Range *Range

+}

+

+// Range describes a base..head request. Ref on Request carries head.

+type Range struct {

+ Base string

+ ThreeDot bool

+}

+

+// RequestFunc parses route-specific path parameters. It must not invoke

+// git or resolve refs itself.

+type RequestFunc func(*http.Request) (Request, error)

+

+// Page sizes for routes that paginate via ?ofs=. Kept in core (not

+// modules) so buildCtx can quantize an incoming ofs to a real page

+// boundary without an import cycle. Routes declare the matching PageSize,

+// and it must match the literal arg the log.html/graph.html template passes

+// to `mod "log"`/`mod "graph"`.

+const (

+ LogPageSize = 20

+ GraphPageSize = 150

+)

+

+// text/plain or octet-stream for everything the module did not validate,

+// nosniff so the browser does not second-guess that, and a sandbox CSP as a

+// backstop. The one exception is InlineContentTyper: a module that has

+// checked the bytes may name a raster image type, which cannot execute and

+// is still covered by nosniff.

+ // A module may declare a validated inline MIME (raster images). It is

+ // checked before IsBinary so an image is served as image/*, not

+ // octet-stream; only modules that vetted the bytes may return one, and

+ // the nosniff above keeps the declared type from being second-guessed.

+ if ct, ok := v.(InlineContentTyper); ok {

+ if s := ct.InlineContentType(); s != "" {

+ h.Set("Content-Type", s)

+ return

+ }

+ }

+

+// InlineContentTyper lets a raw-serving module declare a MIME type that is

+// safe to render inline on this origin. It exists so core stays ignorant of

+// formats: the module that knows how to validate image bytes is the module

+// that names the type. An empty return keeps the text/plain or

+// octet-stream-attachment default.

+type InlineContentTyper interface {

+ InlineContentType() string

+}

+ "context"

+ "strconv"

+ "gsg/internal/access"

+ "gsg/internal/session"

+

+ "golang.org/x/sync/singleflight"

+ // Sessions verifies the gsg_user login cookie. Nil-safe: an unset

+ // Sessions makes every request resolve as anonymous, i.e. today's

+ // behavior.

+ Sessions *session.Manager

+

+ // iteration without a restart; leave empty in production. Also disables

+ // the response cache below, so a live-edited template is never masked

+ // by a stale cached response.

+ // StaticTag is a content hash of the embedded static assets (set once

+ // at startup in main.go via HashFS), threaded onto every Ctx so the

+ // `static` template func can build cache-busting asset URLs.

+ StaticTag string

+

+

+ // respCache holds full rendered responses for CacheableAnon routes,

+ // keyed on the request (route+path+query, see cacheEligible) rather

+ // than content identity. sf collapses every request that arrives while

+ // a key is cold into one fill instead of one per request -- the thing

+ // that actually matters during a traffic spike is many distinct

+ // anonymous visitors hitting the same hot page, not just requests that

+ // happen to land in the same instant.

+ respCache *LRU

+ sf singleflight.Group

+ Log: slog.Default(),

+ Timeout: 10 * time.Second,

+ MaxGit: 16 << 20, // headroom above modules.maxPreviewSize (10 MiB)

+ cache: NewLRU(cacheSize),

+ respCache: NewLRU(cacheSize),

+ tag, err := HashFS(fsys)

+// HashFS digests every file in fsys, path and contents both, into a short

+// stable tag. Used for the template set (so editing the theme invalidates

+// every ETag at once -- without this a restyled page keeps serving 304s)

+// and, via main.go, for the embedded static assets, so a CSS/JS edit mints

+// a new cache-busting URL instead of being masked by a year-long immutable

+// Cache-Control.

+func HashFS(fsys fs.FS) (string, error) {

+// cachedResponse is a full rendered response, header and body both, as

+// stored in respCache. expiresAt is only meaningful for entries actually

+// stored there.

+type cachedResponse struct {

+ header http.Header

+ body []byte

+ expiresAt time.Time

+}

+

+ if key, ok := s.cacheEligible(rt, r); ok {

+ if cr, ok := s.respCacheGet(key); ok {

+ writeResponse(w, r, cr)

+ return

+ }

+ // singleflight collapses every request that arrives while this key

+ // is cold into one fill. That fill runs on a context detached from

+ // whichever request happened to trigger it: without that, the

+ // first caller to disconnect or time out would kill the shared

+ // git/render work and fail every other request that coalesced onto

+ // it too, even ones with their own deadline still well in the

+ // future. Bounded by s.Timeout so a genuinely stuck fill still

+ // gets reaped.

+ //

+ // The closure below captures r, the *triggering* (leader) request

+ // -- every follower that coalesces onto this Do gets a response

+ // built from the leader's request, not their own. That's only safe

+ // because cacheEligible already pinned every request-varying input

+ // that matters (user == "", no share cookie) and the key covers

+ // path+query, so leader and followers are asking an identical

+ // question. A future CacheableAnon route whose render depends on

+ // anything else request-specific (a header, say) would silently

+ // break this.

+ v, err, _ := s.sf.Do(key, func() (any, error) {

+ fillCtx, cancel := context.WithTimeout(context.Background(), s.Timeout)

+ defer cancel()

+ return s.fillResponse(reqCtx{fillCtx}, rt, r)

+ })

+ if err != nil {

+ s.fail(w, r, rt, err)

+ return

+ }

+ cr := v.(*cachedResponse)

+ s.respCache.Put(key, cr)

+ writeResponse(w, r, cr)

+ return

+ }

+

+ c, header, err := s.buildResponseHead(ctx, rt, r)

+ copyHeader(w.Header(), header)

+ if match := r.Header.Get("If-None-Match"); match != "" && strings.Contains(match, header.Get("ETag")) {

+ s.mu.RLock()

+ ts := s.templates

+ s.mu.RUnlock()

+// cacheEligible reports whether rt/r may be served from, and stored in,

+// the shared response cache, and if so, the key to use. Eligibility is

+// decided entirely from cheap, git-free signals -- cookies and

+// already-loaded repo config -- so a cache hit costs nothing beyond a map

+// lookup, and a miss doesn't cost anything extra either before falling

+// through to the real render.

+//

+// Two independent conditions gate it, deliberately redundant: the request

+// must carry neither a session nor a share cookie (the same

+// anonymous-and-shareless condition the Cache-Control split in

+// buildResponseHead already trusts), AND, for a repo-scoped route, that

+// repo must not be Hidden -- checked directly from RepoInfo, with no

+// reference to any cookie at all. A cache entry is shared state replayed

+// to whoever asks next, so a false negative here has a bigger blast

+// radius than a single mis-issued header would: the Hidden check means a

+// bug in cookie detection alone can never leak a hidden repo's content,

+// since that repo's responses are never eligible for the shared cache in

+// the first place.

+func (s *Server) cacheEligible(rt Route, r *http.Request) (string, bool) {

+ if !rt.CacheableAnon || s.TemplateDir != "" {

+ return "", false

+ }

+ if s.Sessions.Verify(r) != "" {

+ return "", false

+ }

+ if _, ok := s.Sessions.VerifyShareCookie(r); ok {

+ return "", false

+ }

+ if rt.Scope == ScopeRepo {

+ h, ok := s.Site.Lookup(r.PathValue("repo"))

+ if !ok || h.Info.Hidden {

+ return "", false

+ }

+ }

+ return rt.Name + "\x00" + r.URL.Path + "\x00" + r.URL.RawQuery, true

+}

+

+func (s *Server) respCacheGet(key string) (*cachedResponse, bool) {

+ v, ok := s.respCache.Get(key)

+ if !ok {

+ return nil, false

+ }

+ cr := v.(*cachedResponse)

+ if time.Now().After(cr.expiresAt) {

+ return nil, false

+ }

+ return cr, true

+}

+

+// fillResponse builds a full response for storage in respCache: header and

+// body both, since an entry has to be complete before anyone else can be

+// served from it.

+func (s *Server) fillResponse(ctx contexter, rt Route, r *http.Request) (*cachedResponse, error) {

+ c, header, err := s.buildResponseHead(ctx, rt, r)

+ if err != nil {

+ return nil, err

+ }

+ s.mu.RLock()

+ ts := s.templates

+ s.mu.RUnlock()

+ body, err := rt.Render.Render(c, ts)

+ if err != nil {

+ return nil, err

+ }

+ header.Set("Content-Type", rt.Render.ContentType())

+ if hs, ok := rt.Render.(HeaderSetter); ok {

+ hs.Headers(c, header)

+ }

+ return &cachedResponse{header: header, body: body, expiresAt: time.Now().Add(c.cacheMaxAge())}, nil

+}

+

+// buildResponseHead resolves the Ctx and computes the ETag/Cache-Control

+// header, without executing the template -- split out so a matching

+// If-None-Match can skip rendering the body entirely.

+//

+// ETag is derived from the resolved commit SHA and every other input that

+// can change what's rendered, not the response body, so a conditional

+// request costs one ref lookup instead of a render.

+func (s *Server) buildResponseHead(ctx contexter, rt Route, r *http.Request) (*Ctx, http.Header, error) {

+ c, err := s.buildCtx(ctx, rt, r)

+ if err != nil {

+ return nil, nil, err

+ }

+ c.Nav = BuildNav(s.Routes, rt.Name, c.Info.Slug, c.Ref)

+

+ s.mu.RLock()

+ tag := s.tmplTag

+ s.mu.RUnlock()

+

+ // contentIdentity carries the commit, keyring, and every Var (e.g.

+ // compare's base ref) -- the same fragment module results are keyed

+ // on, so this can't drift out of sync with what CacheKey covers.

+ //

+ // c.User and the raw gsg_share cookie value are folded in here,

+ // deliberately not into contentIdentity itself: contentIdentity also

+ // drives Ctx.CacheKey, the cross-request module Store key, and module

+ // results (tree/blob/log/...) aren't user-dependent -- authorization

+ // happens in buildCtx's Lookup gate, not inside a module. Keying the

+ // shared LRU per grant would fragment it for no benefit. The ETag,

+ // unlike the module cache, must vary by identity: without c.User,

+ // logging in or out keeps the same ETag as the anonymous response and a

+ // browser's stale If-None-Match earns a 304 with the wrong body. The

+ // share cookie needs the same treatment for the same reason: two

+ // anonymous visitors holding different share grants both have

+ // c.User == "", so without it they'd collide on one ETag and one

+ // share-holder's listing could be served to another. The cookie's own

+ // signature bytes already uniquely identify the grant, and folding them

+ // into a hash never echoes them back in a header.

+ //

+ // s.StaticTag is folded in too: a CSS/JS-only edit changes every

+ // rendered `static "..."` URL, so page ETags have to move with it.

+ shareCookie := ""

+ if ck, err := r.Cookie(session.ShareCookieName); err == nil {

+ shareCookie = ck.Value

+ }

+ etag := `"` + shortHash(rt.Name, r.URL.Path, r.URL.RawQuery, tag, s.StaticTag, c.contentIdentity(), c.User, shareCookie) + `"`

+

+ header := http.Header{}

+ header.Set("ETag", etag)

+ if c.Immutable {

+ header.Set("Cache-Control", "public, max-age=31536000, immutable")

+ } else {

+ // Vary: Cookie applies to every response here, not just personalized

+ // ones -- the *absence* of gsg_user is also a cache dimension. Without

+ // it on the anonymous branch too, a shared cache could store an

+ // anonymous response keyed on URL alone and later serve it back to a

+ // request that does carry a session cookie.

+ header.Add("Vary", "Cookie")

+ if c.User != "" || len(c.SharedSlugs) > 0 {

+ // No shared/intermediary cache (proxy, CDN, or gsg's own

+ // respCache) may ever store this response, only the requesting

+ // browser -- otherwise a misbehaving shared cache could serve

+ // one user's hidden-repo listing to a different visitor. Vary:

+ // Cookie above is defense in depth for any cache that honors

+ // Vary but not Cache-Control: private.

+ header.Set("Cache-Control", "private, no-cache")

+ } else {

+ // public, with a real max-age rather than no-cache: the ETag

+ // already folds in c.User and the share cookie (above), so the

+ // only failure mode for a shared cache that mishandles Vary is

+ // serving this anonymous view to a logged-in or share-holding

+ // visitor within the TTL -- they see fewer repos, or a 404 on a

+ // hidden one. A UX papercut, not a disclosure: the dangerous

+ // direction (private content served to an anonymous visitor)

+ // can't happen here, since that's the separate branch above.

+ header.Set("Cache-Control", fmt.Sprintf("public, max-age=%d", int(c.cacheMaxAge().Seconds())))

+ }

+ }

+ return c, header, nil

+}

+

+func copyHeader(dst, src http.Header) {

+ for k, vs := range src {

+ for _, v := range vs {

+ dst.Add(k, v)

+ }

+ }

+}

+

+func writeResponse(w http.ResponseWriter, r *http.Request, cr *cachedResponse) {

+ copyHeader(w.Header(), cr.header)

+ if match := r.Header.Get("If-None-Match"); match != "" && strings.Contains(match, cr.header.Get("ETag")) {

+ w.WriteHeader(http.StatusNotModified)

+ return

+ }

+ w.Write(cr.body)

+}

+

+ // Resolved once, before the scope branch, so the site-scoped early

+ // return (the index page -- the main surface a login or share link is

+ // meant to affect) doesn't skip it.

+ identity := access.Identity{User: s.Sessions.Verify(r)}

+ if claims, ok := s.Sessions.VerifyShareCookie(r); ok {

+ identity.SharedSlugs, identity.SharedIssuedAt = claims.Slugs, claims.IssuedAt()

+ }

+

+ c.User = identity.User

+ c.SharedSlugs, c.SharedIssuedAt = identity.SharedSlugs, identity.SharedIssuedAt

+ c.StaticTag = s.StaticTag

+ h, ok := s.Site.Lookup(slug)

+ // Hidden repos are 404, indistinguishable from nonexistent, unless the

+ // resolved identity is explicitly allowed to see this one. The rule lives

+ // in internal/access so this gate, the index module and share redemption

+ // agree about owners, grants and revocation.

+ if !h.Info.AccessPolicy().CanView(identity) {

+ return nil, Errorf(http.StatusNotFound, "no such repository %q", slug)

+ }

+ req, err := parseRequest(rt, repo, r)

+ if err != nil {

+ return nil, err

+ ref, path := req.Ref, req.Path

+ c.User = identity.User

+ c.SharedSlugs, c.SharedIssuedAt = identity.SharedSlugs, identity.SharedIssuedAt

+ c.StaticTag = s.StaticTag

+ if req.Range != nil {

+ base := req.Range.Base

+ dots := "2"

+ if req.Range.ThreeDot {

+ dots = "3"

+ }

+ headSHA := c.Commit

+ // Two-dot compares are undirected as far as the caller is concerned:

+ // whichever ref is the ancestor should read as "base", regardless of

+ // which side of ".." it was typed on. Three-dot is left alone --

+ // its merge-base semantics are direction-sensitive by design.

+ if dots == "2" && baseSHA != headSHA {

+ if anc, err := repo.IsAncestor(headSHA, baseSHA); err == nil && anc {

+ base, ref = ref, base

+ baseSHA, headSHA = headSHA, baseSHA

+ }

+ }

+ c.Ref, c.Commit = ref, headSHA

+ c.Vars["baseSHA"], c.Vars["headSHA"] = baseSHA, headSHA

+ if rt.PageSize > 0 {

+ if v := r.URL.Query().Get("ofs"); v != "" {

+ if ofs, err := strconv.Atoi(v); err == nil && ofs > 0 {

+ ofs -= ofs % rt.PageSize // snap to a page boundary before it can become a cache key

+ c.Vars["ofs"] = strconv.Itoa(ofs)

+ }

+ }

+ }

+ // One source of truth for the immutable policy: the cache header in

+ // buildResponseHead reads the same field, so page chrome that must not

+ // be frozen into a year-long response is suppressed by exactly the

+ // condition that makes the response year-long.

+ c.Immutable = rt.Immutable && c.Commit != ""

+// parseRequest applies the route's parser, or the default {rest...}/{rev}

+// handling. Both only identify ref candidates; buildCtx below always calls

+// Repo.Resolve before anything downstream sees a commit.

+func parseRequest(rt Route, repo *gitx.Repo, r *http.Request) (Request, error) {

+ if rt.Request != nil {

+ return rt.Request(r)

+ }

+ switch {

+ case r.PathValue("rest") != "":

+ ref, path := repo.SplitRefPath(r.PathValue("rest"))

+ return Request{Ref: ref, Path: path}, nil

+ case r.PathValue("rev") != "":

+ return Request{Ref: r.PathValue("rev")}, nil

+ default:

+ return Request{Ref: repo.HeadRef()}, nil

+ }

+}

+

+

+ // The cached-response and cache-fill paths in serve() only ever reach

+ // fail() before anything is written to w, so for those there is

+ // nothing to strip. But the plain (non-cacheable) path copies

+ // buildResponseHead's ETag/Cache-Control onto w *before* calling

+ // Render, on the assumption that Render will succeed -- if it doesn't,

+ // this Del/Set is still what prevents a failed response from going out

+ // with a stale ETag or, worse, the year-long immutable Cache-Control

+ // from a commit route.

+ w.Header().Del("ETag")

+ w.Header().Set("Cache-Control", "no-store")

+

+ body, cType := renderErrorPage(code, s.Site.Name)

+ w.Header().Set("Content-Type", cType)

+ w.WriteHeader(code)

+ w.Write(body)

+package core

+

+import (

+ "fmt"

+ "log/slog"

+ "os"

+ "path/filepath"

+ "sync"

+ "time"

+

+ "github.com/fsnotify/fsnotify"

+

+ "gsg/internal/gitx"

+)

+

+// discoverConcurrency bounds how many repositories are opened at once during

+// the initial scan. Each one is a handful of git forks plus, for

+// keyring-bearing repos, a gpg import -- unbounded parallelism would fork

+// thousands of processes at once on a large install.

+const discoverConcurrency = 16

+

+// watcher owns every repo directly under root: which ones are currently

+// open, and the fsnotify watch that tells it when to look again. reconcile

+// is the single entry point for loading, reloading, or dropping a repo --

+// used identically by the initial scan and by every later filesystem event.

+type watcher struct {

+ site *Site

+ root string

+ fsw *fsnotify.Watcher

+

+ mu sync.Mutex

+ repos map[string]*gitx.Repo // open repos, by directory name -- reused across reconciles

+ dirName map[string]string // git-dir path -> directory name, for event dispatch

+

+ debMu sync.Mutex

+ debounce map[string]*time.Timer

+}

+

+// Start discovers every repository under site.Root, then watches root and

+// each repo's git-dir for changes for the life of the process. It returns

+// once the initial scan completes, the same as the old discover() did.

+func Start(site *Site) error {

+ fsw, err := fsnotify.NewWatcher()

+ if err != nil {

+ return fmt.Errorf("config watch: %w", err)

+ }

+ if err := fsw.Add(site.Root); err != nil {

+ fsw.Close()

+ return fmt.Errorf("config watch: %w", err)

+ }

+

+ w := &watcher{

+ site: site,

+ root: site.Root,

+ fsw: fsw,

+ repos: map[string]*gitx.Repo{},

+ dirName: map[string]string{},

+ debounce: map[string]*time.Timer{},

+ }

+

+ entries, err := os.ReadDir(site.Root)

+ if err != nil {

+ fsw.Close()

+ return err

+ }

+

+ sem := make(chan struct{}, discoverConcurrency)

+ var wg sync.WaitGroup

+ for _, e := range entries {

+ if !e.IsDir() {

+ continue

+ }

+ wg.Add(1)

+ go func(name string) {

+ defer wg.Done()

+ sem <- struct{}{}

+ defer func() { <-sem }()

+ w.reconcile(name)

+ }(e.Name())

+ }

+ wg.Wait()

+

+ if len(site.RepoList()) == 0 {

+ fsw.Close()

+ return fmt.Errorf("no repositories found under %s", site.Root)

+ }

+

+ go w.run()

+ return nil

+}

+

+// reconcile loads, reloads, or drops exactly one repo, named by its

+// directory under root. It is existence-driven rather than event-driven --

+// it doesn't ask what kind of filesystem event caused this call, only

+// whether root/name currently exists and is a valid repo -- which is what

+// lets the same function serve both the initial concurrent scan and the

+// one-at-a-time runtime event loop with no special-casing between them.

+func (w *watcher) reconcile(name string) {

+ dir := filepath.Join(w.root, name)

+

+ w.mu.Lock()

+ r, known := w.repos[name]

+ w.mu.Unlock()

+

+ if _, err := os.Stat(dir); err != nil {

+ if known {

+ w.mu.Lock()

+ delete(w.repos, name)

+ w.fsw.Remove(r.Dir)

+ delete(w.dirName, r.Dir)

+ w.mu.Unlock()

+ w.site.remove(r.Slug)

+ }

+ return

+ }

+

+ if !known {

+ var err error

+ if r, err = gitx.Open(dir); err != nil {

+ return // not a repo (or a bare clone still being populated)

+ }

+ w.mu.Lock()

+ w.repos[name] = r

+ w.fsw.Add(r.Dir) // catches this repo's own config/description writes from here on

+ w.dirName[r.Dir] = name

+ w.mu.Unlock()

+ }

+

+ info := LoadRepoInfo(r)

+

+ // Converge the keyring to whatever's configured now, on this call just

+ // like any other -- no "only import the first time" special case.

+ if info.GPGKeyring != r.KeyringPath() {

+ if info.GPGKeyring == "" {

+ r.ClearKeyring()

+ } else if err := r.UseKeyring(info.GPGKeyring); err != nil {

+ slog.Warn("gpg keyring: verification disabled", "repo", info.Slug, "err", err)

+ info.GPGKeyring = ""

+ }

+ }

+

+ w.site.upsert(Handle{Repo: r, Info: info})

+}

+

+// run consumes filesystem events for the life of the process. A repo dir

+// appearing, disappearing, or being renamed under root is dispatched by its

+// (new) name; a write to a known repo's config or description file is

+// dispatched by that repo's name.

+func (w *watcher) run() {

+ for {

+ select {

+ case ev, ok := <-w.fsw.Events:

+ if !ok {

+ return

+ }

+ if filepath.Dir(ev.Name) == w.root {

+ w.scheduleReconcile(filepath.Base(ev.Name))

+ continue

+ }

+ if base := filepath.Base(ev.Name); base == "config" || base == "description" {

+ w.mu.Lock()

+ name := w.dirName[filepath.Dir(ev.Name)]

+ w.mu.Unlock()

+ if name != "" {

+ w.scheduleReconcile(name)

+ }

+ }

+ case err, ok := <-w.fsw.Errors:

+ if !ok {

+ return

+ }

+ slog.Warn("config watch error", "err", err)

+ }

+ }

+}

+

+// scheduleReconcile coalesces bursts of events for the same repo -- a single

+// `git config` write is a lockfile create plus a rename, i.e. at least two

+// raw events for one logical change -- into a single reconcile call.

+func (w *watcher) scheduleReconcile(name string) {

+ const debounceDelay = 200 * time.Millisecond

+

+ w.debMu.Lock()

+ defer w.debMu.Unlock()

+

+ if t, ok := w.debounce[name]; ok {

+ t.Reset(debounceDelay)

+ return

+ }

+ w.debounce[name] = time.AfterFunc(debounceDelay, func() {

+ w.debMu.Lock()

+ delete(w.debounce, name)

+ w.debMu.Unlock()

+ w.reconcile(name)

+ })

+}

+ "errors"

+ "sync"

+

+ // gpgHome, once set by UseKeyring, is an isolated GNUPGHOME containing

+ // only the keys the operator imported for this repo. Its presence is

+ // also the signal to Log/LogAll to ask git for signature status at all.

+ gpgHome string

+

+ // keyringPath is the gsg.gpgkeyring value that produced gpgHome, so a

+ // caller can tell whether the configured keyring has changed without

+ // tracking that separately. Empty when no keyring is imported.

+ keyringPath string

+

+ // memo caches HeadRef/Refs for the lifetime of one request. It is a

+ // pointer, allocated fresh by WithContext, rather than a plain field:

+ // Repo is copied by value (see WithContext), so a mutex or map field

+ // here directly would either trip go vet's copylocks check or -- worse

+ // -- share its map header with the copy, leaking one request's cache

+ // into the long-lived Repo every Handle keeps between requests. nil on

+ // that long-lived Repo and in any Repo not built via WithContext (e.g.

+ // tests): HeadRef/Refs just skip the cache in that case.

+ memo *repoMemo

+}

+

+type repoMemo struct {

+ mu sync.Mutex

+ headRef *string

+ haveRefs bool

+ refs []Ref

+ refsErr error

+ c.memo = &repoMemo{}

+ // safe.directory=* bypasses git's dubious-ownership check (CVE-2022-24765).

+ // gsg runs against operator-chosen repo roots, commonly bind-mounted into

+ // a container where the mount ends up owned by a different uid than the

+ // process -- a trust boundary git can't see, since HOME=/nonexistent

+ // below means there's no config file left to set this in from outside.

+ full := append([]string{"--git-dir", r.Dir, "-c", "safe.directory=*"}, args...)

+ if r.gpgHome != "" {

+ // git shells out to gpg to check %G?; gpg picks this up from its

+ // own environment, which it inherits from git's.

+ cmd.Env = append(cmd.Env, "GNUPGHOME="+r.gpgHome)

+ }

+// -------------------------------------------------------------------- gpg

+

+// UseKeyring points every subsequent git invocation on this Repo (via

+// GNUPGHOME, see run) at an isolated homedir containing only the keys

+// imported from path. Without this, %G? signature checks would fall back

+// to the host's default keyring -- whatever happens to be trusted there,

+// not what this repo's operator vetted.

+//

+// The homedir is created directly under /tmp rather than os.TempDir():

+// gpg-agent's control socket is a Unix domain socket, capped at ~104

+// bytes, and a long TMPDIR (macOS's is typically 50+ characters) pushes

+// the full path over that limit and breaks key generation/import in a way

+// that just prints "no agent running" with no useful exit code to catch.

+func (r *Repo) UseKeyring(path string) error {

+ dir, err := os.MkdirTemp("/tmp", "gsg-gpg-")

+ if err != nil {

+ return fmt.Errorf("gpg keyring: %w", err)

+ }

+ if err := os.Chmod(dir, 0700); err != nil {

+ return fmt.Errorf("gpg keyring: %w", err)

+ }

+ cmd := exec.Command("gpg", "--batch", "--quiet", "--import", path)

+ cmd.Env = []string{"GNUPGHOME=" + dir, "HOME=/nonexistent", "PATH=" + os.Getenv("PATH")}

+ var errb bytes.Buffer

+ cmd.Stderr = &errb

+ if err := cmd.Run(); err != nil {

+ os.RemoveAll(dir)

+ return fmt.Errorf("gpg keyring: import %s: %w: %s", path, err, strings.TrimSpace(errb.String()))

+ }

+

+ // Only swap the new homedir in -- and clean up the old one -- once the

+ // import has actually succeeded, so a bad reconfigure logs a warning and

+ // leaves the previously-working keyring active rather than breaking it.

+ old := r.gpgHome

+ r.gpgHome, r.keyringPath = dir, path

+ if old != "" {

+ os.RemoveAll(old)

+ }

+ return nil

+}

+

+// KeyringPath is the gsg.gpgkeyring value currently imported, or "" if no

+// keyring is active. Callers use this to detect when the configured keyring

+// has changed, on any call -- the first or the hundredth -- without needing

+// to track that separately.

+func (r *Repo) KeyringPath() string { return r.keyringPath }

+

+// ClearKeyring reverts to unverified signatures, removing any imported

+// keyring's isolated homedir.

+func (r *Repo) ClearKeyring() {

+ if r.gpgHome != "" {

+ os.RemoveAll(r.gpgHome)

+ }

+ r.gpgHome, r.keyringPath = "", ""

+}

+

+ if r.memo != nil {

+ r.memo.mu.Lock()

+ if r.memo.haveRefs {

+ refs, err := r.memo.refs, r.memo.refsErr

+ r.memo.mu.Unlock()

+ return refs, err

+ }

+ r.memo.mu.Unlock()

+ }

+

+ refs, err := r.refs()

+

+ if r.memo != nil {

+ r.memo.mu.Lock()

+ r.memo.refs, r.memo.refsErr, r.memo.haveRefs = refs, err, true

+ r.memo.mu.Unlock()

+ }

+ return refs, err

+}

+

+func (r *Repo) refs() ([]Ref, error) {

+ out, err := r.run("rev-parse", "--verify", "--quiet", ref+"^{commit}")

+ return "", fmt.Errorf("unknown commit %q", ref)

+ if r.memo != nil {

+ r.memo.mu.Lock()

+ cached := r.memo.headRef

+ r.memo.mu.Unlock()

+ if cached != nil {

+ return *cached

+ }

+ }

+

+ head := r.headRef()

+

+ if r.memo != nil {

+ r.memo.mu.Lock()

+ r.memo.headRef = &head

+ r.memo.mu.Unlock()

+ }

+ return head

+}

+

+func (r *Repo) headRef() string {

+

+ // Signature is only populated when the caller asked for it (Log, when

+ // the repo has a keyring -- see Repo.UseKeyring). SigStatus is git's

+ // raw %G? code: G/U good, B bad, X/Y expired, R revoked, E unchecked,

+ // N unsigned or "" when signature checks weren't requested at all.

+ SigStatus string

+ Signer string

+ KeyID string

+}

+

+// Verified reports a good signature from a key in the repo's configured

+// keyring. A bare gpg homedir has no ownertrust database, so a genuinely

+// valid signature from a freshly-imported key comes back "U" (valid, trust

+// unknown), not "G" -- trust here comes from the key being in the

+// operator's keyring file, not from GPG's own web-of-trust bookkeeping.

+func (c Commit) Verified() bool { return c.SigStatus == "G" || c.SigStatus == "U" }

+

+// Signed reports whether the commit carries a signature at all, good or

+// not -- lets a template tell "bad signature" apart from "no signature".

+func (c Commit) Signed() bool { return c.SigStatus != "" && c.SigStatus != "N" }

+

+// Unchecked reports a signature git could not evaluate against the

+// keyring at all -- almost always because the signing key just isn't in

+// it. That is not evidence of tampering the way B/X/Y/R are, so it should

+// read as "we don't know", not as a failure.

+func (c Commit) Unchecked() bool { return c.SigStatus == "E" }

+

+// SigLabel is a short human-readable rendering of SigStatus, for the log

+// view's badge.

+func (c Commit) SigLabel() string {

+ switch c.SigStatus {

+ case "G", "U":

+ return "verified"

+ case "B":

+ return "bad signature"

+ case "X":

+ return "expired signature"

+ case "Y":

+ return "expired key"

+ case "R":

+ return "revoked key"

+ case "E":

+ return "signature not checked"

+ default:

+ return "unsigned"

+ }

+// When verify is true, each commit also carries its signature status --

+// only pass true for small, bounded logs: git forks gpg once per signed

+// commit to check it.

+func (r *Repo) Log(rev string, n, skip int, verify bool) ([]Commit, error) {

+ verify = verify && r.gpgHome != "" // no keyring configured: nothing to check against

+ fields := []string{"%H", "%an", "%ae", "%aI", "%P", "%s"}

+ if verify {

+ fields = append(fields, "%G?", "%GS", "%GK")

+ }

+ fields = append(fields, "%b")

+ format := strings.Join(fields, escLogF)

+ if skip > 0 {

+ args = append(args, "--skip", strconv.Itoa(skip))

+ }

+ out, err := r.run(args...)

+ return r.parseLog(out, err, verify)

+func (r *Repo) parseLog(out []byte, err error, verify bool) ([]Commit, error) {

+ nfields := 7

+ if verify {

+ nfields = 10

+ }

+ p := strings.SplitN(rec, sepF, nfields)

+ if len(p) < nfields {

+ Subject: p[5],

+ }

+ if verify {

+ c.SigStatus, c.Signer, c.KeyID, c.Body = p[6], p[7], p[8], strings.TrimSpace(p[9])

+ } else {

+ c.Body = strings.TrimSpace(p[6])

+// IsAncestor reports whether a is an ancestor of b (true, in particular,

+// when a == b).

+func (r *Repo) IsAncestor(a, b string) (bool, error) {

+ _, err := r.run("merge-base", "--is-ancestor", a, b)

+ if err == nil {

+ return true, nil

+ }

+ var exitErr *exec.ExitError

+ if errors.As(err, &exitErr) && exitErr.ExitCode() == 1 {

+ return false, nil

+ }

+ return false, err

+}

+

+ // Never request signature status here: this walks every ref unbounded

+ // for the graph view, and git forks gpg per signed commit -- fine at

+ // Log's n=20, not fine here.

+ out, err := r.run("log", "--all", "--topo-order", "--date-order",

+ "-n", strconv.Itoa(n), "--format="+escLogR+format)

+ return r.parseLog(out, err, false)

+func (e Entry) IsDir() bool { return e.Type == "tree" }

+func (e Entry) IsSubmodule() bool { return e.Type == "commit" }

+// Stat looks up a single path's own tree entry (its mode/type/sha as

+// recorded by its parent tree), regardless of depth. Unlike Blob, this

+// works for gitlinks (submodules), since it never tries to read object

+// contents.

+func (r *Repo) Stat(rev, path string) (Entry, bool, error) {

+ out, err := r.run("ls-tree", "-z", "--long", rev, "--", path)

+ if err != nil {

+ return Entry{}, false, err

+ }

+ rec := strings.TrimSuffix(string(out), "\x00")

+ if rec == "" {

+ return Entry{}, false, nil

+ }

+ head, name, ok := strings.Cut(rec, "\t")

+ if !ok {

+ return Entry{}, false, nil

+ }

+ f := strings.Fields(head)

+ if len(f) < 3 {

+ return Entry{}, false, nil

+ }

+ e := Entry{Mode: f[0], Type: f[1], SHA: f[2], Name: filepath.Base(name), Path: name}

+ if len(f) > 3 {

+ e.Size, _ = strconv.ParseInt(f[3], 10, 64)

+ }

+ return e, true, nil

+}

+

+// SubmoduleURL looks up the remote configured for a submodule path in

+// .gitmodules at rev. Best-effort: a missing or unparsable file just means

+// no URL is shown alongside the pinned commit.

+func (r *Repo) SubmoduleURL(rev, path string) string {

+ raw, err := r.Blob(rev, ".gitmodules")

+ if err != nil {

+ return ""

+ }

+ var inSection, sectionMatches bool

+ for _, line := range strings.Split(string(raw), "\n") {

+ line = strings.TrimSpace(line)

+ if strings.HasPrefix(line, "[submodule") {

+ inSection = true

+ sectionMatches = false

+ continue

+ }

+ if !inSection {

+ continue

+ }

+ key, val, ok := strings.Cut(line, "=")

+ if !ok {

+ continue

+ }

+ key, val = strings.TrimSpace(key), strings.TrimSpace(val)

+ switch key {

+ case "path":

+ sectionMatches = val == path

+ case "url":

+ if sectionMatches {

+ return val

+ }

+ }

+ }

+ return ""

+}

+

+package gitx

+

+import (

+ "os"

+ "os/exec"

+ "testing"

+)

+

+// runGit drives git directly (not through Repo.run, which doesn't exist

+// yet at setup time) with the same kind of isolation Repo.run uses --

+// GIT_CONFIG_NOSYSTEM and a throwaway HOME -- so the test behaves the same

+// on a machine with commit.gpgsign=true globally as it does in CI.

+func runGit(t *testing.T, dir string, args ...string) {

+ t.Helper()

+ cmd := exec.Command("git", append([]string{"-C", dir, "-c", "commit.gpgsign=false"}, args...)...)

+ cmd.Env = []string{

+ "PATH=" + os.Getenv("PATH"),

+ "HOME=" + dir,

+ "GIT_CONFIG_NOSYSTEM=1",

+ "GIT_AUTHOR_NAME=test", "GIT_AUTHOR_EMAIL=test@example.com",

+ "GIT_COMMITTER_NAME=test", "GIT_COMMITTER_EMAIL=test@example.com",

+ }

+ if out, err := cmd.CombinedOutput(); err != nil {

+ t.Fatalf("git %v: %v\n%s", args, err, out)

+ }

+}

+

+// newTestRepo builds a real repository with one empty commit, a branch

+// "feature/x" (a branch name containing a slash), a second branch

+// "release", and a tag "release/1.0". The last two coexist by construction

+// deliberately: refs/heads and refs/tags are separate namespaces, so

+// "release" (a branch) and "release/1.0" (a tag) can both exist even

+// though a branch "release" and a branch "release/1.0" could not -- git

+// refuses that, since a ref name is a path and "release" can't be both a

+// file and a directory. Opened through gitx.Open, because SplitRefPath

+// resolves against Refs(), which shells out to `git for-each-ref` -- there

+// is no faking that, it has to be a real repo with real refs.

+func newTestRepo(t *testing.T) *Repo {

+ t.Helper()

+ dir := t.TempDir()

+ runGit(t, dir, "init", "-q", "-b", "main")

+ runGit(t, dir, "commit", "-q", "--allow-empty", "-m", "init")

+ runGit(t, dir, "branch", "feature/x")

+ runGit(t, dir, "branch", "release")

+ runGit(t, dir, "tag", "release/1.0")

+

+ r, err := Open(dir)

+ if err != nil {

+ t.Fatalf("Open: %v", err)

+ }

+ return r

+}

+

+// TestSplitRefPath guards the longest-prefix-wins rule that lets ref names

+// contain slashes. A naive split at the first "/" gets both of the two

+// interesting cases here wrong: it would send "feature/x/src/main.go" to

+// ref "feature" (not a ref at all) instead of branch "feature/x", and it

+// would send "release/1.0/docs/readme.md" to branch "release" instead of

+// the more specific tag "release/1.0" -- the real ambiguity SplitRefPath

+// exists to resolve, since both "release" and "release/1.0" are valid refs

+// here and only the longest match is the intended one.

+func TestSplitRefPath(t *testing.T) {

+ r := newTestRepo(t)

+

+ cases := []struct {

+ name string

+ rest string

+ wantRef string

+ wantPath string

+ }{

+ {"single-segment branch with a path", "main/src/main.go", "main", "src/main.go"},

+ {"slashed branch name resolves in full, not just its first segment",

+ "feature/x/src/main.go", "feature/x", "src/main.go"},

+ {"slashed tag wins over a shorter branch that's also a valid prefix",

+ "release/1.0/docs/readme.md", "release/1.0", "docs/readme.md"},

+ {"shorter branch still resolves when no longer candidate matches",

+ "release/README.md", "release", "README.md"},

+ {"slashed branch with no path", "feature/x", "feature/x", ""},

+ {"empty rest falls back to HEAD", "", "main", ""},

+ {"no ref matches: whole thing is a path at HEAD",

+ "no/such/branch/file.go", "main", "no/such/branch/file.go"},

+ }

+

+ for _, tc := range cases {

+ t.Run(tc.name, func(t *testing.T) {

+ ref, path := r.SplitRefPath(tc.rest)

+ if ref != tc.wantRef || path != tc.wantPath {

+ t.Errorf("SplitRefPath(%q) = (%q, %q), want (%q, %q)",

+ tc.rest, ref, path, tc.wantRef, tc.wantPath)

+ }

+ })

+ }

+}

+

+// TestIsAncestor builds its own repo (rather than reusing newTestRepo,

+// whose branches all point at the same single commit) because it needs a

+// real linear ancestor/descendant pair plus a genuinely diverged pair:

+// "main" advances past the point where "other" branched off, then "other"

+// advances on its own, so main's tip and other's tip share c1 as a common

+// ancestor but are not ancestors of each other.

+func TestIsAncestor(t *testing.T) {

+ dir := t.TempDir()

+ runGit(t, dir, "init", "-q", "-b", "main")

+ runGit(t, dir, "commit", "-q", "--allow-empty", "-m", "c1")

+

+ r, err := Open(dir)

+ if err != nil {

+ t.Fatalf("Open: %v", err)

+ }

+ c1, err := r.Resolve("main")

+ if err != nil {

+ t.Fatalf("Resolve(main): %v", err)

+ }

+

+ runGit(t, dir, "branch", "other")

+ runGit(t, dir, "commit", "-q", "--allow-empty", "-m", "c2")

+ c2, err := r.Resolve("main")

+ if err != nil {

+ t.Fatalf("Resolve(main): %v", err)

+ }

+

+ runGit(t, dir, "checkout", "-q", "other")

+ runGit(t, dir, "commit", "-q", "--allow-empty", "-m", "c3-diverged")

+ c3, err := r.Resolve("other")

+ if err != nil {

+ t.Fatalf("Resolve(other): %v", err)

+ }

+

+ cases := []struct {

+ name string

+ a, b string

+ want bool

+ }{

+ {"strict ancestor", c1, c2, true},

+ {"reversed order is not an ancestor relationship", c2, c1, false},

+ {"a commit is its own ancestor", c1, c1, true},

+ {"diverged commits are not ancestors either direction", c2, c3, false},

+ {"diverged commits, reverse direction", c3, c2, false},

+ }

+ for _, tc := range cases {

+ t.Run(tc.name, func(t *testing.T) {

+ got, err := r.IsAncestor(tc.a, tc.b)

+ if err != nil {

+ t.Fatalf("IsAncestor(%q, %q): %v", tc.a, tc.b, err)

+ }

+ if got != tc.want {

+ t.Errorf("IsAncestor(%q, %q) = %v, want %v", tc.a, tc.b, got, tc.want)

+ }

+ })

+ }

+

+ t.Run("bogus revision is an error, not false", func(t *testing.T) {

+ if _, err := r.IsAncestor("deadbeef", c1); err == nil {

+ t.Error("IsAncestor with a bogus revision: got nil error, want non-nil")

+ }

+ })

+}

+// Package httpx holds small HTTP helpers shared by gsg's non-page

+// surfaces. The admin and share handlers must make the same origin,

+// scheme, header and remote-address decisions; keeping them here means a

+// security fix lands in one place instead of three.

+package httpx

+

+import (

+ "net"

+ "net/http"

+ "net/url"

+ "strings"

+)

+

+// SecureOptions controls the admin/share response policy. These pages are

+// deliberately not the themed site: no inline script or style, so the CSP

+// can stay tight.

+type SecureOptions struct {

+ // ScriptSrc is the CSP script-src value. Empty means "'none'"; the

+ // notices admin page needs "'self'" for admin.js, while share pages

+ // ship no JavaScript at all.

+ ScriptSrc string

+ // NoStore marks a response whose body must never be stored, even by

+ // the requesting browser -- a minted share URL is a bearer capability.

+ NoStore bool

+}

+

+// Secure sets the response headers every admin/share page must carry.

+func Secure(w http.ResponseWriter, opts SecureOptions) {

+ scriptSrc := opts.ScriptSrc

+ if scriptSrc == "" {

+ scriptSrc = "'none'"

+ }

+ hdr := w.Header()

+ hdr.Set("X-Content-Type-Options", "nosniff")

+ hdr.Set("X-Frame-Options", "DENY")

+ hdr.Set("Content-Security-Policy",

+ "default-src 'none'; style-src 'self'; script-src "+scriptSrc+

+ "; img-src 'self'; form-action 'self'; base-uri 'none'")

+ if opts.NoStore {

+ hdr.Set("Cache-Control", "no-store")

+ }

+}

+

+// SameOrigin blocks a cross-site POST even if a session cookie would

+// otherwise be sent. A valid cookie proves the browser is logged in; it

+// does not prove the request came from our own page.

+func SameOrigin(r *http.Request) bool {

+ switch r.Header.Get("Sec-Fetch-Site") {

+ case "", "same-origin", "none":

+ default:

+ return false

+ }

+ if o := r.Header.Get("Origin"); o != "" {

+ u, err := url.Parse(o)

+ if err != nil || !strings.EqualFold(u.Host, r.Host) {

+ return false

+ }

+ }

+ return true

+}

+

+// IsHTTPS reports whether the browser's original request was HTTPS,

+// accounting for the reverse proxy's X-Forwarded-Proto.

+func IsHTTPS(r *http.Request) bool {

+ return r.TLS != nil || strings.EqualFold(r.Header.Get("X-Forwarded-Proto"), "https")

+}

+

+// AbsoluteURL builds an absolute URL for a path on this host, using the

+// same proxy-aware scheme as IsHTTPS.

+func AbsoluteURL(r *http.Request, path string) string {

+ scheme := "http"

+ if IsHTTPS(r) {

+ scheme = "https"

+ }

+ return scheme + "://" + r.Host + path

+}

+

+// RemoteIP strips the port from r.RemoteAddr for use as a rate-limit key.

+func RemoteIP(r *http.Request) string {

+ host, _, err := net.SplitHostPort(r.RemoteAddr)

+ if err != nil {

+ return r.RemoteAddr

+ }

+ return host

+}

+package httpx

+

+import (

+ "net/http/httptest"

+ "strings"

+ "testing"

+)

+

+func TestSecure(t *testing.T) {

+ rec := httptest.NewRecorder()

+ Secure(rec, SecureOptions{ScriptSrc: "'self'", NoStore: true})

+ h := rec.Header()

+

+ if got := h.Get("X-Content-Type-Options"); got != "nosniff" {

+ t.Errorf("X-Content-Type-Options = %q", got)

+ }

+ if got := h.Get("X-Frame-Options"); got != "DENY" {

+ t.Errorf("X-Frame-Options = %q", got)

+ }

+ if got := h.Get("Cache-Control"); got != "no-store" {

+ t.Errorf("Cache-Control = %q", got)

+ }

+ if got := h.Get("Content-Security-Policy"); got == "" ||

+ !strings.Contains(got, "script-src 'self'") || !strings.Contains(got, "base-uri 'none'") {

+ t.Errorf("Content-Security-Policy = %q", got)

+ }

+}

+

+func TestSecureDefaultsToNoScript(t *testing.T) {

+ rec := httptest.NewRecorder()

+ Secure(rec, SecureOptions{})

+ if got := rec.Header().Get("Content-Security-Policy"); !strings.Contains(got, "script-src 'none'") {

+ t.Errorf("Content-Security-Policy = %q, want script-src 'none'", got)

+ }

+ if got := rec.Header().Get("Cache-Control"); got != "" {

+ t.Errorf("Cache-Control = %q, want unset", got)

+ }

+}

+

+func TestSameOrigin(t *testing.T) {

+ cases := []struct {

+ name string

+ fetch string

+ origin string

+ want bool

+ }{

+ {name: "no headers", want: true},

+ {name: "same origin", fetch: "same-origin", origin: "https://git.example", want: true},

+ {name: "cross site", fetch: "cross-site", want: false},

+ {name: "different origin", origin: "https://evil.example", want: false},

+ }

+

+ for _, tc := range cases {

+ t.Run(tc.name, func(t *testing.T) {

+ r := httptest.NewRequest("POST", "https://git.example/admin/notices", nil)

+ if tc.fetch != "" {

+ r.Header.Set("Sec-Fetch-Site", tc.fetch)

+ }

+ if tc.origin != "" {

+ r.Header.Set("Origin", tc.origin)

+ }

+ if got := SameOrigin(r); got != tc.want {

+ t.Fatalf("SameOrigin() = %v, want %v", got, tc.want)

+ }

+ })

+ }

+}

+

+func TestIsHTTPSAndAbsoluteURL(t *testing.T) {

+ r := httptest.NewRequest("GET", "http://git.example/share/new", nil)

+ r.Host = "git.example"

+ if IsHTTPS(r) {

+ t.Fatal("plain request reported HTTPS")

+ }

+ if got := AbsoluteURL(r, "/share/view/token"); got != "http://git.example/share/view/token" {

+ t.Fatalf("AbsoluteURL() = %q", got)

+ }

+

+ r.Header.Set("X-Forwarded-Proto", "https")

+ if !IsHTTPS(r) {

+ t.Fatal("proxied HTTPS request not recognized")

+ }

+ if got := AbsoluteURL(r, "/share/view/token"); got != "https://git.example/share/view/token" {

+ t.Fatalf("AbsoluteURL() = %q", got)

+ }

+}

+

+func TestRemoteIP(t *testing.T) {

+ r := httptest.NewRequest("GET", "/", nil)

+ r.RemoteAddr = "203.0.113.9:54321"

+ if got := RemoteIP(r); got != "203.0.113.9" {

+ t.Fatalf("RemoteIP() = %q", got)

+ }

+ r.RemoteAddr = "unix"

+ if got := RemoteIP(r); got != "unix" {

+ t.Fatalf("RemoteIP() = %q", got)

+ }

+}

+ "html/template"

+ Path string

+ Size int

+ Binary bool

+ Image string // validated raster MIME, "" when not a previewable image

+ Lines []Line

+ Submodule *Submodule

+ Lang string // "json" or "yaml", when the path implies one; "" otherwise

+ ParseErr *ParseNote // set when Lang is non-empty and the content doesn't parse

+ Oversize bool // Lang is set, but the file is too large to parse and index

+// Structured reports whether the fold/search/reference tooling applies to

+// this file. A recognised extension is not enough on its own: past

+// maxStructuredSize the view falls back to plain numbered lines.

+func (b Blob) Structured() bool { return b.Lang != "" && !b.Oversize }

+

+// StructuredLimit is the size past which that tooling switches itself off,

+// so the banner explaining the fallback can name the threshold.

+func (b Blob) StructuredLimit() int { return maxStructuredSize }

+

+// Preview reports whether the image is small enough to render inline. An

+// image over maxPreviewSize is still downloadable; it just is not fetched a

+// second time by every reader who only wanted to see the tree around it.

+func (b Blob) Preview() bool { return b.Image != "" && b.Size <= maxPreviewSize }

+

+// PreviewLimit names the threshold for the too-large notice.

+func (b Blob) PreviewLimit() int { return maxPreviewSize }

+

+// Submodule describes a gitlink entry (mode 160000): a pointer to a commit

+// in another repository rather than file content, so there is nothing to

+// diff or display line-by-line.

+type Submodule struct {

+ SHA string

+ Remote string // from .gitmodules, best-effort; empty if not found

+}

+

+// Line is one rendered source line. Everything past Text is structure the

+// blob view uses to fold, filter and cross-reference JSON/YAML, and is zero

+// for every other language.

+ Text template.HTML

+

+ Depth int // nesting level, in indent units

+ FoldTo int // last line of the block this one opens; 0 if it opens none

+ Key string // mapping key declared here, for key-scoped search

+ Path string // canonical value path, for path queries; "" when unknown

+ Anchor *Anchor // YAML anchor declared here

+ Ref *StructRef // YAML alias resolved here

+ if entry, ok, _ := c.Repo.Stat(c.Commit, path); ok && entry.Type == "commit" {

+ return Blob{Path: path, Submodule: &Submodule{

+ SHA: entry.SHA,

+ Remote: c.Repo.SubmoduleURL(c.Commit, path),

+ }}, nil

+ }

+ // Check the image magic before the generic binary test: a valid raster

+ // image is served as a preview rather than a wall of numbered bytes.

+ b.Image = imageContentType(path, raw)

+ if b.Image != "" {

+ b.Binary = true

+ return b, nil

+ }

+ b.Lang = structuredLang(path)

+ b.Oversize = b.Lang != "" && len(raw) > maxStructuredSize

+ if b.Structured() {

+ b.ParseErr = validateStructured(b.Lang, raw)

+ }

+

+ hl, ok := highlightLines(path, raw)

+ if !ok {

+ for _, t := range strings.Split(strings.TrimRight(string(raw), "\n"), "\n") {

+ hl = append(hl, template.HTML(template.HTMLEscapeString(t)))

+ }

+ } else if b.Structured() {

+ hl = withIndentGuides(hl, indentUnit(raw))

+ }

+ for i, t := range hl {

+ if b.Structured() {

+ annotateStructure(b.Lines, raw, b.Lang)

+ }

+ Image string // validated raster MIME; see imageContentType

+func (r RawBlob) Bytes() []byte { return r.Data }

+func (r RawBlob) IsBinary() bool { return r.Binary }

+func (r RawBlob) InlineContentType() string { return r.Image }

+ return RawBlob{

+ Path: path,

+ Data: raw,

+ Binary: bytes.IndexByte(head, 0) >= 0,

+ Image: imageContentType(path, raw),

+ }, nil

+package modules

+

+import (

+ "fmt"

+ "os"

+ "os/exec"

+ "path/filepath"

+ "strings"

+ "testing"

+

+ "gsg/internal/core"

+ "gsg/internal/gitx"

+)

+

+// blobCtx commits files into a throwaway repository and returns a Ctx

+// pointing at it. Isolation matches internal/gitx's own test helper, so a

+// machine with commit.gpgsign=true globally behaves like CI.

+func blobCtx(t *testing.T, files map[string]string) *core.Ctx {

+ t.Helper()

+ dir := t.TempDir()

+ env := []string{

+ "PATH=" + os.Getenv("PATH"),

+ "HOME=" + dir,

+ "GIT_CONFIG_NOSYSTEM=1",

+ "GIT_AUTHOR_NAME=test", "GIT_AUTHOR_EMAIL=test@example.com",

+ "GIT_COMMITTER_NAME=test", "GIT_COMMITTER_EMAIL=test@example.com",

+ }

+ git := func(args ...string) {

+ t.Helper()

+ cmd := exec.Command("git", append([]string{"-C", dir, "-c", "commit.gpgsign=false"}, args...)...)

+ cmd.Env = env

+ if out, err := cmd.CombinedOutput(); err != nil {

+ t.Fatalf("git %v: %v\n%s", args, err, out)

+ }

+ }

+ git("init", "-q", ".")

+ for name, body := range files {

+ if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o644); err != nil {

+ t.Fatal(err)

+ }

+ }

+ git("add", "-A")

+ git("commit", "-qm", "fixture")

+

+ repo, err := gitx.Open(dir)

+ if err != nil {

+ t.Fatal(err)

+ }

+ sha, err := repo.Resolve("HEAD")

+ if err != nil {

+ t.Fatal(err)

+ }

+ return &core.Ctx{Repo: repo, Ref: "HEAD", Commit: sha}

+}

+

+func blobAt(t *testing.T, c *core.Ctx, path string) Blob {

+ t.Helper()

+ c.Path = path

+ v, err := blobMod(c)

+ if err != nil {

+ t.Fatalf("blob %q: %v", path, err)

+ }

+ b, ok := v.(Blob)

+ if !ok {

+ t.Fatalf("blob %q: got %T", path, v)

+ }

+ return b

+}

+

+// Past maxStructuredSize a config file is served as plain numbered lines:

+// no parse, no fold ranges, no anchor resolution -- and Oversize set so the

+// view can say why rather than silently dropping the tooling.

+func TestStructuredSizeGate(t *testing.T) {

+ var big strings.Builder

+ big.WriteString("items: &items\n")

+ for i := 0; big.Len() <= maxStructuredSize; i++ {

+ fmt.Fprintf(&big, " - name: item-%d\n value: %d\n", i, i)

+ }

+ small := "items: &items\n - name: a\ncopy: *items\n"

+

+ c := blobCtx(t, map[string]string{"big.yaml": big.String(), "small.yaml": small})

+

+ b := blobAt(t, c, "big.yaml")

+ if b.Lang != "yaml" {

+ t.Errorf("Lang = %q, want yaml", b.Lang)

+ }

+ if !b.Oversize || b.Structured() {

+ t.Errorf("Oversize = %v, Structured = %v; want true, false", b.Oversize, b.Structured())

+ }

+ if b.ParseErr != nil {

+ t.Errorf("oversize file was parsed anyway: %+v", b.ParseErr)

+ }

+ if len(b.Lines) == 0 {

+ t.Fatal("oversize file rendered no lines")

+ }

+ for _, l := range b.Lines {

+ if l.FoldTo != 0 || l.Depth != 0 || l.Key != "" || l.Anchor != nil || l.Ref != nil {

+ t.Fatalf("line %d carries structure past the size limit: %+v", l.N, l)

+ }

+ }

+

+ s := blobAt(t, c, "small.yaml")

+ if !s.Structured() || s.Oversize {

+ t.Fatalf("small file: Structured = %v, Oversize = %v", s.Structured(), s.Oversize)

+ }

+ if s.Lines[0].Anchor == nil || s.Lines[2].Ref == nil {

+ t.Error("small file lost its anchor/alias annotations")

+ }

+ if s.Lines[0].FoldTo != 2 {

+ t.Errorf("small file FoldTo = %d, want 2", s.Lines[0].FoldTo)

+ }

+}

+

+// A non-config file is never structured, whatever its size.

+func TestPlainFileIsNotStructured(t *testing.T) {

+ c := blobCtx(t, map[string]string{"main.go": "package main\n\nfunc main() {}\n"})

+ b := blobAt(t, c, "main.go")

+ if b.Structured() || b.Oversize || b.Lang != "" {

+ t.Errorf("go file: Lang = %q, Structured = %v, Oversize = %v", b.Lang, b.Structured(), b.Oversize)

+ }

+}

+ log, err := c.Repo.Log(c.Commit, 1, 0, false)

+ if log, err := c.Repo.Log(from+".."+head, 250, 0, false); err == nil {

+ log, err := c.Repo.Log(rev, n, 0, false)

+

+ Ofs, PageSize int

+ HasPrev, HasNext bool

+ PrevOfs, NextOfs int

+// graph: the DAG across every ref. {{ mod "graph" "120" }} -- default

+// core.GraphPageSize. Paginated via the ?ofs= query param on the graph

+// route (see buildCtx), which core.GraphPageSize must match.

+//

+// Lane assignment below is a single forward pass that carries state

+// (`active`) across every row, so a page can't be computed by slicing the

+// git fetch with --skip -- that would reset `active` at the page boundary

+// and corrupt lane continuity. Instead every request walks the full range

+// from the top of history through the end of the requested page, and only

+// the rendered rows are sliced down to the page afterward, once Lanes and

+// each row's Rail SVG have already been computed against the full range.

+ n := core.GraphPageSize

+ ofs, _ := strconv.Atoi(c.Var("ofs"))

+ if ofs < 0 {

+ ofs = 0

+ }

+ commits, err := c.Repo.LogAll(ofs + n + 1) // from the top; no --skip, see above

+

+ total := len(g.Rows)

+ end := ofs + n

+ hasNext := total > end

+ if end > total {

+ end = total

+ }

+ start := ofs

+ if start > total {

+ start = total

+ }

+ g.Rows = g.Rows[start:end]

+ g.Ofs, g.PageSize = ofs, n

+ g.HasPrev, g.PrevOfs = ofs > 0, ofs-n

+ if g.PrevOfs < 0 {

+ g.PrevOfs = 0

+ }

+ g.HasNext, g.NextOfs = hasNext, end

+package modules

+

+import (

+ "html/template"

+ "strings"

+

+ "github.com/alecthomas/chroma/v2"

+ "github.com/alecthomas/chroma/v2/lexers"

+)

+

+// maxHighlightSize bounds how much source chroma will tokenise. Past this,

+// a file falls back to plain (still viewable, just uncoloured) text rather

+// than risk a slow lex on something pathological.

+const maxHighlightSize = 512 * 1024

+

+// highlightLines lexes src by the language implied by path and returns one

+// escaped, span-wrapped HTML fragment per line. ok is false when path has no

+// recognised language or src is too large to bother lexing; callers should

+// fall back to plain escaped lines in that case.

+func highlightLines(path string, src []byte) (lines []template.HTML, ok bool) {

+ if len(src) > maxHighlightSize {

+ return nil, false

+ }

+ lexer := lexers.Match(path)

+ if lexer == nil {

+ return nil, false

+ }

+ it, err := chroma.Coalesce(lexer).Tokenise(nil, string(src))

+ if err != nil {

+ return nil, false

+ }

+ for _, toks := range chroma.SplitTokensIntoLines(it.Tokens()) {

+ var b strings.Builder

+ for i, tok := range toks {

+ // SplitTokensIntoLines keeps each line's newline attached to

+ // its last token; drop it so it doesn't render as a blank

+ // row inside the (white-space: pre) table cell.

+ if i == len(toks)-1 {

+ tok.Value = strings.TrimSuffix(tok.Value, "\n")

+ }

+ esc := template.HTMLEscapeString(tok.Value)

+ if cls := tokenClass(tok.Type); cls != "" {

+ b.WriteString(`<span class="`)

+ b.WriteString(cls)

+ b.WriteString(`">`)

+ b.WriteString(esc)

+ b.WriteString(`</span>`)

+ } else {

+ b.WriteString(esc)

+ }

+ }

+ lines = append(lines, template.HTML(b.String()))

+ }

+ return lines, true

+}

+

+// tokenClass buckets chroma's ~70 token types down to the handful of colours

+// the theme actually defines (see --syn-* in base.css). Punctuation,

+// operators and plain names are left uncoloured on purpose -- a source line

+// with every token tinted reads as noise, not signal.

+func tokenClass(t chroma.TokenType) string {

+ switch {

+ case t.InCategory(chroma.Comment):

+ return "tok-c"

+ case t.InCategory(chroma.Keyword):

+ return "tok-k"

+ case t.InSubCategory(chroma.LiteralString):

+ return "tok-s"

+ case t.InSubCategory(chroma.LiteralNumber):

+ return "tok-n"

+ case t == chroma.NameFunction, t == chroma.NameFunctionMagic,

+ t == chroma.NameClass, t == chroma.NameNamespace,

+ t == chroma.NameBuiltin, t == chroma.NameBuiltinPseudo,

+ t == chroma.NameTag, t == chroma.NameDecorator:

+ return "tok-fn"

+ default:

+ return ""

+ }

+}

+package modules

+

+import (

+ "bytes"

+ "path"

+ "strings"

+)

+

+// maxPreviewSize bounds how large an image the blob view will render inline.

+// Past it the view keeps the download link but drops the preview, so a large

+// file is not pulled over the wire twice (once as the page's subresource,

+// once as the bytes the reader actually wanted). The /raw/ route itself is

+// not capped here: a direct request is an explicit request for the bytes,

+// and MaxGit still bounds every git read -- it must stay above this value or

+// a previewable-sized image would already be truncated by the time it gets

+// here.

+const maxPreviewSize = 10 << 20 // 10 MiB

+

+// imageContentType returns the MIME type to serve at p when its leading

+// bytes are that format and the extension agrees, and "" otherwise.

+//

+// SECURITY: this is the one place /raw/ is allowed to declare a non-text

+// Content-Type, so the rules are deliberately narrow:

+// - only raster formats are recognised. SVG is an XML document that can

+// carry <script>, so it is never in this list and keeps the text/plain

+// fallback; the danger is top-level navigation to an image/svg+xml

+// response on this origin, not <img>, where scripts do not run.

+// - the extension and the magic bytes must BOTH match, so an .png whose

+// contents are really HTML is not relabelled as an image. Relaxing the

+// current attachment rule for attacker-influenced bytes is only safe

+// because a mislabelled file fails here and keeps the download.

+// - the caller still sends X-Content-Type-Options: nosniff and the

+// sandbox CSP, so even a polyglot declared image/* cannot be re-sniffed

+// as a document.

+func imageContentType(p string, data []byte) string {

+ switch strings.ToLower(path.Ext(p)) {

+ case ".png":

+ if bytes.HasPrefix(data, []byte("\x89PNG\r\n\x1a\n")) {

+ return "image/png"

+ }

+ case ".jpg", ".jpeg":

+ if bytes.HasPrefix(data, []byte("\xff\xd8\xff")) {

+ return "image/jpeg"

+ }

+ case ".gif":

+ if bytes.HasPrefix(data, []byte("GIF87a")) || bytes.HasPrefix(data, []byte("GIF89a")) {

+ return "image/gif"

+ }

+ case ".webp":

+ if len(data) >= 12 && bytes.Equal(data[:4], []byte("RIFF")) &&

+ bytes.Equal(data[8:12], []byte("WEBP")) {

+ return "image/webp"

+ }

+ case ".bmp":

+ if bytes.HasPrefix(data, []byte("BM")) {

+ return "image/bmp"

+ }

+ case ".ico":

+ if bytes.HasPrefix(data, []byte("\x00\x00\x01\x00")) {

+ return "image/x-icon"

+ }

+ case ".avif":

+ // ISO-BMFF: "ftyp" at offset 4, major brand avif/avis at 8. A file

+ // with a compatible-but-not-major avif brand is left unlabelled

+ // rather than guessed at.

+ if len(data) >= 12 && bytes.Equal(data[4:8], []byte("ftyp")) &&

+ (bytes.Equal(data[8:12], []byte("avif")) || bytes.Equal(data[8:12], []byte("avis"))) {

+ return "image/avif"

+ }

+ }

+ return ""

+}

+package modules

+

+import "testing"

+

+// A file only earns an inline image MIME when its extension and its magic

+// bytes agree and the format is a raster one. The cases that must return ""

+// are the attacker-influenced ones: content that is not an image at all, and

+// SVG, which is an active document rather than a picture.

+func TestImageContentType(t *testing.T) {

+ png := []byte("\x89PNG\r\n\x1a\n" + "rest of the file")

+ tests := []struct {

+ name string

+ path string

+ data []byte

+ want string

+ }{

+ {"png", "logo.png", png, "image/png"},

+ {"uppercase extension", "LOGO.PNG", png, "image/png"},

+ {"jpeg", "a.jpg", []byte{0xff, 0xd8, 0xff, 0xe0}, "image/jpeg"},

+ {"jpeg long extension", "a.jpeg", []byte{0xff, 0xd8, 0xff, 0xe0}, "image/jpeg"},

+ {"gif87", "a.gif", []byte("GIF87a...."), "image/gif"},

+ {"gif89", "a.gif", []byte("GIF89a...."), "image/gif"},

+ {"webp", "a.webp", []byte("RIFF\x00\x00\x00\x00WEBPVP8 "), "image/webp"},

+ {"bmp", "a.bmp", []byte("BM...."), "image/bmp"},

+ {"ico", "a.ico", []byte{0x00, 0x00, 0x01, 0x00}, "image/x-icon"},

+ {"avif", "a.avif", []byte("\x00\x00\x00\x18ftypavif"), "image/avif"},

+

+ // HTML wearing a .png name, and a real PNG named .txt, must both

+ // fall back to the download path.

+ {"html named png", "evil.png", []byte("<html><script>x</script>"), ""},

+ {"png extension without magic", "evil.png", []byte("not an image"), ""},

+ {"magic without extension", "evil.txt", png, ""},

+ {"truncated png", "evil.png", []byte("\x89PNG"), ""},

+

+ // SVG can carry <script> and would be stored XSS if served as a

+ // document on this origin, so it is never recognised here.

+ {"svg", "evil.svg", []byte(`<svg xmlns="http://www.w3.org/2000/svg"><script/></svg>`), ""},

+ {"no extension", "Makefile", []byte("all:\n"), ""},

+ }

+ for _, tc := range tests {

+ if got := imageContentType(tc.path, tc.data); got != tc.want {

+ t.Errorf("%s: imageContentType(%q) = %q, want %q", tc.name, tc.path, got, tc.want)

+ }

+ }

+}

+

+// The blob view only renders a preview for a validated raster image, and

+// only while it is under the size cap; both facts are what tell the view

+// whether to show an <img>, a download notice, or numbered bytes.

+func TestImageBlobPreview(t *testing.T) {

+ png := append([]byte("\x89PNG\r\n\x1a\n"), make([]byte, 64)...)

+ big := append([]byte("\x89PNG\r\n\x1a\n"), make([]byte, maxPreviewSize)...)

+ c := blobCtx(t, map[string]string{

+ "logo.png": string(png),

+ "big.png": string(big),

+ "evil.png": "<html>not an image</html>",

+ })

+

+ b := blobAt(t, c, "logo.png")

+ if b.Image != "image/png" || !b.Preview() || !b.Binary {

+ t.Errorf("small image: Image=%q Preview=%v Binary=%v", b.Image, b.Preview(), b.Binary)

+ }

+ if b.PreviewLimit() != maxPreviewSize {

+ t.Errorf("PreviewLimit = %d, want %d", b.PreviewLimit(), maxPreviewSize)

+ }

+

+ bigBlob := blobAt(t, c, "big.png")

+ if bigBlob.Image != "image/png" {

+ t.Errorf("large image: Image = %q, want image/png", bigBlob.Image)

+ }

+ if bigBlob.Preview() {

+ t.Error("large image was previewed past the size cap")

+ }

+

+ // Not an image, so it keeps the plain binary path rather than a preview.

+ evil := blobAt(t, c, "evil.png")

+ if evil.Image != "" || evil.Preview() {

+ t.Errorf("misnamed html: Image=%q Preview=%v, want none", evil.Image, evil.Preview())

+ }

+}

+

+// /raw/ must declare the image MIME so the preview and direct navigation

+// render a picture, and must expose it through the interface core checks.

+func TestRawBlobInlineImage(t *testing.T) {

+ png := []byte("\x89PNG\r\n\x1a\n" + "body")

+ c := blobCtx(t, map[string]string{"logo.png": string(png)})

+ c.Path = "logo.png"

+ v, err := blobRawMod(c)

+ if err != nil {

+ t.Fatal(err)

+ }

+ r, ok := v.(RawBlob)

+ if !ok {

+ t.Fatalf("got %T", v)

+ }

+ if r.InlineContentType() != "image/png" {

+ t.Errorf("InlineContentType = %q, want image/png", r.InlineContentType())

+ }

+}

+ "gsg/internal/gitx"

+// LogPage is one page of commit history, with enough to render prev/next

+// links without a separate count query (see the n+1 fetch trick below).

+type LogPage struct {

+ Commits []gitx.Commit

+ Ofs, PageSize int

+ HasPrev, HasNext bool

+ PrevOfs, NextOfs int

+}

+

+// log: a page of recent commits. {{ mod "log" "20" }} -- default

+// core.LogPageSize, "0" = all. Paginated via the ?ofs= query param on the

+// log route (see buildCtx), which core.LogPageSize must match.

+ n := core.LogPageSize

+ ofs, _ := strconv.Atoi(c.Var("ofs"))

+ if ofs < 0 {

+ ofs = 0

+ }

+

+ fetch := n

+ if n > 0 {

+ fetch = n + 1 // one extra row to detect a next page

+ }

+ commits, err := c.Repo.Log(rev, fetch, ofs, true)

+ if err != nil {

+ return nil, err

+ }

+

+ page := LogPage{Ofs: ofs, PageSize: n, HasPrev: ofs > 0, PrevOfs: ofs - n}

+ if page.PrevOfs < 0 {

+ page.PrevOfs = 0

+ }

+ if n > 0 && len(commits) > n {

+ commits = commits[:n]

+ page.HasNext, page.NextOfs = true, ofs+n

+ }

+ page.Commits = commits

+ return page, nil

+ if log, err := c.Repo.Log(c.Ref, 1, 0, false); err == nil && len(log) > 0 {

+package modules

+

+import (

+ "gsg/internal/core"

+ "gsg/internal/notices"

+)

+

+func init() { core.Register("notices", noticesMod) }

+

+// notices: the site-wide banners followed by the ones for the repository

+// being viewed, in that order. Site-scoped routes (the index) build a Ctx

+// with c.Repo == nil and an empty Info.Slug, so this must never touch

+// c.Repo and must skip the repo half when Slug is empty. A nil default

+// store (the feature is off) is an empty list, not an error -- the

+// template uses modOr and guards on Immutable, so an empty list renders

+// nothing.

+func noticesMod(c *core.Ctx, args ...string) (any, error) {

+ st := notices.Default()

+ if st == nil {

+ return []notices.Notice(nil), nil

+ }

+ snap := st.Snapshot()

+ out := make([]notices.Notice, 0, len(snap.Doc.Global)+8)

+ out = append(out, snap.Doc.Global...)

+ if c.Info.Slug != "" {

+ out = append(out, snap.Doc.Repos[c.Info.Slug]...)

+ }

+ return out, nil

+}

+package modules

+

+import (

+ "html/template"

+ "os"

+ "path/filepath"

+ "strings"

+ "testing"

+

+ "gsg/internal/core"

+ "gsg/internal/notices"

+)

+

+// Global notices come before the repository's own; a site-scoped Ctx (nil

+// Repo, empty Slug) gets the global list only and must not panic.

+func TestNoticesModMergesGlobalThenRepo(t *testing.T) {

+ path := filepath.Join(t.TempDir(), "notices.yaml")

+ st, err := notices.Open(path)

+ if err != nil {

+ t.Fatal(err)

+ }

+ t.Cleanup(st.Close)

+ err = st.Set(notices.Document{

+ Global: []notices.Notice{{Type: notices.TypeCritical, Title: "global"}},

+ Repos: map[string][]notices.Notice{"demo": {{Type: notices.TypeInfo, Title: "repo"}}},

+ })

+ if err != nil {

+ t.Fatal(err)

+ }

+ notices.SetDefault(st)

+ t.Cleanup(func() { notices.SetDefault(nil) })

+

+ v, err := noticesMod(&core.Ctx{Info: core.RepoInfo{Slug: "demo"}})

+ if err != nil {

+ t.Fatal(err)

+ }

+ got, ok := v.([]notices.Notice)

+ if !ok {

+ t.Fatalf("notices returned %T", v)

+ }

+ if len(got) != 2 || got[0].Title != "global" || got[1].Title != "repo" {

+ t.Fatalf("got %+v", got)

+ }

+

+ v, err = noticesMod(&core.Ctx{})

+ if err != nil {

+ t.Fatal(err)

+ }

+ if got := v.([]notices.Notice); len(got) != 1 || got[0].Title != "global" {

+ t.Fatalf("site-scoped got %+v", got)

+ }

+}

+

+// The notices partial must render nothing on a page that will be cached

+// immutably, and must not even call the module there -- the guard wraps the

+// modOr call, not just its output.

+func TestNoticesPartialSuppressesImmutable(t *testing.T) {

+ src, err := os.ReadFile("../../templates/layouts/notices.html")

+ if err != nil {

+ t.Fatal(err)

+ }

+ calls := 0

+ tmpl, err := template.New("notices.html").Funcs(template.FuncMap{

+ "modOr": func(string, ...string) any {

+ calls++

+ return []notices.Notice{{Type: notices.TypeInfo, Title: "banner"}}

+ },

+ }).Parse(string(src))

+ if err != nil {

+ t.Fatal(err)

+ }

+ render := func(immutable bool) string {

+ var sb strings.Builder

+ if err := tmpl.ExecuteTemplate(&sb, "notices", struct{ Immutable bool }{immutable}); err != nil {

+ t.Fatal(err)

+ }

+ return sb.String()

+ }

+

+ got := render(true)

+ if strings.Contains(got, "banner") || calls != 0 {

+ t.Fatalf("immutable page rendered notices (calls=%d): %q", calls, got)

+ }

+ got = render(false)

+ if !strings.Contains(got, "banner") || calls != 1 {

+ t.Fatalf("non-immutable page did not render (calls=%d): %q", calls, got)

+ }

+}

+ // Same (rev, path) listing the `tree` module already computes for this

+ // page -- go through it instead of forking a second identical ls-tree.

+ v, err := c.Mod("tree")

+ t, ok := v.(Tree)

+ if !ok {

+ return nil, nil

+ }

+ for _, e := range t.Entries {

+ "sync"

+ "gsg/internal/access"

+// reposCacheTTL bounds how stale the index page's "last updated" ordering

+// and repo list can be. reposMod is site-scoped, so it never gets a

+// resolved commit and therefore never touches the module cache (see

+// Ctx.CacheKey) -- without this, every hit to "/" or the JSON index forks

+// git twice per repo, unconditionally, no matter how often the page is

+// requested. A few seconds of staleness here is the same trade-off the

+// fsnotify debounce already makes for repo discovery, just applied to one

+// more surface.

+const reposCacheTTL = 5 * time.Second

+

+var reposCache struct {

+ mu sync.Mutex

+ at time.Time

+ val []RepoSummary

+}

+

+// publicRepos returns every publicly-visible repository, newest activity

+// first, refreshed at most once per reposCacheTTL. This is the expensive,

+// I/O-bound part (one git log per repo) that the cache above exists for,

+// and it is deliberately untouched by personalization (see reposMod):

+// anonymous traffic -- the overwhelming majority of requests -- keeps

+// paying exactly what it paid before logins or share links existed,

+// regardless of how many hidden repos a site has.

+func publicRepos(c *core.Ctx) []RepoSummary {

+ reposCache.mu.Lock()

+ if !reposCache.at.IsZero() && time.Since(reposCache.at) < reposCacheTTL {

+ out := reposCache.val

+ reposCache.mu.Unlock()

+ return out

+ }

+ reposCache.mu.Unlock()

+

+ list := c.Site.RepoList()

+ out := make([]RepoSummary, 0, len(list))

+ for _, h := range list {

+ out = append(out, summarize(h))

+ }

+ sort.Slice(out, func(i, j int) bool { return out[i].LastCommit.After(out[j].LastCommit) })

+

+ reposCache.mu.Lock()

+ reposCache.val, reposCache.at = out, time.Now()

+ reposCache.mu.Unlock()

+ return out

+}

+

+func summarize(h core.Handle) RepoSummary {

+ s := RepoSummary{RepoInfo: h.Info}

+ if log, err := h.Repo.Log(h.Repo.HeadRef(), 1, 0, false); err == nil && len(log) > 0 {

+ s.LastCommit = log[0].When

+ }

+ return s

+}

+

+// repos: every repository visible to the requester, newest activity first

+// -- every public repo, plus any hidden repo the current identity is

+// allowed to see, whether as an owner (gsg.visible-to) or via an unrevoked

+// share grant. Site-scoped -- does not touch c.Repo, so it is safe on the

+// site Ctx.

+func reposMod(c *core.Ctx, args ...string) (any, error) {

+ base := publicRepos(c)

+ if c.User == "" && len(c.SharedSlugs) == 0 {

+ return base, nil

+ }

+

+ // Uncached and on-demand, by design: only the handful of hidden repos

+ // this specific identity unlocks, never a walk weighted by total

+ // hidden-repo count. Cost scales with how many repos one person can

+ // see, not with site size -- an owner (or share-link visitor) reloading

+ // "/" pays one git log per repo they can unlock, on every request (not

+ // cross-request-memoized), which is the trade-off for keeping

+ // publicRepos's shared cache above entirely free of personalization.

+ identity := access.Identity{

+ User: c.User,

+ SharedSlugs: c.SharedSlugs,

+ SharedIssuedAt: c.SharedIssuedAt,

+ }

+ var unlocked []RepoSummary

+ for _, h := range c.Site.RepoList() {

+ if !h.Info.Hidden {

+ continue

+ }

+ if h.Info.AccessPolicy().CanView(identity) {

+ unlocked = append(unlocked, summarize(h))

+ if len(unlocked) == 0 {

+ return base, nil

+ }

+

+ out := make([]RepoSummary, 0, len(base)+len(unlocked))

+ out = append(out, base...)

+ out = append(out, unlocked...)

+package modules

+

+import (

+ "bytes"

+ "encoding/json"

+ "html/template"

+ "regexp"

+ "sort"

+ "strconv"

+ "strings"

+

+ "gopkg.in/yaml.v3"

+)

+

+// ParseNote reports why a JSON/YAML blob failed to parse, so the blob view

+// can point at the offending line instead of leaving a reader to guess.

+// Line is 0 when the underlying error can't be pinned to one.

+type ParseNote struct {

+ Line int

+ Msg string

+}

+

+// Anchor is a YAML anchor declared on a line, along with how many alias

+// sites in the file point back at it.

+type Anchor struct {

+ Name string

+ Uses int

+}

+

+// StructRef is a resolved YAML alias: which anchor it names, the line that

+// anchor is declared on, and the value it stands for rendered back to YAML.

+// One per line -- a flow sequence like [*a, *b] resolves only its first.

+type StructRef struct {

+ Name string

+ Line int

+ Preview string

+}

+

+// maxStructuredSize bounds the work one file may cost the structured view:

+// a full parse on the server, and a pass over every row in the browser at

+// load. It matches maxHighlightSize on purpose -- past that point the file

+// is already served as plain, unhighlighted text with no indent guides, and

+// folding a file that has neither would be a strange half-feature. Half a

+// megabyte is far above any hand-written config and below the size where a

+// modest laptop notices the per-row work.

+const maxStructuredSize = maxHighlightSize

+

+// structuredLang returns "json" or "yaml" for a recognised config

+// extension, "" otherwise. The blob view only spends the extra parse and

+// indent-guide pass on formats where nesting depth is the whole point.

+func structuredLang(path string) string {

+ p := strings.ToLower(path)

+ switch {

+ case strings.HasSuffix(p, ".json"):

+ return "json"

+ case strings.HasSuffix(p, ".yaml"), strings.HasSuffix(p, ".yml"):

+ return "yaml"

+ default:

+ return ""

+ }

+}

+

+func validateStructured(lang string, raw []byte) *ParseNote {

+ var err error

+ switch lang {

+ case "json":

+ err = json.Unmarshal(raw, new(any))

+ case "yaml":

+ err = yaml.Unmarshal(raw, new(any))

+ default:

+ return nil

+ }

+ if err == nil {

+ return nil

+ }

+ return &ParseNote{Line: parseErrorLine(lang, raw, err), Msg: err.Error()}

+}

+

+var yamlLineRe = regexp.MustCompile(`line (\d+)`)

+

+func parseErrorLine(lang string, raw []byte, err error) int {

+ if lang == "json" {

+ switch e := err.(type) {

+ case *json.SyntaxError:

+ return bytes.Count(raw[:e.Offset], []byte("\n")) + 1

+ case *json.UnmarshalTypeError:

+ return bytes.Count(raw[:e.Offset], []byte("\n")) + 1

+ }

+ return 0

+ }

+ // yaml.v3 errors are plain strings of the form "yaml: line N: ...", or

+ // for TypeError one such string per bad field -- take the first.

+ if m := yamlLineRe.FindStringSubmatch(err.Error()); m != nil {

+ n, _ := strconv.Atoi(m[1])

+ return n

+ }

+ return 0

+}

+

+// indentUnit finds the smallest non-zero run of leading spaces across

+// non-blank lines, so a 4-space file gets one guide per level and a

+// 2-space file doesn't get a spurious extra one.

+func indentUnit(raw []byte) int {

+ unit := 0

+ for _, line := range bytes.Split(raw, []byte("\n")) {

+ n := 0

+ for n < len(line) && line[n] == ' ' {

+ n++

+ }

+ if n == 0 || n == len(line) {

+ continue // blank or all-whitespace

+ }

+ if unit == 0 || n < unit {

+ unit = n

+ }

+ }

+ if unit == 0 {

+ return 2

+ }

+ return unit

+}

+

+// annotateStructure fills in the per-line structure the blob view needs to

+// fold, filter and cross-reference a config file: nesting depth, the extent

+// of the block each line opens, the mapping key it declares, and (YAML only)

+// the anchors and aliases tying parts of the file together.

+//

+// It works off raw rather than the highlighted HTML: indentation is the one

+// signal that means the same thing in both languages, and it survives

+// minified or oddly-formatted input by simply finding nothing to fold.

+func annotateStructure(lines []Line, raw []byte, lang string) {

+ src := bytes.Split(raw, []byte("\n"))

+ unit := indentUnit(raw)

+

+ ind := make([]int, len(src))

+ for i, l := range src {

+ ind[i] = lineIndent(l)

+ }

+ ends := foldEnds(ind)

+

+ keyRe := jsonKeyRe

+ if lang == "yaml" {

+ keyRe = yamlKeyRe

+ }

+ for i := range src {

+ if i >= len(lines) {

+ break

+ }

+ if ind[i] >= 0 {

+ lines[i].Depth = ind[i] / unit

+ if e := ends[i]; e > 0 && e <= len(lines) {

+ lines[i].FoldTo = e

+ }

+ }

+ if m := keyRe.FindSubmatch(src[i]); m != nil {

+ for _, g := range m[1:] {

+ if len(g) > 0 {

+ lines[i].Key = string(g)

+ break

+ }

+ }

+ }

+ }

+ if lang != "yaml" {

+ annotateJSONPaths(lines, raw)

+ return

+ }

+ anchors, refs, paths := yamlAnnotations(src)

+ for n, a := range anchors {

+ if n >= 1 && n <= len(lines) {

+ lines[n-1].Anchor = a

+ }

+ }

+ for n, r := range refs {

+ if n >= 1 && n <= len(lines) {

+ lines[n-1].Ref = r

+ }

+ }

+ for n, p := range paths {

+ if n >= 1 && n <= len(lines) {

+ lines[n-1].Path = p

+ }

+ }

+}

+

+// lineIndent counts leading spaces, or returns -1 for a line that carries no

+// structure (blank or whitespace-only) so folding steps over it rather than

+// treating column 0 as a dedent.

+func lineIndent(line []byte) int {

+ n := 0

+ for n < len(line) && line[n] == ' ' {

+ n++

+ }

+ if n == len(bytes.TrimRight(line, " \t\r")) {

+ return -1

+ }

+ return n

+}

+

+// foldEnds returns, per line, the 1-based number of the last line belonging

+// to the block that line opens -- 0 when it opens nothing. A line opens a

+// block when the next line carrying structure is indented further, and the

+// block runs until indentation returns to that line's own level or less.

+// Blank lines between siblings are absorbed; blank lines trailing a block

+// are not.

+func foldEnds(ind []int) []int {

+ ends := make([]int, len(ind))

+ type frame struct {

+ ind, idx int

+ child bool

+ }

+ var stack []frame

+ prev := -1 // last line carrying structure

+ for i, in := range ind {

+ if in < 0 {

+ continue

+ }

+ for len(stack) > 0 && stack[len(stack)-1].ind >= in {

+ if t := stack[len(stack)-1]; t.child {

+ ends[t.idx] = prev + 1

+ }

+ stack = stack[:len(stack)-1]

+ }

+ if len(stack) > 0 {

+ stack[len(stack)-1].child = true

+ }

+ stack = append(stack, frame{ind: in, idx: i})

+ prev = i

+ }

+ for _, t := range stack {

+ if t.child {

+ ends[t.idx] = prev + 1

+ }

+ }

+ return ends

+}

+

+var (

+ // The key a line declares, used to scope search to keys rather than

+ // whole lines. Both are deliberately shallow: a miss costs a narrower

+ // search, not a wrong render.

+ yamlKeyRe = regexp.MustCompile(`^\s*(?:-\s+)?(?:"([^"]*)"|'([^']*)'|([^\s#"'][^:#]*?))\s*:(?:\s|$)`)

+ jsonKeyRe = regexp.MustCompile(`^\s*"((?:[^"\\]|\\.)*)"\s*:`)

+)

+

+// yamlAnnotations resolves every alias in the file to the line its anchor is

+// declared on, keyed by 1-based line number, and records each line's

+// canonical value path. Anchors are per-document, so the whole stream is

+// decoded document by document -- a k8s manifest that defines its anchors in

+// the second document would otherwise come back empty. A malformed document

+// ends the walk with whatever was found first; the parse-error banner

+// already reports the failure itself.

+func yamlAnnotations(src [][]byte) (map[int]*Anchor, map[int]*StructRef, map[int]string) {

+ anchors := map[int]*Anchor{}

+ refs := map[int]*StructRef{}

+ paths := map[int]string{}

+ dec := yaml.NewDecoder(bytes.NewReader(bytes.Join(src, []byte("\n"))))

+ for {

+ var doc yaml.Node

+ if err := dec.Decode(&doc); err != nil {

+ break

+ }

+ walkYAML(&doc, src, anchors, refs, paths, "")

+ }

+ return anchors, refs, paths

+}

+

+func walkYAML(n *yaml.Node, src [][]byte, anchors map[int]*Anchor, refs map[int]*StructRef, paths map[int]string, path string) {

+ if n.Anchor != "" {

+ if line := anchorLine(src, n.Anchor, n.Line); line > 0 {

+ if _, ok := anchors[line]; !ok {

+ anchors[line] = &Anchor{Name: n.Anchor}

+ }

+ }

+ }

+ if n.Kind == yaml.AliasNode && n.Alias != nil {

+ target := anchorLine(src, n.Value, n.Alias.Line)

+ if target > 0 {

+ if _, ok := refs[n.Line]; !ok {

+ refs[n.Line] = &StructRef{Name: n.Value, Line: target, Preview: nodePreview(n.Alias)}

+ }

+ if a, ok := anchors[target]; ok {

+ a.Uses++

+ }

+ }

+ // An alias displays only *name here; the aliased value's lines are

+ // wherever the anchor was declared. Recursing into n.Alias would

+ // emit paths pointing at those other lines, so record this line's

+ // path and stop.

+ recordPath(paths, n.Line, path)

+ return

+ }

+

+ switch n.Kind {

+ case yaml.DocumentNode:

+ for _, c := range n.Content {

+ walkYAML(c, src, anchors, refs, paths, path)

+ }

+ case yaml.MappingNode:

+ for i := 0; i+1 < len(n.Content); i += 2 {

+ k, v := n.Content[i], n.Content[i+1]

+ child := joinPath(path, k.Value)

+ if k.Value == "<<" {

+ // A merge key is not a property of the mapping, and the

+ // rendered text never expands it, so a `<<` segment would

+ // name something the reader cannot see. Keep the parent.

+ child = path

+ }

+ // Walk the key too (anchors may be declared on one), but record

+ // the value's path last so it wins for the shared line.

+ walkYAML(k, src, anchors, refs, paths, path)

+ recordPath(paths, k.Line, child)

+ walkYAML(v, src, anchors, refs, paths, child)

+ }

+ case yaml.SequenceNode:

+ for i, c := range n.Content {

+ child := joinIndex(path, i)

+ recordPath(paths, c.Line, child)

+ walkYAML(c, src, anchors, refs, paths, child)

+ }

+ default:

+ recordPath(paths, n.Line, path)

+ }

+}

+

+// anchorLine locates the line the "&name" token sits on. A node's own Line

+// is where its *value* begins, which for a block mapping is the line after

+// the key the anchor was written on -- so scan back from there for the

+// token itself and point at that instead.

+func anchorLine(src [][]byte, name string, at int) int {

+ tok := []byte("&" + name)

+ if at > len(src) {

+ at = len(src)

+ }

+ for i := at - 1; i >= 0 && i > at-64; i-- {

+ j := bytes.Index(src[i], tok)

+ if j < 0 {

+ continue

+ }

+ if k := j + len(tok); k < len(src[i]) && isAnchorChar(src[i][k]) {

+ continue // &namelonger

+ }

+ return i + 1

+ }

+ return 0

+}

+

+func isAnchorChar(b byte) bool {

+ return b == '-' || b == '_' || b == '.' ||

+ (b >= '0' && b <= '9') || (b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z')

+}

+

+// nodePreview renders what an alias actually stands for, short enough to sit

+// in a tooltip. The anchor name is stripped from the copy so the preview

+// reads as the value, not as its declaration.

+func nodePreview(n *yaml.Node) string {

+ c := *n

+ c.Anchor = ""

+ var buf bytes.Buffer

+ enc := yaml.NewEncoder(&buf)

+ enc.SetIndent(2) // yaml.Marshal's default of 4 doesn't match most files

+ if err := enc.Encode(&c); err != nil {

+ return ""

+ }

+ enc.Close()

+ s := strings.TrimRight(buf.String(), "\n")

+ if ls := strings.Split(s, "\n"); len(ls) > 12 {

+ s = strings.Join(append(ls[:12], "…"), "\n")

+ }

+ if len(s) > 480 {

+ s = strings.ToValidUTF8(s[:480], "") + "…"

+ }

+ return s

+}

+

+// withIndentGuides prefixes each line's leading spaces with one guide span

+// per nesting level, so deeply nested JSON/YAML reads like a tree instead

+// of a wall of spaces. Leading whitespace is always plain, unwrapped text

+// at this point (see highlightLines' Text/TextWhitespace handling), so

+// trimming it back off the rendered HTML here is safe.

+func withIndentGuides(lines []template.HTML, unit int) []template.HTML {

+ out := make([]template.HTML, len(lines))

+ for i, l := range lines {

+ s := string(l)

+ n := 0

+ for n < len(s) && s[n] == ' ' {

+ n++

+ }

+ if n < unit {

+ out[i] = l

+ continue

+ }

+ var b strings.Builder

+ levels, rem := n/unit, n%unit

+ for j := 0; j < levels; j++ {

+ b.WriteString(`<span class="ind" style="width:`)

+ b.WriteString(strconv.Itoa(unit))

+ b.WriteString(`ch"></span>`)

+ }

+ if rem > 0 {

+ b.WriteString(strings.Repeat(" ", rem))

+ }

+ b.WriteString(s[n:])

+ out[i] = template.HTML(b.String())

+ }

+ return out

+}

+

+// --------------------------------------------------------------- paths

+

+// A path query names a value the way obj1.property3.items[4].val does.

+// Both the server (here) and static/js/structured.js write the same

+// canonical form so a query can be compared as a string: simple keys are

+// dotted, indices attach directly, and anything else is bracket-quoted.

+var (

+ simplePathKey = regexp.MustCompile(`^[A-Za-z0-9_$-]+$`)

+ pathEscaper = strings.NewReplacer(`\`, `\\`, `"`, `\"`)

+)

+

+func joinPath(parent, key string) string {

+ if simplePathKey.MatchString(key) {

+ if parent == "" {

+ return key

+ }

+ return parent + "." + key

+ }

+ return parent + `["` + pathEscaper.Replace(key) + `"]`

+}

+

+func joinIndex(parent string, i int) string {

+ return parent + "[" + strconv.Itoa(i) + "]"

+}

+

+// recordPath keeps the last path recorded for a line. A line can carry more

+// than one path (JSON/YAML flow style puts several values on one row), and

+// the last one parsed is the deepest -- the one a reader naming a full path

+// is most likely to mean. A container query still reaches its children by

+// the boundary-aware prefix match in structured.js, so dropping the shallow

+// path costs nothing there.

+func recordPath(paths map[int]string, line int, path string) {

+ if path == "" || line <= 0 {

+ return

+ }

+ paths[line] = path

+}

+

+// annotateJSONPaths records each line's canonical value path. It reuses

+// encoding/json's own decoder rather than a second parser, so the offsets it

+// sees are exactly the ones the format defines.

+func annotateJSONPaths(lines []Line, raw []byte) {

+ paths := jsonPaths(raw)

+ for i := range lines {

+ if p, ok := paths[lines[i].N]; ok {

+ lines[i].Path = p

+ }

+ }

+}

+

+func jsonPaths(raw []byte) map[int]string {

+ paths := map[int]string{}

+ lineOf := newLineIndex(raw)

+ dec := json.NewDecoder(bytes.NewReader(raw))

+

+ // walk consumes one JSON value at path. Objects record the path on the

+ // key's line and recurse into the value; arrays record it on each

+ // element's line. A malformed document simply stops -- the parse-error

+ // banner owns reporting that.

+ var walk func(path string)

+ walk = func(path string) {

+ tok, err := dec.Token()

+ if err != nil {

+ return

+ }

+ recordPath(paths, lineOf(dec.InputOffset()), path)

+ d, ok := tok.(json.Delim)

+ if !ok {

+ return

+ }

+ switch d {

+ case '{':

+ for dec.More() {

+ kt, err := dec.Token()

+ if err != nil {

+ return

+ }

+ key, _ := kt.(string)

+ child := joinPath(path, key)

+ recordPath(paths, lineOf(dec.InputOffset()), child)

+ walk(child)

+ }

+ dec.Token() // consume '}'

+ case '[':

+ for i := 0; dec.More(); i++ {

+ walk(joinIndex(path, i))

+ }

+ dec.Token() // consume ']'

+ }

+ }

+ walk("")

+ return paths

+}

+

+// newLineIndex maps a byte offset to a 1-based line number. Newline

+// positions are found once and binary-searched per token, so indexing a

+// whole file stays O(n log n) rather than counting from zero each time.

+func newLineIndex(raw []byte) func(int64) int {

+ var newlines []int64

+ for i, b := range raw {

+ if b == '\n' {

+ newlines = append(newlines, int64(i))

+ }

+ }

+ return func(off int64) int {

+ return sort.Search(len(newlines), func(i int) bool { return newlines[i] >= off }) + 1

+ }

+}

+package modules

+

+import (

+ "html/template"

+ "strings"

+ "testing"

+)

+

+// lines builds the Line slice annotateStructure expects, mirroring what

+// blobMod produces before the structure pass runs.

+func lines(raw string) []Line {

+ out := []Line{}

+ for i, t := range strings.Split(raw, "\n") {

+ out = append(out, Line{N: i + 1, Text: template.HTML(t)})

+ }

+ return out

+}

+

+const sampleYAML = `defaults: &defaults

+ adapter: postgres

+ pool: 5

+

+development:

+ <<: *defaults

+ database: dev

+

+test:

+ <<: *defaults

+ database: test

+ hosts:

+ - a

+ - b

+`

+

+func TestFoldRangesYAML(t *testing.T) {

+ ls := lines(sampleYAML)

+ annotateStructure(ls, []byte(sampleYAML), "yaml")

+

+ want := map[int]int{

+ 1: 3, // defaults: block ends at "pool: 5", not the blank line after

+ 5: 7, // development:

+ 9: 14, // test:, stopping short of the empty line 15

+ 12: 14, // hosts:

+ }

+ for _, l := range ls {

+ if got, ok := want[l.N]; ok {

+ if l.FoldTo != got {

+ t.Errorf("line %d: FoldTo = %d, want %d", l.N, l.FoldTo, got)

+ }

+ } else if l.FoldTo != 0 {

+ t.Errorf("line %d: FoldTo = %d, want none", l.N, l.FoldTo)

+ }

+ }

+ if ls[1].Depth != 1 {

+ t.Errorf("line 2 depth = %d, want 1", ls[1].Depth)

+ }

+ if ls[13].Depth != 2 {

+ t.Errorf("line 14 depth = %d, want 2", ls[13].Depth)

+ }

+}

+

+func TestKeysAndAnchors(t *testing.T) {

+ ls := lines(sampleYAML)

+ annotateStructure(ls, []byte(sampleYAML), "yaml")

+

+ if ls[0].Key != "defaults" {

+ t.Errorf("line 1 key = %q, want %q", ls[0].Key, "defaults")

+ }

+ if ls[13].Key != "" {

+ t.Errorf("line 14 (sequence item) key = %q, want none", ls[13].Key)

+ }

+

+ // The anchor is reported on the line the &token is written on, not on

+ // the line the mapping it names begins.

+ a := ls[0].Anchor

+ if a == nil {

+ t.Fatal("line 1: no anchor")

+ }

+ if a.Name != "defaults" || a.Uses != 2 {

+ t.Errorf("anchor = %+v, want {defaults 2}", *a)

+ }

+

+ for _, n := range []int{6, 10} {

+ r := ls[n-1].Ref

+ if r == nil {

+ t.Fatalf("line %d: no ref", n)

+ }

+ if r.Name != "defaults" || r.Line != 1 {

+ t.Errorf("line %d ref = %+v, want defaults@1", n, *r)

+ }

+ if !strings.Contains(r.Preview, "adapter: postgres") {

+ t.Errorf("line %d preview = %q, want the resolved mapping", n, r.Preview)

+ }

+ }

+}

+

+// Anchors defined in the second document of a stream are still resolved:

+// yaml.Unmarshal would only ever see the first.

+func TestMultiDocumentAnchors(t *testing.T) {

+ const src = `---

+kind: First

+---

+base: &b

+ x: 1

+copy: *b

+`

+ ls := lines(src)

+ annotateStructure(ls, []byte(src), "yaml")

+

+ if ls[3].Anchor == nil || ls[3].Anchor.Name != "b" {

+ t.Fatalf("line 4 anchor = %+v, want b", ls[3].Anchor)

+ }

+ if r := ls[5].Ref; r == nil || r.Line != 4 {

+ t.Fatalf("line 6 ref = %+v, want b@4", r)

+ }

+}

+

+func TestFoldRangesJSON(t *testing.T) {

+ const src = `{

+ "name": "gsg",

+ "deps": {

+ "a": 1

+ },

+ "list": [

+ 2

+ ]

+}`

+ ls := lines(src)

+ annotateStructure(ls, []byte(src), "json")

+

+ if ls[0].FoldTo != 8 {

+ t.Errorf("line 1 FoldTo = %d, want 8", ls[0].FoldTo)

+ }

+ if ls[2].FoldTo != 4 {

+ t.Errorf("line 3 FoldTo = %d, want 4", ls[2].FoldTo)

+ }

+ if ls[5].FoldTo != 7 {

+ t.Errorf("line 6 FoldTo = %d, want 7", ls[5].FoldTo)

+ }

+ if ls[1].Key != "name" {

+ t.Errorf("line 2 key = %q, want %q", ls[1].Key, "name")

+ }

+ // No anchors outside YAML, and a brace inside a string is not structure.

+ if ls[1].Anchor != nil || ls[1].Ref != nil {

+ t.Error("JSON line carries anchor/ref data")

+ }

+}

+

+// Minified JSON has no indentation to fold on; it must degrade to a plain

+// view rather than producing bogus ranges.

+func TestMinifiedJSONHasNoFolds(t *testing.T) {

+ const src = `{"a":{"b":[1,2]},"c":3}`

+ ls := lines(src)

+ annotateStructure(ls, []byte(src), "json")

+ if ls[0].FoldTo != 0 {

+ t.Errorf("FoldTo = %d, want 0", ls[0].FoldTo)

+ }

+}

+

+// Nested arrays of objects are the shape a path query like

+// obj1.property3.items[4].val is written against.

+func TestJSONPaths(t *testing.T) {

+ const src = `{

+ "obj1": {

+ "property3": {

+ "items": [

+ {

+ "val": 0

+ },

+ {

+ "val": 1

+ }

+ ]

+ }

+ }

+}`

+ ls := lines(src)

+ annotateStructure(ls, []byte(src), "json")

+

+ want := map[int]string{

+ 2: "obj1",

+ 3: "obj1.property3",

+ 4: "obj1.property3.items",

+ 5: "obj1.property3.items[0]",

+ 6: "obj1.property3.items[0].val",

+ 8: "obj1.property3.items[1]",

+ 9: "obj1.property3.items[1].val",

+ }

+ for _, l := range ls {

+ if got, ok := want[l.N]; ok {

+ if l.Path != got {

+ t.Errorf("line %d Path = %q, want %q", l.N, l.Path, got)

+ }

+ } else if l.Path != "" {

+ t.Errorf("line %d Path = %q, want none", l.N, l.Path)

+ }

+ }

+}

+

+// A flow-style row carries several paths at once; the deepest is kept, so

+// a query naming the final member still resolves. The shallow ones stay

+// reachable when a container query prefix-matches the deep path.

+func TestJSONFlowPathKeepsDeepest(t *testing.T) {

+ const src = `{"a": {"b": 1}}`

+ ls := lines(src)

+ annotateStructure(ls, []byte(src), "json")

+ if ls[0].Path != "a.b" {

+ t.Errorf("Path = %q, want a.b", ls[0].Path)

+ }

+}

+

+func TestYAMLPaths(t *testing.T) {

+ ls := lines(sampleYAML)

+ annotateStructure(ls, []byte(sampleYAML), "yaml")

+

+ want := map[int]string{

+ 1: "defaults",

+ 2: "defaults.adapter",

+ 3: "defaults.pool",

+ 5: "development",

+ 6: "development", // merge key keeps the parent path

+ 7: "development.database",

+ 9: "test",

+ 10: "test",

+ 11: "test.database",

+ 12: "test.hosts",

+ 13: "test.hosts[0]",

+ 14: "test.hosts[1]",

+ }

+ for _, l := range ls {

+ if got, ok := want[l.N]; ok {

+ if l.Path != got {

+ t.Errorf("line %d Path = %q, want %q", l.N, l.Path, got)

+ }

+ } else if l.Path != "" {

+ t.Errorf("line %d Path = %q, want none", l.N, l.Path)

+ }

+ }

+}

+

+func TestYAMLSequenceOfMappingsPaths(t *testing.T) {

+ const src = `obj1:

+ property3:

+ items:

+ - val: 0

+ - val: 1

+`

+ ls := lines(src)

+ annotateStructure(ls, []byte(src), "yaml")

+ if ls[3].Path != "obj1.property3.items[0].val" {

+ t.Errorf("line 4 Path = %q", ls[3].Path)

+ }

+ if ls[4].Path != "obj1.property3.items[1].val" {

+ t.Errorf("line 5 Path = %q", ls[4].Path)

+ }

+}

+

+func TestPathKeyQuoting(t *testing.T) {

+ tests := []struct{ parent, key, want string }{

+ {"", "obj1", "obj1"},

+ {"obj1", "items", "obj1.items"},

+ {"obj1", "a.b", `obj1["a.b"]`},

+ {"", "weird key", `["weird key"]`},

+ {"obj1", `quo"te`, `obj1["quo\"te"]`},

+ }

+ for _, tc := range tests {

+ if got := joinPath(tc.parent, tc.key); got != tc.want {

+ t.Errorf("joinPath(%q, %q) = %q, want %q", tc.parent, tc.key, got, tc.want)

+ }

+ }

+ if got := joinIndex("obj1.items", 4); got != "obj1.items[4]" {

+ t.Errorf("joinIndex = %q", got)

+ }

+}

+<!doctype html>

+<html lang="en">

+<head>

+<meta charset="utf-8">

+<meta name="viewport" content="width=device-width, initial-scale=1">

+<title>Notices &middot; {{ .Site }}</title>

+<link rel="stylesheet" href="/static/css/base.css">

+<link rel="stylesheet" href="/static/css/admin.css">

+<script src="/static/js/admin.js" defer></script>

+</head>

+<body>

+<main class="wrap">

+ <header class="hero">

+ <h1 class="page-title">Notices</h1>

+ <p class="page-subtitle">Global notices render above every repository's.</p>

+ </header>

+

+ {{ if .Saved }}<div class="notice notice-fix">Saved.</div>{{ end }}

+ {{ if .Error }}<div class="notice notice-critical">

+ <strong class="notice-title">Not saved</strong>

+ <pre class="notice-body">{{ .Error }}</pre>

+ </div>{{ end }}

+

+ <form method="post" action="/admin/notices" class="admin-form">

+ <input type="hidden" name="csrf" value="{{ .CSRF }}">

+ <div class="table-wrap">

+ <table class="table admin-table">

+ <thead>

+ <tr>

+ <th>Scope</th><th>Type</th><th>Title</th><th>Body</th>

+ <th>Link</th><th>Link text</th><th>Remove</th>

+ </tr>

+ </thead>

+ <tbody>

+ {{ range $i, $row := .Rows }}

+ <tr>

+ <td><select name="scope">

+ <option value="global"{{ if eq $row.Scope "global" }} selected{{ end }}>global</option>

+ {{ range $.Repos }}<option value="{{ . }}"{{ if eq $row.Scope . }} selected{{ end }}>{{ . }}</option>{{ end }}

+ </select></td>

+ <td><select name="type">

+ <option value="critical"{{ if eq $row.Type "critical" }} selected{{ end }}>critical</option>

+ <option value="warning"{{ if eq $row.Type "warning" }} selected{{ end }}>warning</option>

+ <option value="info"{{ if eq $row.Type "info" }} selected{{ end }}>info</option>

+ <option value="fix"{{ if eq $row.Type "fix" }} selected{{ end }}>fix</option>

+ </select></td>

+ <td><input name="title" value="{{ $row.Title }}"></td>

+ <td><textarea name="body" rows="2">{{ $row.Body }}</textarea></td>

+ <td><input name="link" value="{{ $row.Link }}"></td>

+ <td><input name="link_text" value="{{ $row.LinkText }}"></td>

+ <td class="admin-del"><input type="checkbox" name="del" value="{{ $i }}"></td>

+ </tr>

+ {{ end }}

+ </tbody>

+ </table>

+ </div>

+ <p class="admin-actions">

+ <button class="chip admin-save" type="submit">Save notices</button>

+ <button class="chip js-only" type="button" id="add-notice">Add notice</button>

+ </p>

+ </form>

+</main>

+</body>

+</html>

+package notices

+

+import (

+ "crypto/rand"

+ "crypto/subtle"

+ "embed"

+ "encoding/hex"

+ "fmt"

+ "html/template"

+ "log/slog"

+ "net/http"

+ "sort"

+ "strconv"

+ "strings"

+

+ "gsg/internal/httpx"

+)

+

+//go:embed admin.html

+var adminFS embed.FS

+

+// HandlerConfig is everything the admin surface needs that this package

+// cannot discover for itself. Repos is the visible repository list, used to

+// populate the scope dropdown.

+type HandlerConfig struct {

+ Store *Store

+ Repos []string

+ SiteName string

+ UserHeader string // e.g. "X-Authentik-Username"; logging only, never authz

+

+ // GroupHeader and RequiredGroup gate the admin surface itself, on top of

+ // whatever authentication the reverse proxy already did. Authentik's

+ // forward_auth can be shared by every /admin/* route (so several people

+ // can log in for share links), while only members of RequiredGroup may

+ // reach notices editing. RequiredGroup empty disables the check -- every

+ // request that reaches this handler is authorized, i.e. today's

+ // behavior. GroupHeader defaults to "X-Authentik-Groups", which

+ // Authentik sends as a "|"-delimited list of the user's groups.

+ GroupHeader string

+ RequiredGroup string

+

+ Logger *slog.Logger

+}

+

+type adminRow struct {

+ Scope, Type, Title, Body, Link, LinkText string

+}

+

+type adminView struct {

+ Site, CSRF, Error string

+ Saved bool

+ Repos []string

+ Rows []adminRow

+}

+

+const (

+ csrfCookie = "gsg_admin_csrf"

+ maxFormBytes = 1 << 20

+)

+

+type handler struct {

+ cfg HandlerConfig

+ tmpl *template.Template

+}

+

+// NewHandler builds the admin mux. It is deliberately separate from the

+// read-only server: the only write path in gsg lives here, and it writes a

+// config file, never a repository.

+func NewHandler(cfg HandlerConfig) (http.Handler, error) {

+ if cfg.Store == nil {

+ return nil, fmt.Errorf("notices admin: no store")

+ }

+ if cfg.Logger == nil {

+ cfg.Logger = slog.Default()

+ }

+ if cfg.UserHeader == "" {

+ cfg.UserHeader = "X-Authentik-Username"

+ }

+ if cfg.GroupHeader == "" {

+ cfg.GroupHeader = "X-Authentik-Groups"

+ }

+ tmpl, err := template.ParseFS(adminFS, "admin.html")

+ if err != nil {

+ return nil, fmt.Errorf("notices admin template: %w", err)

+ }

+ h := &handler{cfg: cfg, tmpl: tmpl}

+

+ mux := http.NewServeMux()

+ // Method-qualified patterns: anything else (PUT, DELETE, or a stray

+ // GET/POST to another path) is refused by the mux, not silently handled.

+ mux.HandleFunc("GET /admin/{$}", h.index)

+ mux.HandleFunc("GET /admin/notices", h.get)

+ mux.HandleFunc("POST /admin/notices", h.post)

+

+ if cfg.RequiredGroup == "" {

+ return mux, nil

+ }

+ return h.requireGroup(mux), nil

+}

+

+// requireGroup wraps next so that every admin route first checks

+// RequiredGroup, before any handler runs (including the CSRF cookie setup

+// in get/index -- a rejected caller gets no state from this handler at

+// all). Authentication already happened upstream at the reverse proxy; this

+// is authorization on top of it, using a group claim the proxy forwards, so

+// that reaching the (shared) /admin/* forward_auth is not by itself enough

+// to edit notices.

+func (h *handler) requireGroup(next http.Handler) http.Handler {

+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

+ if !h.inRequiredGroup(r) {

+ h.cfg.Logger.Warn("notices admin: group check rejected",

+ "user", r.Header.Get(h.cfg.UserHeader),

+ "groups", r.Header.Get(h.cfg.GroupHeader))

+ http.Error(w, "forbidden", http.StatusForbidden)

+ return

+ }

+ next.ServeHTTP(w, r)

+ })

+}

+

+// inRequiredGroup reports whether r carries cfg.RequiredGroup in its

+// GroupHeader. Authentik delimits multiple groups with "|"; entries are

+// trimmed so incidental whitespace around the delimiter doesn't cause a

+// false negative.

+func (h *handler) inRequiredGroup(r *http.Request) bool {

+ for _, g := range strings.Split(r.Header.Get(h.cfg.GroupHeader), "|") {

+ if strings.TrimSpace(g) == h.cfg.RequiredGroup {

+ return true

+ }

+ }

+ return false

+}

+

+func (h *handler) index(w http.ResponseWriter, r *http.Request) {

+ http.Redirect(w, r, "/admin/notices", http.StatusSeeOther)

+}

+

+func (h *handler) get(w http.ResponseWriter, r *http.Request) {

+ httpx.Secure(w, httpx.SecureOptions{ScriptSrc: "'self'"})

+ tok, err := ensureCSRF(w, r)

+ if err != nil {

+ http.Error(w, "cannot start session", http.StatusInternalServerError)

+ return

+ }

+ h.render(w, http.StatusOK, tok, "", r.URL.Query().Get("saved") == "1")

+}

+

+func (h *handler) post(w http.ResponseWriter, r *http.Request) {

+ httpx.Secure(w, httpx.SecureOptions{ScriptSrc: "'self'"})

+

+ // Header checks first: they need no body. Then bound and parse the

+ // body, then compare the CSRF token against the cookie. Parsing before

+ // the token check is safe because the read is capped.

+ if !httpx.SameOrigin(r) {

+ h.cfg.Logger.Warn("notices admin: origin rejected",

+ "host", r.Host, "origin", r.Header.Get("Origin"),

+ "sec-fetch-site", r.Header.Get("Sec-Fetch-Site"))

+ http.Error(w, "forbidden", http.StatusForbidden)

+ return

+ }

+ r.Body = http.MaxBytesReader(w, r.Body, maxFormBytes)

+ if err := r.ParseForm(); err != nil {

+ http.Error(w, "bad form", http.StatusBadRequest)

+ return

+ }

+ if !checkCSRF(r) {

+ h.cfg.Logger.Warn("notices admin: csrf rejected",

+ "user", r.Header.Get(h.cfg.UserHeader))

+ http.Error(w, "forbidden", http.StatusForbidden)

+ return

+ }

+

+ doc, err := docFromForm(r)

+ if err == nil {

+ err = h.cfg.Store.Set(doc)

+ }

+ if err != nil {

+ tok, _ := ensureCSRF(w, r)

+ h.render(w, http.StatusBadRequest, tok, err.Error(), false)

+ return

+ }

+

+ h.cfg.Logger.Info("notices updated",

+ "user", r.Header.Get(h.cfg.UserHeader),

+ "global", len(doc.Global), "repos", len(doc.Repos))

+ http.Redirect(w, r, "/admin/notices?saved=1", http.StatusSeeOther)

+}

+

+func (h *handler) render(w http.ResponseWriter, status int, csrf, errMsg string, saved bool) {

+ snap := h.cfg.Store.Snapshot()

+ rows := make([]adminRow, 0, len(snap.Doc.Global)+2)

+ for _, n := range snap.Doc.Global {

+ rows = append(rows, adminRow{"global", n.Type, n.Title, n.Body, n.Link, n.LinkText})

+ }

+ slugs := make([]string, 0, len(snap.Doc.Repos))

+ for slug := range snap.Doc.Repos {

+ slugs = append(slugs, slug)

+ }

+ sort.Strings(slugs)

+ for _, slug := range slugs {

+ for _, n := range snap.Doc.Repos[slug] {

+ rows = append(rows, adminRow{slug, n.Type, n.Title, n.Body, n.Link, n.LinkText})

+ }

+ }

+ // One blank row is the no-JS "add" affordance: fill it and save. The

+ // admin.js helper clones it for the Add button.

+ rows = append(rows, adminRow{"global", TypeInfo, "", "", "", ""})

+

+ w.Header().Set("Content-Type", "text/html; charset=utf-8")

+ w.WriteHeader(status)

+ if err := h.tmpl.Execute(w, adminView{

+ Site: h.cfg.SiteName, CSRF: csrf, Error: errMsg, Saved: saved,

+ Repos: h.cfg.Repos, Rows: rows,

+ }); err != nil {

+ h.cfg.Logger.Error("notices admin render", "err", err)

+ }

+}

+

+// docFromForm rebuilds the document from the rendered row list. Rows are

+// parallel slices (scope[], type[], ...); deletion is a sparse del[] list

+// of row indices. A row with every field blank is treated as unused -- so

+// clearing a row removes it. PostForm, not Form, so a query string cannot

+// inject or override fields.

+func docFromForm(r *http.Request) (Document, error) {

+ form := r.PostForm

+ at := func(name string, i int) string {

+ if v := form[name]; i < len(v) {

+ return v[i]

+ }

+ return ""

+ }

+ del := map[int]bool{}

+ for _, s := range form["del"] {

+ if i, err := strconv.Atoi(s); err == nil {

+ del[i] = true

+ }

+ }

+ n := len(form["scope"])

+ doc := Document{Repos: map[string][]Notice{}}

+ for i := 0; i < n; i++ {

+ if del[i] {

+ continue

+ }

+ nt := Notice{

+ Type: at("type", i), Title: at("title", i), Body: at("body", i),

+ Link: at("link", i), LinkText: at("link_text", i),

+ }

+ if nt.Type == "" && nt.Title == "" && nt.Body == "" && nt.Link == "" {

+ continue

+ }

+ scope := at("scope", i)

+ if scope == "" || scope == "global" {

+ doc.Global = append(doc.Global, nt)

+ } else {

+ doc.Repos[scope] = append(doc.Repos[scope], nt)

+ }

+ }

+ return doc, nil // Store.Set validates

+}

+

+func ensureCSRF(w http.ResponseWriter, r *http.Request) (string, error) {

+ if c, err := r.Cookie(csrfCookie); err == nil && len(c.Value) >= 32 {

+ return c.Value, nil

+ }

+ b := make([]byte, 32)

+ if _, err := rand.Read(b); err != nil {

+ return "", err

+ }

+ tok := hex.EncodeToString(b)

+ http.SetCookie(w, &http.Cookie{

+ Name: csrfCookie, Value: tok, Path: "/admin",

+ HttpOnly: true, Secure: httpx.IsHTTPS(r), SameSite: http.SameSiteStrictMode,

+ MaxAge: 86400,

+ })

+ return tok, nil

+}

+

+func checkCSRF(r *http.Request) bool {

+ c, err := r.Cookie(csrfCookie)

+ if err != nil {

+ return false

+ }

+ got := r.PostForm.Get("csrf")

+ return subtle.ConstantTimeCompare([]byte(c.Value), []byte(got)) == 1

+}

+package notices

+

+import (

+ "log/slog"

+ "net/http"

+ "net/http/httptest"

+ "path/filepath"

+ "testing"

+)

+

+func testHandler(t *testing.T, cfg HandlerConfig) http.Handler {

+ t.Helper()

+ store, err := Open(filepath.Join(t.TempDir(), "notices.yaml"))

+ if err != nil {

+ t.Fatalf("Open: %v", err)

+ }

+ t.Cleanup(store.Close)

+ cfg.Store = store

+ if cfg.Logger == nil {

+ cfg.Logger = slog.Default()

+ }

+ h, err := NewHandler(cfg)

+ if err != nil {

+ t.Fatalf("NewHandler: %v", err)

+ }

+ return h

+}

+

+// Without RequiredGroup, the handler behaves exactly as it always did:

+// reaching it at all is enough, regardless of any group header.

+func TestHandlerNoGroupGateByDefault(t *testing.T) {

+ h := testHandler(t, HandlerConfig{})

+

+ req := httptest.NewRequest("GET", "/admin/notices", nil)

+ rec := httptest.NewRecorder()

+ h.ServeHTTP(rec, req)

+ if rec.Code != http.StatusOK {

+ t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)

+ }

+}

+

+// With RequiredGroup set, a caller whose GroupHeader doesn't list it is

+// refused before the handler does anything else -- no CSRF cookie, no page.

+func TestHandlerRejectsMissingGroup(t *testing.T) {

+ h := testHandler(t, HandlerConfig{RequiredGroup: "gsg-admins"})

+

+ cases := []struct {

+ name string

+ groups string

+ }{

+ {"no header", ""},

+ {"different group", "some-other-group"},

+ {"prefix collision", "gsg-admins-extra"},

+ }

+ for _, tc := range cases {

+ t.Run(tc.name, func(t *testing.T) {

+ req := httptest.NewRequest("GET", "/admin/notices", nil)

+ if tc.groups != "" {

+ req.Header.Set("X-Authentik-Groups", tc.groups)

+ }

+ rec := httptest.NewRecorder()

+ h.ServeHTTP(rec, req)

+ if rec.Code != http.StatusForbidden {

+ t.Fatalf("status = %d, want %d", rec.Code, http.StatusForbidden)

+ }

+ if rec.Result().Cookies() != nil && len(rec.Result().Cookies()) != 0 {

+ t.Errorf("rejected request set cookies: %v", rec.Result().Cookies())

+ }

+ })

+ }

+}

+

+// A member -- anywhere in the "|"-delimited list, with incidental

+// whitespace -- is let through.

+func TestHandlerAllowsMemberGroup(t *testing.T) {

+ h := testHandler(t, HandlerConfig{RequiredGroup: "gsg-admins"})

+

+ cases := []string{

+ "gsg-admins",

+ "other-group|gsg-admins",

+ "gsg-admins|other-group",

+ "other-group| gsg-admins |another",

+ }

+ for _, groups := range cases {

+ req := httptest.NewRequest("GET", "/admin/notices", nil)

+ req.Header.Set("X-Authentik-Groups", groups)

+ rec := httptest.NewRecorder()

+ h.ServeHTTP(rec, req)

+ if rec.Code != http.StatusOK {

+ t.Errorf("groups=%q: status = %d, want %d", groups, rec.Code, http.StatusOK)

+ }

+ }

+}

+

+// A custom GroupHeader is honored instead of the Authentik default.

+func TestHandlerCustomGroupHeader(t *testing.T) {

+ h := testHandler(t, HandlerConfig{RequiredGroup: "gsg-admins", GroupHeader: "X-Custom-Groups"})

+

+ req := httptest.NewRequest("GET", "/admin/notices", nil)

+ req.Header.Set("X-Authentik-Groups", "gsg-admins") // wrong header, should not count

+ rec := httptest.NewRecorder()

+ h.ServeHTTP(rec, req)

+ if rec.Code != http.StatusForbidden {

+ t.Fatalf("status = %d, want %d (wrong header should not authorize)", rec.Code, http.StatusForbidden)

+ }

+

+ req = httptest.NewRequest("GET", "/admin/notices", nil)

+ req.Header.Set("X-Custom-Groups", "gsg-admins")

+ rec = httptest.NewRecorder()

+ h.ServeHTTP(rec, req)

+ if rec.Code != http.StatusOK {

+ t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)

+ }

+}

+// Package notices holds operator-authored banners shown at the top of every

+// page: a site-wide list plus a list per repository. Content lives in one

+// YAML file that is watched for changes, so editing it never needs a

+// rebuild, and the optional admin listener can rewrite it.

+//

+// This package deliberately does not import internal/core: it is plain

+// config, and keeping it dependency-free lets both the module and the admin

+// handler reach it without an import cycle.

+package notices

+

+import (

+ "bytes"

+ "errors"

+ "fmt"

+ "io"

+ "net/url"

+ "sort"

+ "strings"

+ "unicode/utf8"

+

+ "gopkg.in/yaml.v3"

+)

+

+// Severities. The value doubles as the CSS class suffix, so it is validated

+// on every load and save; a typo must not become an unstyled banner.

+const (

+ TypeCritical = "critical"

+ TypeWarning = "warning"

+ TypeInfo = "info"

+ TypeFix = "fix"

+)

+

+// Notice is one banner. Link and LinkText are optional; an empty Link

+// renders no anchor.

+type Notice struct {

+ Type string `yaml:"type"`

+ Title string `yaml:"title,omitempty"`

+ Body string `yaml:"body,omitempty"`

+ Link string `yaml:"link,omitempty"`

+ LinkText string `yaml:"link_text,omitempty"`

+}

+

+// Document is the on-disk shape. Global renders above every repo's list.

+type Document struct {

+ Global []Notice `yaml:"global,omitempty"`

+ Repos map[string][]Notice `yaml:"repos,omitempty"`

+}

+

+// Snapshot is an immutable document plus the content hash identifying it.

+// They are carried together so a reader can never see data and revision

+// disagree.

+type Snapshot struct {

+ Doc Document

+ Rev string

+}

+

+const (

+ maxNotices = 200

+ maxPerRepo = 50

+ maxTitle = 200

+ maxBody = 4000

+ maxLink = 2048

+ maxLinkText = 120

+)

+

+// typeAliases make hand-editing forgiving without letting an invalid type

+// reach the template.

+var typeAliases = map[string]string{

+ "critical": TypeCritical,

+ "warning": TypeWarning,

+ "warn": TypeWarning,

+ "info": TypeInfo,

+ "informational": TypeInfo,

+ "information": TypeInfo,

+ "fix": TypeFix,

+ "fixed": TypeFix,

+}

+

+func canonicalType(s string) (string, bool) {

+ t, ok := typeAliases[strings.ToLower(strings.TrimSpace(s))]

+ return t, ok

+}

+

+// validSlug mirrors a repository directory name: one path element, no

+// separators. It keeps the repos map keys from becoming junk.

+func validSlug(s string) bool {

+ if s == "" || s == "." || s == ".." {

+ return false

+ }

+ for _, r := range s {

+ switch {

+ case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9',

+ r == '.', r == '_', r == '-':

+ default:

+ return false

+ }

+ }

+ return true

+}

+

+// checkLink allows a site-relative path and the http/https/mailto schemes.

+// html/template would neutralise a javascript: URL anyway, but rejecting it

+// here turns a silent #ZgotmplZ into a visible form error.

+func checkLink(raw string) error {

+ if strings.HasPrefix(raw, "//") || strings.ContainsAny(raw, "\\\x00\r\n") {

+ return fmt.Errorf("link %q is not allowed", raw)

+ }

+ u, err := url.Parse(raw)

+ if err != nil {

+ return fmt.Errorf("link %q: %w", raw, err)

+ }

+ if !u.IsAbs() {

+ return nil // relative path

+ }

+ switch strings.ToLower(u.Scheme) {

+ case "http", "https", "mailto":

+ return nil

+ default:

+ return fmt.Errorf("link %q: scheme %q is not allowed", raw, u.Scheme)

+ }

+}

+

+// validate trims and canonicalises in place and returns every problem it

+// found, so the admin form can show all of them at once.

+func validate(doc *Document) error {

+ var errs []error

+ total := 0

+ check := func(list []Notice, where string) []Notice {

+ for i := range list {

+ n := &list[i]

+ total++

+ if t, ok := canonicalType(n.Type); ok {

+ n.Type = t

+ } else {

+ errs = append(errs, fmt.Errorf("%s[%d]: type %q must be one of critical, warning, info, fix", where, i, n.Type))

+ }

+ n.Title = strings.TrimSpace(n.Title)

+ n.Body = strings.TrimRight(n.Body, "\n")

+ n.Link = strings.TrimSpace(n.Link)

+ n.LinkText = strings.TrimSpace(n.LinkText)

+ if n.Title == "" && n.Body == "" {

+ errs = append(errs, fmt.Errorf("%s[%d]: needs a title or a body", where, i))

+ }

+ switch {

+ case utf8.RuneCountInString(n.Title) > maxTitle:

+ errs = append(errs, fmt.Errorf("%s[%d]: title longer than %d characters", where, i, maxTitle))

+ case utf8.RuneCountInString(n.Body) > maxBody:

+ errs = append(errs, fmt.Errorf("%s[%d]: body longer than %d characters", where, i, maxBody))

+ case utf8.RuneCountInString(n.LinkText) > maxLinkText:

+ errs = append(errs, fmt.Errorf("%s[%d]: link text longer than %d characters", where, i, maxLinkText))

+ }

+ if len(n.Link) > maxLink {

+ errs = append(errs, fmt.Errorf("%s[%d]: link longer than %d bytes", where, i, maxLink))

+ }

+ if n.Link != "" {

+ if err := checkLink(n.Link); err != nil {

+ errs = append(errs, fmt.Errorf("%s[%d]: %w", where, i, err))

+ }

+ }

+ }

+ return list

+ }

+

+ doc.Global = check(doc.Global, "global")

+ slugs := make([]string, 0, len(doc.Repos))

+ for slug := range doc.Repos {

+ slugs = append(slugs, slug)

+ }

+ sort.Strings(slugs)

+ for _, slug := range slugs {

+ if !validSlug(slug) {

+ errs = append(errs, fmt.Errorf("repos: %q is not a valid repository slug", slug))

+ continue

+ }

+ if len(doc.Repos[slug]) > maxPerRepo {

+ errs = append(errs, fmt.Errorf("repos.%s: more than %d notices", slug, maxPerRepo))

+ }

+ doc.Repos[slug] = check(doc.Repos[slug], "repos."+slug)

+ }

+ if total > maxNotices {

+ errs = append(errs, fmt.Errorf("more than %d notices in total", maxNotices))

+ }

+ return errors.Join(errs...)

+}

+

+// parse decodes strictly: an unknown key is a typo the operator should see,

+// not something silently ignored. An empty file is an empty document.

+func parse(b []byte) (Document, error) {

+ var doc Document

+ dec := yaml.NewDecoder(bytes.NewReader(b))

+ dec.KnownFields(true)

+ if err := dec.Decode(&doc); err != nil {

+ if errors.Is(err, io.EOF) {

+ return Document{Repos: map[string][]Notice{}}, nil

+ }

+ return Document{}, fmt.Errorf("notices: %w", err)

+ }

+ if err := validate(&doc); err != nil {

+ return Document{}, err

+ }

+ if doc.Repos == nil {

+ doc.Repos = map[string][]Notice{}

+ }

+ return doc, nil

+}

+

+// marshal assumes the document has already been through validate, which is

+// what canonicalises severity aliases and trims fields. Both callers (parse

+// and Store.Set) validate first.

+func marshal(doc Document) ([]byte, error) {

+ var buf bytes.Buffer

+ enc := yaml.NewEncoder(&buf)

+ enc.SetIndent(2)

+ if err := enc.Encode(doc); err != nil {

+ return nil, err

+ }

+ if err := enc.Close(); err != nil {

+ return nil, err

+ }

+ return buf.Bytes(), nil

+}

+package notices

+

+import (

+ "crypto/sha256"

+ "encoding/hex"

+ "fmt"

+ "log/slog"

+ "os"

+ "path/filepath"

+ "sync"

+ "sync/atomic"

+ "time"

+

+ "github.com/fsnotify/fsnotify"

+)

+

+// Store owns one notices file. Reads are lock-free (an atomic snapshot);

+// writes and the watcher's reloads serialise on mu so a web save and an

+// external edit can never interleave.

+type Store struct {

+ path string

+ dir string

+

+ mu sync.Mutex

+ cur atomic.Pointer[Snapshot]

+

+ fsw *fsnotify.Watcher

+ done chan struct{}

+ closeOnce sync.Once

+}

+

+// Open loads the file (an absent file is an empty document) and starts

+// watching its directory. A parse error is fatal at startup so a typo is

+// visible immediately; later reload errors keep the last good snapshot.

+func Open(path string) (*Store, error) {

+ abs, err := filepath.Abs(path)

+ if err != nil {

+ return nil, err

+ }

+ dir := filepath.Dir(abs)

+ if fi, err := os.Stat(dir); err != nil || !fi.IsDir() {

+ return nil, fmt.Errorf("notices: directory %s does not exist", dir)

+ }

+

+ s := &Store{path: abs, dir: dir, done: make(chan struct{})}

+ snap, err := readSnapshot(abs)

+ if err != nil {

+ return nil, err

+ }

+ s.cur.Store(snap)

+

+ fsw, err := fsnotify.NewWatcher()

+ if err != nil {

+ return nil, fmt.Errorf("notices watch: %w", err)

+ }

+ if err := fsw.Add(dir); err != nil {

+ fsw.Close()

+ return nil, fmt.Errorf("notices watch: %w", err)

+ }

+ s.fsw = fsw

+ go s.watch()

+ return s, nil

+}

+

+// readSnapshot reads and hashes the file. A missing file is an empty

+// document, not an error -- the admin UI creates it on first save.

+func readSnapshot(path string) (*Snapshot, error) {

+ b, err := os.ReadFile(path)

+ if err != nil {

+ if os.IsNotExist(err) {

+ b = nil

+ } else {

+ return nil, fmt.Errorf("notices: %w", err)

+ }

+ }

+ doc, err := parse(b)

+ if err != nil {

+ return nil, err

+ }

+ return &Snapshot{Doc: doc, Rev: hash(b)}, nil

+}

+

+func hash(b []byte) string {

+ sum := sha256.Sum256(b)

+ return hex.EncodeToString(sum[:])[:16]

+}

+

+// Snapshot is the current document. The returned value shares its backing

+// slices and map with the stored one; callers must not mutate it.

+func (s *Store) Snapshot() Snapshot {

+ p := s.cur.Load()

+ if p == nil {

+ return Snapshot{}

+ }

+ return *p

+}

+

+// Revision is the content hash. O(1); safe to call on every request.

+func (s *Store) Revision() string {

+ p := s.cur.Load()

+ if p == nil {

+ return ""

+ }

+ return p.Rev

+}

+

+// Set validates, writes atomically (temp file in the same directory, fsync,

+// rename, 0600), and publishes the new snapshot immediately, so the next

+// request sees it without waiting for the watcher.

+func (s *Store) Set(doc Document) error {

+ if err := validate(&doc); err != nil {

+ return err

+ }

+ b, err := marshal(doc)

+ if err != nil {

+ return err

+ }

+

+ s.mu.Lock()

+ defer s.mu.Unlock()

+

+ tmp, err := os.CreateTemp(s.dir, ".notices-*.tmp")

+ if err != nil {

+ return fmt.Errorf("notices: %w", err)

+ }

+ tmpName := tmp.Name()

+ defer os.Remove(tmpName) // no-op once the rename succeeds

+ if err := tmp.Chmod(0o600); err != nil {

+ tmp.Close()

+ return err

+ }

+ if _, err := tmp.Write(b); err != nil {

+ tmp.Close()

+ return err

+ }

+ if err := tmp.Sync(); err != nil {

+ tmp.Close()

+ return err

+ }

+ if err := tmp.Close(); err != nil {

+ return err

+ }

+ if err := os.Rename(tmpName, s.path); err != nil {

+ return err

+ }

+

+ s.cur.Store(&Snapshot{Doc: doc, Rev: hash(b)})

+ return nil

+}

+

+// watch is the only goroutine that touches the debounce timer, so no lock

+// is needed for it. Events for our own ".notices-*.tmp" files are ignored;

+// only the real path triggers a reload.

+func (s *Store) watch() {

+ const debounce = 200 * time.Millisecond

+ var timer *time.Timer

+ var timerC <-chan time.Time

+

+ for {

+ select {

+ case ev, ok := <-s.fsw.Events:

+ if !ok {

+ return

+ }

+ if filepath.Clean(ev.Name) != s.path {

+ continue

+ }

+ if timer == nil {

+ timer = time.NewTimer(debounce)

+ } else {

+ if !timer.Stop() {

+ select {

+ case <-timer.C:

+ default:

+ }

+ }

+ timer.Reset(debounce)

+ }

+ timerC = timer.C

+ case <-timerC:

+ timerC = nil

+ s.reload()

+ case err, ok := <-s.fsw.Errors:

+ if !ok {

+ return

+ }

+ slog.Warn("notices watch error", "err", err)

+ case <-s.done:

+ if timer != nil {

+ timer.Stop()

+ }

+ return

+ }

+ }

+}

+

+// reload re-reads the file and swaps the snapshot only when the content

+// hash moved. A parse error keeps the previous snapshot, so a half-written

+// or mistyped file never blanks the banners.

+func (s *Store) reload() {

+ s.mu.Lock()

+ defer s.mu.Unlock()

+

+ snap, err := readSnapshot(s.path)

+ if err != nil {

+ slog.Warn("notices: keeping previous snapshot", "err", err)

+ return

+ }

+ if cur := s.cur.Load(); cur != nil && cur.Rev == snap.Rev {

+ return

+ }

+ s.cur.Store(snap)

+ slog.Info("notices reloaded", "revision", snap.Rev)

+}

+

+func (s *Store) Close() {

+ s.closeOnce.Do(func() {

+ close(s.done)

+ if s.fsw != nil {

+ s.fsw.Close()

+ }

+ })

+}

+

+// def is the process-wide store the `notices` module reads. A nil default

+// means the feature is off; the module returns an empty list, not an error.

+var def atomic.Pointer[Store]

+

+func SetDefault(s *Store) { def.Store(s) }

+func Default() *Store { return def.Load() }

+package notices

+

+import (

+ "os"

+ "path/filepath"

+ "reflect"

+ "strings"

+ "testing"

+)

+

+func TestParseRejectsUnknownField(t *testing.T) {

+ _, err := parse([]byte("global:\n - type: info\n subject: hi\n"))

+ if err == nil {

+ t.Fatal("unknown field accepted")

+ }

+ if !strings.Contains(err.Error(), "subject") {

+ t.Fatalf("error does not name the field: %v", err)

+ }

+}

+

+func TestParseRejectsBadType(t *testing.T) {

+ _, err := parse([]byte("global:\n - type: critcal\n title: hi\n"))

+ if err == nil || !strings.Contains(err.Error(), "critcal") {

+ t.Fatalf("bad type: err = %v", err)

+ }

+}

+

+func TestParseEmpty(t *testing.T) {

+ for _, in := range [][]byte{nil, []byte(""), []byte("{}\n")} {

+ doc, err := parse(in)

+ if err != nil {

+ t.Fatalf("parse(%q): %v", in, err)

+ }

+ if len(doc.Global) != 0 || len(doc.Repos) != 0 {

+ t.Fatalf("parse(%q) = %+v, want empty", in, doc)

+ }

+ if doc.Repos == nil {

+ t.Fatalf("parse(%q): Repos is nil", in)

+ }

+ }

+}

+

+func TestTypeAliasesAndTrimming(t *testing.T) {

+ doc, err := parse([]byte("global:\n - type: informational\n title: ' spaced '\n"))

+ if err != nil {

+ t.Fatal(err)

+ }

+ n := doc.Global[0]

+ if n.Type != TypeInfo || n.Title != "spaced" {

+ t.Fatalf("got %+v", n)

+ }

+}

+

+func TestLinkSchemes(t *testing.T) {

+ cases := []struct {

+ link string

+ ok bool

+ }{

+ {"/status", true},

+ {"https://example.org/a", true},

+ {"mailto:ops@example.org", true},

+ {"javascript:alert(1)", false},

+ {"//evil.example", false},

+ {"ftp://example.org", false},

+ }

+ for _, tc := range cases {

+ doc := Document{Global: []Notice{{Type: TypeInfo, Title: "x", Link: tc.link}}}

+ err := validate(&doc)

+ if tc.ok && err != nil {

+ t.Errorf("link %q rejected: %v", tc.link, err)

+ }

+ if !tc.ok && err == nil {

+ t.Errorf("link %q accepted", tc.link)

+ }

+ }

+}

+

+func TestSetRoundTripAndRevision(t *testing.T) {

+ path := filepath.Join(t.TempDir(), "notices.yaml")

+ st, err := Open(path)

+ if err != nil {

+ t.Fatal(err)

+ }

+ t.Cleanup(st.Close)

+

+ if st.Revision() == "" {

+ t.Fatal("empty store has no revision")

+ }

+ doc := Document{

+ Global: []Notice{{Type: TypeCritical, Title: "Outage", Body: "line\nline"}},

+ Repos: map[string][]Notice{"demo": {{Type: "informational", Title: "Repo"}}},

+ }

+ if err := st.Set(doc); err != nil {

+ t.Fatal(err)

+ }

+ // informational must have been canonicalised in the published snapshot.

+ if got := st.Snapshot().Doc.Repos["demo"][0].Type; got != TypeInfo {

+ t.Fatalf("published type = %q, want %q", got, TypeInfo)

+ }

+ rev := st.Revision()

+

+ fi, err := os.Stat(path)

+ if err != nil {

+ t.Fatal(err)

+ }

+ if perm := fi.Mode().Perm(); perm != 0o600 {

+ t.Errorf("file mode = %o, want 600", perm)

+ }

+

+ again, err := Open(path)

+ if err != nil {

+ t.Fatal(err)

+ }

+ t.Cleanup(again.Close)

+ if !reflect.DeepEqual(st.Snapshot().Doc, again.Snapshot().Doc) {

+ t.Fatalf("round trip mismatch:\n%+v\n%+v", st.Snapshot().Doc, again.Snapshot().Doc)

+ }

+

+ // A no-op save is byte-identical and keeps the revision.

+ if err := st.Set(doc); err != nil {

+ t.Fatal(err)

+ }

+ if st.Revision() != rev {

+ t.Fatalf("no-op save changed revision %q -> %q", rev, st.Revision())

+ }

+

+ // A content change moves it.

+ doc.Global[0].Body = "different"

+ if err := st.Set(doc); err != nil {

+ t.Fatal(err)

+ }

+ if st.Revision() == rev {

+ t.Fatal("content change kept the same revision")

+ }

+}

+

+func TestOpenMissingFileAndBadDir(t *testing.T) {

+ dir := t.TempDir()

+ st, err := Open(filepath.Join(dir, "notices.yaml"))

+ if err != nil {

+ t.Fatal(err)

+ }

+ t.Cleanup(st.Close)

+ if len(st.Snapshot().Doc.Global) != 0 {

+ t.Fatal("missing file is not empty")

+ }

+ if _, err := Open(filepath.Join(dir, "nope", "notices.yaml")); err == nil {

+ t.Fatal("missing directory accepted")

+ }

+}

+// Package session mints and verifies the signed, stateless cookies gsg

+// uses to recognize a logged-in browser. There is no server-side session

+// store: everything needed to verify a cookie travels inside it, HMAC-signed

+// against a secret that lives only in this process's memory. A restart

+// invalidates every outstanding session -- an accepted trade-off for a

+// login this lightweight.

+//

+// The master secret is never used to sign anything directly. Each purpose

+// (today: the user session cookie; later: share-link tokens) gets its own

+// key derived from the secret via deriveKey, so a value signed for one

+// purpose can never be replayed as another -- that's enforced by

+// construction, not by a discriminator field a bug could skip.

+package session

+

+import (

+ "crypto/hmac"

+ "crypto/rand"

+ "crypto/sha256"

+ "crypto/subtle"

+ "encoding/base64"

+ "encoding/json"

+ "fmt"

+ "net/http"

+ "strconv"

+ "strings"

+ "time"

+)

+

+const (

+ // CookieName is the browser cookie carrying the signed session.

+ CookieName = "gsg_user"

+

+ // TTL is how long a session lasts after login before it must be

+ // re-established. Embedded inside the signed payload, not left to the

+ // cookie's own Max-Age/Expires alone, so a copied cookie can't outlive

+ // what the server considers valid.

+ TTL = 30 * 24 * time.Hour

+

+ // ShareCookieName is the browser cookie a redeemed share link mints.

+ ShareCookieName = "gsg_share"

+

+ purposeSession = "session"

+ purposeShareURL = "share-url"

+ purposeShareCookie = "share-cookie"

+)

+

+// Manager issues and verifies gsg's signed cookies. Safe for concurrent

+// use; a nil *Manager verifies every request as anonymous, so wiring it up

+// is optional.

+type Manager struct {

+ secret []byte

+}

+

+// NewManager generates a fresh in-memory secret.

+func NewManager() *Manager {

+ secret := make([]byte, 32)

+ if _, err := rand.Read(secret); err != nil {

+ panic("session: failed to generate secret: " + err.Error())

+ }

+ return &Manager{secret: secret}

+}

+

+// deriveKey derives a purpose-scoped signing key from the master secret.

+// This is a single-step HMAC-based derivation (not full RFC 5869 HKDF),

+// which is sufficient here: the input is already a uniformly random 32-byte

+// secret, so there's no entropy-extraction step to do, only labeling.

+func (m *Manager) deriveKey(purpose string) []byte {

+ mac := hmac.New(sha256.New, m.secret)

+ mac.Write([]byte(purpose))

+ return mac.Sum(nil)

+}

+

+// Issue mints a signed session cookie for username.

+func (m *Manager) Issue(username string) *http.Cookie {

+ exp := time.Now().Add(TTL).Unix()

+ payload := username + "|" + strconv.FormatInt(exp, 10)

+ return &http.Cookie{

+ Name: CookieName,

+ Value: sign(m.deriveKey(purposeSession), payload, ""),

+ Path: "/",

+ HttpOnly: true,

+ Secure: true,

+ SameSite: http.SameSiteLaxMode,

+ Expires: time.Unix(exp, 0),

+ }

+}

+

+// Verify reads and checks the session cookie on r, returning the

+// authenticated username, or "" if there is none, it's malformed, it's

+// signed for a different purpose, or it has expired.

+func (m *Manager) Verify(r *http.Request) string {

+ if m == nil {

+ return ""

+ }

+ c, err := r.Cookie(CookieName)

+ if err != nil {

+ return ""

+ }

+ payload, ok := verify(m.deriveKey(purposeSession), c.Value, "")

+ if !ok {

+ return ""

+ }

+ user, expStr, ok := strings.Cut(payload, "|")

+ if !ok {

+ return ""

+ }

+ exp, err := strconv.ParseInt(expStr, 10, 64)

+ if err != nil || time.Now().Unix() > exp {

+ return ""

+ }

+ return user

+}

+

+// Clear returns a cookie that immediately expires the session.

+func (m *Manager) Clear() *http.Cookie {

+ return &http.Cookie{

+ Name: CookieName,

+ Value: "",

+ Path: "/",

+ HttpOnly: true,

+ Secure: true,

+ SameSite: http.SameSiteLaxMode,

+ MaxAge: -1,

+ }

+}

+

+// ShareClaims is the payload embedded in both a share-URL token and the

+// gsg_share cookie minted on redemption. Slugs is the set of repo slugs the

+// grant unlocks; IAT/Exp are unix seconds. Pwd records only whether the

+// URL token requires a password -- it carries no password material itself.

+type ShareClaims struct {

+ V int `json:"v"`

+ Slugs []string `json:"slugs"`

+ IAT int64 `json:"iat"`

+ Exp int64 `json:"exp"`

+ Pwd bool `json:"pwd"`

+}

+

+func (c ShareClaims) expired() bool { return c.Exp != 0 && time.Now().Unix() > c.Exp }

+

+// IssuedAt is c.IAT as a time.Time, for comparison against a repo's

+// gsg.share-revoked-after.

+func (c ShareClaims) IssuedAt() time.Time { return time.Unix(c.IAT, 0) }

+

+// NewShareToken signs a share-URL token. password is "" for an unprotected

+// link; when set, it is folded into the signature, never stored in the

+// token -- see the package doc.

+func (m *Manager) NewShareToken(slugs []string, ttl time.Duration, password string) (string, ShareClaims) {

+ now := time.Now()

+ claims := ShareClaims{V: 1, Slugs: slugs, IAT: now.Unix(), Exp: now.Add(ttl).Unix(), Pwd: password != ""}

+ b, _ := json.Marshal(claims) // ShareClaims always marshals; no error path

+ return sign(m.deriveKey(purposeShareURL), string(b), password), claims

+}

+

+// PeekShareToken decodes a share-URL token's claims WITHOUT verifying its

+// signature. It exists only so the redemption page can decide whether to

+// show a password prompt before it knows the password; the result must

+// never be used to grant access -- only VerifyShareToken's result may do

+// that.

+func PeekShareToken(tok string) (ShareClaims, bool) {

+ encPayload, _, found := strings.Cut(tok, ".")

+ if !found {

+ return ShareClaims{}, false

+ }

+ b, err := dec(encPayload)

+ if err != nil {

+ return ShareClaims{}, false

+ }

+ var c ShareClaims

+ if err := json.Unmarshal(b, &c); err != nil || c.V != 1 {

+ return ShareClaims{}, false

+ }

+ return c, true

+}

+

+// VerifyShareToken checks a share-URL token against the password the

+// visitor supplied (pass "" for a token that doesn't require one) and

+// returns its claims. Wrong password, tampering, or expiry all fail the

+// same way -- there is nothing here for an attacker to distinguish.

+func (m *Manager) VerifyShareToken(tok, password string) (ShareClaims, bool) {

+ payload, ok := verify(m.deriveKey(purposeShareURL), tok, password)

+ if !ok {

+ return ShareClaims{}, false

+ }

+ var c ShareClaims

+ if err := json.Unmarshal([]byte(payload), &c); err != nil || c.V != 1 || c.expired() {

+ return ShareClaims{}, false

+ }

+ return c, true

+}

+

+// IssueShareCookie mints the gsg_share cookie from already-verified claims.

+// IAT and Exp are copied verbatim from the URL token, not restamped to

+// "now": the revocation check compares a repo's gsg.share-revoked-after

+// against IAT, and resetting it here would let an already-redeemed browser

+// outlive a revocation aimed at it.

+func (m *Manager) IssueShareCookie(claims ShareClaims) *http.Cookie {

+ b, _ := json.Marshal(claims)

+ return &http.Cookie{

+ Name: ShareCookieName,

+ Value: sign(m.deriveKey(purposeShareCookie), string(b), ""),

+ Path: "/",

+ HttpOnly: true,

+ Secure: true,

+ SameSite: http.SameSiteLaxMode,

+ Expires: time.Unix(claims.Exp, 0),

+ }

+}

+

+// VerifyShareCookie reads and checks the gsg_share cookie on r.

+func (m *Manager) VerifyShareCookie(r *http.Request) (ShareClaims, bool) {

+ if m == nil {

+ return ShareClaims{}, false

+ }

+ c, err := r.Cookie(ShareCookieName)

+ if err != nil {

+ return ShareClaims{}, false

+ }

+ payload, ok := verify(m.deriveKey(purposeShareCookie), c.Value, "")

+ if !ok {

+ return ShareClaims{}, false

+ }

+ var claims ShareClaims

+ if err := json.Unmarshal([]byte(payload), &claims); err != nil || claims.V != 1 || claims.expired() {

+ return ShareClaims{}, false

+ }

+ return claims, true

+}

+

+// sign produces "base64url(payload).base64url(hmac-sha256(payload||0||extra))".

+// Compact and self-contained like a JWT, without pulling in a JWT library or

+// its algorithm-confusion surface (alg:none, HS/RS key confusion) -- the key

+// and the hash are fixed by this package, not negotiable per token. extra is

+// "" for every purpose except a password-protected share-URL token, where

+// it's the password: folding it into the signature input (rather than

+// storing a hash of it in the payload) means nobody holding just the token

+// can crack it offline, and a guess can only be checked by asking the

+// server, which can rate-limit attempts.

+func sign(key []byte, payload, extra string) string {

+ mac := hmac.New(sha256.New, key)

+ mac.Write([]byte(payload))

+ mac.Write([]byte{0})

+ mac.Write([]byte(extra))

+ return enc(payload) + "." + enc(string(mac.Sum(nil)))

+}

+

+// verify checks tok against key and extra and, on success, returns the

+// payload.

+func verify(key []byte, tok, extra string) (payload string, ok bool) {

+ encPayload, encSig, found := strings.Cut(tok, ".")

+ if !found {

+ return "", false

+ }

+ payloadBytes, err := dec(encPayload)

+ if err != nil {

+ return "", false

+ }

+ sig, err := dec(encSig)

+ if err != nil {

+ return "", false

+ }

+ mac := hmac.New(sha256.New, key)

+ mac.Write(payloadBytes)

+ mac.Write([]byte{0})

+ mac.Write([]byte(extra))

+ if subtle.ConstantTimeCompare(sig, mac.Sum(nil)) != 1 {

+ return "", false

+ }

+ return string(payloadBytes), true

+}

+

+func enc(s string) string { return base64.RawURLEncoding.EncodeToString([]byte(s)) }

+

+func dec(s string) ([]byte, error) {

+ b, err := base64.RawURLEncoding.DecodeString(s)

+ if err != nil {

+ return nil, fmt.Errorf("session: bad encoding: %w", err)

+ }

+ return b, nil

+}

+<!doctype html>

+<html lang="en">

+<head>

+<meta charset="utf-8">

+<meta name="viewport" content="width=device-width, initial-scale=1">

+<title>Share &middot; {{ .Site }}</title>

+<link rel="stylesheet" href="/static/css/base.css">

+<link rel="stylesheet" href="/static/css/share.css">

+</head>

+<body>

+<main class="wrap">

+ <header class="hero">

+ <h1 class="page-title">Share a hidden repository</h1>

+ <p class="page-subtitle">Anyone with the link can view exactly the repositories you select below &mdash; no login required.</p>

+ </header>

+

+ {{ if .Result }}

+ <div class="notice notice-fix">

+ <strong class="notice-title">Link ready</strong>

+ <p class="share-link"><a href="{{ .Result }}">{{ .Result }}</a></p>

+ <p class="share-hint">Send this URL to whoever needs it. If you set a password, tell them separately &mdash; it isn't part of the link.</p>

+ </div>

+ <p><a href="/share/new">Create another</a></p>

+ {{ else }}

+ {{ if .Error }}

+ <div class="notice notice-critical">

+ <strong class="notice-title">Not created</strong>

+ <p>{{ .Error }}</p>

+ </div>

+ {{ end }}

+

+ {{ if not .Repos }}

+ <p>You don't have any hidden repositories to share.</p>

+ {{ else }}

+ <form method="post" action="/share/new" class="share-form">

+ <fieldset class="share-repos">

+ <legend>Repositories</legend>

+ {{ $sel := .Selected }}

+ {{ range .Repos }}

+ <label class="share-repo">

+ <input type="checkbox" name="repo" value="{{ .Slug }}"{{ if index $sel .Slug }} checked{{ end }}>

+ <span class="share-repo-title">{{ .Title }}</span>

+ <span class="share-maxage">up to {{ humanDuration .MaxAge }}</span>

+ </label>

+ {{ end }}

+ </fieldset>

+

+ <label class="share-field">

+ <span>Password (optional)</span>

+ <input type="password" name="password" autocomplete="new-password">

+ </label>

+

+ <label class="share-field">

+ <span>Expires in (optional &mdash; e.g. "24h", "168h")</span>

+ <input type="text" name="ttl" placeholder="defaults to the shortest selected repo's ceiling">

+ </label>

+

+ <button class="chip admin-save" type="submit">Create link</button>

+ </form>

+ {{ end }}

+ {{ end }}

+</main>

+</body>

+</html>

+// Package share implements anonymous, stateless share links: a logged-in

+// user picks a set of their hidden repos and mints a signed URL that grants

+// view access to exactly those repos, no login required, optionally gated

+// by a password. Everything needed to verify a link travels inside it --

+// there is no server-side record of what's been shared, only the one

+// revocation lever gsg.share-revoked-after provides (see internal/core).

+//

+// This package is deliberately decoupled from gsg/internal/core, the same

+// way internal/notices is: HandlerConfig takes plain data and callbacks,

+// not core.Site or core.RepoInfo, so main.go is the only place that bridges

+// the two.

+package share

+

+import (

+ "embed"

+ "fmt"

+ "html/template"

+ "log/slog"

+ "net/http"

+ "sort"

+ "strings"

+ "sync"

+ "time"

+

+ "gsg/internal/access"

+ "gsg/internal/httpx"

+ "gsg/internal/session"

+)

+

+//go:embed new.html view.html

+var templatesFS embed.FS

+

+// maxSlugs caps how many repos a single share token may name. The token

+// travels as a URL, and an unbounded slug list eventually exceeds practical

+// length limits in browsers, mail clients, and proxies (roughly 2000

+// characters).

+const maxSlugs = 64

+

+const (

+ rateLimitWindow = time.Minute

+ rateLimitMax = 10

+)

+

+// RepoOption is one hidden repo a user could choose to share.

+type RepoOption struct {

+ Slug string

+ Title string

+ MaxAge time.Duration // gsg.share-max-age: the ceiling/default for this repo

+}

+

+// HandlerConfig is everything the share surface needs that it cannot

+// discover for itself.

+type HandlerConfig struct {

+ Sessions *session.Manager

+

+ // VisibleHiddenRepos returns the hidden repos user is currently allowed

+ // to see (and therefore may share). Used both to populate the mint form

+ // and to re-filter a mint submission -- a submitted slug is never

+ // trusted just because the form included it.

+ VisibleHiddenRepos func(user string) []RepoOption

+

+ // RevokedAfter returns a repo's gsg.share-revoked-after (zero if unset)

+ // and whether the repo still exists at all, for filtering a token's

+ // slugs at redemption time.

+ RevokedAfter func(slug string) (revokedAfter time.Time, exists bool)

+

+ SiteName string

+ Logger *slog.Logger

+}

+

+type handler struct {

+ cfg HandlerConfig

+ newTmpl *template.Template

+ viewTmpl *template.Template

+ limiter *rateLimiter

+}

+

+// NewHandler builds the share mux: minting (requires a gsg_user session)

+// and redemption (does not). Both belong on the public listener (see

+// main.go) and are hand-mounted directly on its mux rather than expressed

+// as a core.Route -- core.Route's Renderer always builds a body from a Ctx,

+// and a mint result page or a redirect-plus-Set-Cookie don't fit that

+// shape.

+func NewHandler(cfg HandlerConfig) (http.Handler, error) {

+ if cfg.Sessions == nil {

+ return nil, fmt.Errorf("share: no session manager")

+ }

+ if cfg.VisibleHiddenRepos == nil || cfg.RevokedAfter == nil {

+ return nil, fmt.Errorf("share: missing required callback")

+ }

+ if cfg.Logger == nil {

+ cfg.Logger = slog.Default()

+ }

+

+ funcs := template.FuncMap{"humanDuration": humanDuration}

+ newTmpl, err := template.New("new.html").Funcs(funcs).ParseFS(templatesFS, "new.html")

+ if err != nil {

+ return nil, fmt.Errorf("share: new.html: %w", err)

+ }

+ viewTmpl, err := template.New("view.html").Funcs(funcs).ParseFS(templatesFS, "view.html")

+ if err != nil {

+ return nil, fmt.Errorf("share: view.html: %w", err)

+ }

+

+ h := &handler{cfg: cfg, newTmpl: newTmpl, viewTmpl: viewTmpl, limiter: newRateLimiter()}

+

+ mux := http.NewServeMux()

+ mux.HandleFunc("GET /share/new", h.newForm)

+ mux.HandleFunc("POST /share/new", h.newSubmit)

+ mux.HandleFunc("GET /share/view/{token}", h.view)

+ mux.HandleFunc("POST /share/view/{token}", h.redeem)

+ return mux, nil

+}

+

+type formView struct {

+ Site string

+ Error string

+ Result string

+ Repos []RepoOption

+ Selected map[string]bool

+}

+

+func (h *handler) newForm(w http.ResponseWriter, r *http.Request) {

+ user := h.cfg.Sessions.Verify(r)

+ if user == "" {

+ http.Redirect(w, r, "/auth/login?next=/share/new", http.StatusSeeOther)

+ return

+ }

+ h.renderForm(w, http.StatusOK, user, "", nil)

+}

+

+func (h *handler) renderForm(w http.ResponseWriter, status int, user, errMsg string, selected map[string]bool) {

+ repos := h.cfg.VisibleHiddenRepos(user)

+ sort.Slice(repos, func(i, j int) bool { return repos[i].Slug < repos[j].Slug })

+

+ httpx.Secure(w, httpx.SecureOptions{NoStore: true})

+ w.Header().Set("Content-Type", "text/html; charset=utf-8")

+ w.WriteHeader(status)

+ if err := h.newTmpl.Execute(w, formView{

+ Site: h.cfg.SiteName, Error: errMsg, Repos: repos, Selected: selected,

+ }); err != nil {

+ h.cfg.Logger.Error("share new render", "err", err)

+ }

+}

+

+func (h *handler) newSubmit(w http.ResponseWriter, r *http.Request) {

+ user := h.cfg.Sessions.Verify(r)

+ if user == "" {

+ http.Error(w, "not logged in", http.StatusUnauthorized)

+ return

+ }

+ // Same-origin check on the POST: minting persists nothing server-side,

+ // but it's still an authenticated action worth CSRF-class protection --

+ // a cross-site page shouldn't be able to make a logged-in visitor's

+ // browser silently mint share links.

+ if !httpx.SameOrigin(r) {

+ h.cfg.Logger.Warn("share new: origin rejected",

+ "host", r.Host, "origin", r.Header.Get("Origin"),

+ "sec-fetch-site", r.Header.Get("Sec-Fetch-Site"))

+ http.Error(w, "forbidden", http.StatusForbidden)

+ return

+ }

+ r.Body = http.MaxBytesReader(w, r.Body, 1<<16)

+ if err := r.ParseForm(); err != nil {

+ h.renderForm(w, http.StatusBadRequest, user, "bad form submission", nil)

+ return

+ }

+

+ allowed := h.cfg.VisibleHiddenRepos(user)

+ byslug := make(map[string]RepoOption, len(allowed))

+ for _, o := range allowed {

+ byslug[o.Slug] = o

+ }

+

+ submitted := r.PostForm["repo"]

+ selected := make(map[string]bool, len(submitted))

+ for _, s := range submitted {

+ selected[s] = true

+ }

+

+ // Never trust the submitted slug list: only repos byslug (this user's

+ // own current visibility) can end up in the token, however the form

+ // was tampered with.

+ var slugs []string

+ var ceiling time.Duration

+ for _, s := range submitted {

+ o, ok := byslug[s]

+ if !ok {

+ continue

+ }

+ slugs = append(slugs, o.Slug)

+ if ceiling == 0 || o.MaxAge < ceiling {

+ ceiling = o.MaxAge

+ }

+ }

+ if len(slugs) == 0 {

+ h.renderForm(w, http.StatusBadRequest, user, "select at least one repository", selected)

+ return

+ }

+ if len(slugs) > maxSlugs {

+ h.renderForm(w, http.StatusBadRequest, user,

+ fmt.Sprintf("a single link can name at most %d repositories", maxSlugs), selected)

+ return

+ }

+ sort.Strings(slugs)

+

+ // The user may always ask for less than the ceiling, never more; an

+ // unparsable or too-long value falls back to the ceiling rather than

+ // rejecting the submission outright, since the ceiling is always a

+ // valid choice.

+ ttl := ceiling

+ if v := strings.TrimSpace(r.PostForm.Get("ttl")); v != "" {

+ if d, err := time.ParseDuration(v); err == nil && d > 0 && d <= ceiling {

+ ttl = d

+ }

+ }

+

+ password := r.PostForm.Get("password")

+ tok, claims := h.cfg.Sessions.NewShareToken(slugs, ttl, password)

+

+ h.cfg.Logger.Info("share link minted",

+ "user", user, "repos", len(slugs), "password", password != "",

+ "exp", time.Unix(claims.Exp, 0).Format(time.RFC3339))

+

+ // The result page's body is a bearer capability (the share URL itself),

+ // so unlike the rest of the site it must never be stored anywhere.

+ httpx.Secure(w, httpx.SecureOptions{NoStore: true})

+ w.Header().Set("Content-Type", "text/html; charset=utf-8")

+ if err := h.newTmpl.Execute(w, formView{

+ Site: h.cfg.SiteName, Result: httpx.AbsoluteURL(r, "/share/view/"+tok),

+ }); err != nil {

+ h.cfg.Logger.Error("share new render", "err", err)

+ }

+}

+

+type viewData struct {

+ Site string

+ Error string

+ Action string

+}

+

+// view is the landing page for a share link. A token that requires no

+// password redeems immediately; one that does gets a password prompt

+// first. PeekShareToken is unverified and only decides which of those two

+// to show -- redeem always re-derives the real answer via VerifyShareToken.

+func (h *handler) view(w http.ResponseWriter, r *http.Request) {

+ tok := r.PathValue("token")

+ claims, ok := session.PeekShareToken(tok)

+ if !ok {

+ http.Error(w, "invalid share link", http.StatusNotFound)

+ return

+ }

+ if !claims.Pwd {

+ h.redeem(w, r)

+ return

+ }

+ h.renderPassword(w, http.StatusOK, tok, "")

+}

+

+func (h *handler) renderPassword(w http.ResponseWriter, status int, tok, errMsg string) {

+ httpx.Secure(w, httpx.SecureOptions{NoStore: true})

+ w.Header().Set("Content-Type", "text/html; charset=utf-8")

+ w.WriteHeader(status)

+ if err := h.viewTmpl.Execute(w, viewData{

+ Site: h.cfg.SiteName, Error: errMsg, Action: "/share/view/" + tok,

+ }); err != nil {

+ h.cfg.Logger.Error("share view render", "err", err)

+ }

+}

+

+// redeem verifies the token (with whatever password was submitted, "" if

+// none), filters its slugs against live revocation state, and mints the

+// gsg_share cookie. It also serves the no-password GET path via view above,

+// where the submitted password is always "".

+func (h *handler) redeem(w http.ResponseWriter, r *http.Request) {

+ tok := r.PathValue("token")

+ r.Body = http.MaxBytesReader(w, r.Body, 1<<16)

+ if err := r.ParseForm(); err != nil {

+ http.Error(w, "bad form submission", http.StatusBadRequest)

+ return

+ }

+ password := r.PostForm.Get("password")

+

+ // Only rate-limit actual guesses against a password-protected link --

+ // there is nothing to guess on an unprotected one. Keyed on the source

+ // IP alone, not IP+token: PeekShareToken doesn't verify a signature, so

+ // keying on the token string would let an unauthenticated caller mint

+ // unbounded distinct keys (one per invented token) for free. IP-only

+ // also has the right semantics anyway -- one source gets a fixed

+ // budget of guesses per window, not a fixed budget per link it tries.

+ if peek, ok := session.PeekShareToken(tok); ok && peek.Pwd {

+ if !h.limiter.allow(httpx.RemoteIP(r)) {

+ http.Error(w, "too many attempts, try again later", http.StatusTooManyRequests)

+ return

+ }

+ }

+

+ claims, ok := h.cfg.Sessions.VerifyShareToken(tok, password)

+ if !ok {

+ if peek, peekOK := session.PeekShareToken(tok); peekOK && peek.Pwd {

+ h.renderPassword(w, http.StatusUnauthorized, tok, "incorrect password")

+ return

+ }

+ http.Error(w, "invalid or expired share link", http.StatusNotFound)

+ return

+ }

+

+ // Narrow to what's still live: a repo that no longer exists, or whose

+ // gsg.share-revoked-after postdates this grant, drops out here. This is

+ // a courtesy at redemption time -- the authoritative check runs again

+ // on every subsequent request in core.Server.buildCtx, since revocation

+ // must reach a browser that already holds the cookie, not just block

+ // new redemptions.

+ kept := make([]string, 0, len(claims.Slugs))

+ for _, slug := range claims.Slugs {

+ revokedAfter, exists := h.cfg.RevokedAfter(slug)

+ if !exists {

+ continue

+ }

+ if !access.ShareLive(revokedAfter, claims.IssuedAt()) {

+ continue

+ }

+ kept = append(kept, slug)

+ }

+ if len(kept) == 0 {

+ http.Error(w, "this share link no longer grants access to any repository", http.StatusGone)

+ return

+ }

+ claims.Slugs = kept

+

+ http.SetCookie(w, h.cfg.Sessions.IssueShareCookie(claims))

+ http.Redirect(w, r, "/", http.StatusSeeOther)

+}

+

+// rateLimiter is a small in-memory, per-process fixed-window limiter --

+// the same posture gsg already accepts elsewhere (see reposCache in

+// internal/modules/repos.go): it resets on restart, and, as a known

+// simplification, never evicts a key once created. Acceptable for guarding

+// a share link's password on a self-hosted, single-instance tool.

+type rateLimiter struct {

+ mu sync.Mutex

+ hits map[string][]time.Time

+}

+

+func newRateLimiter() *rateLimiter { return &rateLimiter{hits: map[string][]time.Time{}} }

+

+func (l *rateLimiter) allow(key string) bool {

+ l.mu.Lock()

+ defer l.mu.Unlock()

+ now := time.Now()

+ cutoff := now.Add(-rateLimitWindow)

+

+ // Compact in place: safe because append never writes past the range

+ // index it's reading from.

+ kept := l.hits[key][:0]

+ for _, t := range l.hits[key] {

+ if t.After(cutoff) {

+ kept = append(kept, t)

+ }

+ }

+ if len(kept) >= rateLimitMax {

+ l.hits[key] = kept

+ return false

+ }

+ l.hits[key] = append(kept, now)

+ return true

+}

+

+func humanDuration(d time.Duration) string {

+ switch {

+ case d <= 0:

+ return "0"

+ case d%(24*time.Hour) == 0:

+ days := d / (24 * time.Hour)

+ if days == 1 {

+ return "1 day"

+ }

+ return fmt.Sprintf("%d days", days)

+ case d%time.Hour == 0:

+ hours := d / time.Hour

+ if hours == 1 {

+ return "1 hour"

+ }

+ return fmt.Sprintf("%d hours", hours)

+ default:

+ return d.String()

+ }

+}

+<!doctype html>

+<html lang="en">

+<head>

+<meta charset="utf-8">

+<meta name="viewport" content="width=device-width, initial-scale=1">

+<title>Share link &middot; {{ .Site }}</title>

+<link rel="stylesheet" href="/static/css/base.css">

+<link rel="stylesheet" href="/static/css/share.css">

+</head>

+<body>

+<main class="wrap">

+ <header class="hero">

+ <h1 class="page-title">Password required</h1>

+ <p class="page-subtitle">This share link is password-protected.</p>

+ </header>

+

+ {{ if .Error }}

+ <div class="notice notice-critical"><p>{{ .Error }}</p></div>

+ {{ end }}

+

+ <form method="post" action="{{ .Action }}" class="share-form">

+ <label class="share-field">

+ <span>Password</span>

+ <input type="password" name="password" autofocus>

+ </label>

+ <button class="chip admin-save" type="submit">View</button>

+ </form>

+</main>

+</body>

+</html>

+package site

+

+import (

+ "net/http"

+ "strings"

+

+ "gsg/internal/core"

+)

+

+// CompareRequest parses {range} into the base and head refs. The refs are

+// still resolved by core through gitx.Repo.Resolve; this only splits text.

+func CompareRequest(r *http.Request) (core.Request, error) {

+ rng := r.PathValue("range")

+ // Check three dots first: "a...b" also contains "..".

+ if base, head, ok := strings.Cut(rng, "..."); ok {

+ return core.Request{

+ Ref: head,

+ Range: &core.Range{Base: base, ThreeDot: true},

+ }, nil

+ }

+ if base, head, ok := strings.Cut(rng, ".."); ok {

+ return core.Request{

+ Ref: head,

+ Range: &core.Range{Base: base},

+ }, nil

+ }

+ return core.Request{}, core.Errorf(http.StatusBadRequest, "compare needs base..head")

+}

+package site

+

+import (

+ "net/http/httptest"

+ "testing"

+)

+

+func TestCompareRequest(t *testing.T) {

+ cases := []struct {

+ name string

+ rangeVal string

+ wantRef string

+ wantBase string

+ threeDot bool

+ wantErr bool

+ }{

+ {name: "two dot", rangeVal: "main..feature", wantRef: "feature", wantBase: "main"},

+ {name: "three dot", rangeVal: "main...feature", wantRef: "feature", wantBase: "main", threeDot: true},

+ {name: "refs with dots", rangeVal: "v1.0..v2.0", wantRef: "v2.0", wantBase: "v1.0"},

+ {name: "missing separator", rangeVal: "main", wantErr: true},

+ }

+

+ for _, tc := range cases {

+ t.Run(tc.name, func(t *testing.T) {

+ req := httptest.NewRequest("GET", "/demo/compare/"+tc.rangeVal, nil)

+ req.SetPathValue("range", tc.rangeVal)

+ got, err := CompareRequest(req)

+ if tc.wantErr {

+ if err == nil {

+ t.Fatal("expected an error")

+ }

+ return

+ }

+ if err != nil {

+ t.Fatalf("CompareRequest: %v", err)

+ }

+ if got.Ref != tc.wantRef || got.Range == nil || got.Range.Base != tc.wantBase || got.Range.ThreeDot != tc.threeDot {

+ t.Fatalf("CompareRequest = %+v, want ref=%q base=%q threeDot=%v", got, tc.wantRef, tc.wantBase, tc.threeDot)

+ }

+ })

+ }

+}

+

+// The compare route must use the parser; the paginated routes must declare

+// their page size. Otherwise buildCtx silently falls back to defaults.

+func TestRoutesDeclareParsingMetadata(t *testing.T) {

+ routes := Routes()

+ byName := make(map[string]struct {

+ request bool

+ pageSize int

+ })

+ for _, rt := range routes {

+ byName[rt.Name] = struct {

+ request bool

+ pageSize int

+ }{

+ request: rt.Request != nil,

+ pageSize: rt.PageSize,

+ }

+ }

+

+ if !byName["compare"].request {

+ t.Error("compare route has no Request parser")

+ }

+ if byName["log"].pageSize == 0 {

+ t.Error("log route has no PageSize")

+ }

+ if byName["graph"].pageSize == 0 {

+ t.Error("graph route has no PageSize")

+ }

+}

+ {Name: "index", Scope: core.ScopeSite, CacheableAnon: true,

+ // NavLabel order below is the order tabs appear in the repo-scoped

+ // nav (top bar and page-nav chips) -- see core.BuildNav.

+ {Name: "repo", CacheableAnon: true,

+ Render: core.View{Template: "tree.html"}},

+ {Name: "tree", NavLabel: "files", CacheableAnon: true,

+ {Name: "log", NavLabel: "log", CacheableAnon: true,

+ Pattern: "GET /{repo}/log/{rest...}",

+ Render: core.View{Template: "log.html"},

+ PageSize: core.LogPageSize},

+

+ // The DAG across every ref. {rest...} carries only a ref (never a

+ // path, there's nothing to browse into) -- it exists purely so the

+ // selected branch survives navigating here and back out again.

+ {Name: "graph", NavLabel: "graph", CacheableAnon: true,

+ Pattern: "GET /{repo}/graph/{rest...}",

+ Render: core.View{Template: "graph.html"},

+ PageSize: core.GraphPageSize},

+

+ {Name: "refs", NavLabel: "refs", CacheableAnon: true,

+ Pattern: "GET /{repo}/refs/{rest...}",

+ Render: core.View{Template: "refs.html"}},

+ // Arbitrary two-commit diff: /demo/compare/main...feature. Not

+ // CacheableAnon: a diff body is bounded only by MaxGit (16 MiB,

+ // larger than a blob preview), and every valid ref pair is a

+ // distinct key -- a repo with N refs has ~N^2 reachable ones. The

+ // response cache has no size-aware eviction, so this route would

+ // risk filling it with a few huge entries for no real hit-rate

+ // benefit (see internal/core/route.go's CacheableAnon doc).

+ Render: core.View{Template: "compare.html"},

+ Request: CompareRequest},

+# gsg — a modular git browser

+

+cgit's weight, Hugo's composability, served dynamically. A **module**

+computes one piece of a view; a **route** binds a renderer to a URL pattern.

+Adding a feature means adding a module and calling it from a template —

+`internal/core` never changes.

+

+One dependency (`goldmark`, which itself has none) plus the `git` binary. Go 1.22+ (uses `net/http`

+pattern wildcards, so there is no router dependency either).

+

+```

+go build -o gsg .

+./gsg -root /srv/git -addr :8080 -name "rschanz.org"

+./gsg -root /srv/git -templates ./templates # re-parse the theme per request

+./gsg -root /srv/git -notices /etc/gsg/notices.yaml -admin-addr 127.0.0.1:8081

+```

+

+## The idea

+

+```go

+type Module func(c *Ctx, args ...string) (any, error)

+```

+

+Templates reach modules through one funcmap entry:

+

+```gotmpl

+{{ with mod "meta" }}<h1>{{ .Title }}</h1>{{ end }}

+{{ $d := mod "diff" }}

+{{ with modOr "readme" }}{{ .HTML }}{{ end }}

+```

+

+- **Lazy.** A template that calls `mod "authors"` is what *causes* authors to

+ be computed. Views that don't ask don't pay.

+- **Memoized twice.** Once per request (`Ctx.cache`), and once process-wide

+ against the resolved commit SHA (`core.LRU`).

+- **No manifest.** Dependencies are declared by use. There is no module list

+ to keep in sync with the templates.

+

+`internal/modules/example_authors.go` is a live demonstration: 30 lines, an

+`init()`, and one `{{ with mod "authors" }}` block. Nothing else moved.

+

+## Pages and endpoints are the same mechanism

+

+A route is `{pattern, renderer}`. `core.View` renders a template,

+`core.JSON` serializes an endpoint. Both take a `*Ctx`, both call modules.

+

+```go

+{Name: "commit", Immutable: true,

+ Pattern: "GET /{repo}/commit/{rev}",

+ Render: core.View{Template: "commit.html"}},

+

+{Name: "api-commit", Immutable: true,

+ Pattern: "GET /{repo}/api/commit/{rev}",

+ Render: core.JSON{Build: api.CommitEndpoint}},

+```

+

+### Endpoints use DTOs, not module values

+

+`internal/api` defines explicit structs and never marshals a module's return

+value. Go marshals every exported field by default, so serializing a module

+type means the day someone adds `Body` to `gitx.Commit`, commit messages are

+public. The allowlist is one readable file.

+

+```

+GET /api/repos.json site index

+GET /{repo}/api/repo.json slug, title, description, owner, section,

+ clone_url, default_branch, last_commit

+GET /{repo}/api/commit/{sha} sha, short, authored, parents, and

+ file/line counts — no subject, no body

+```

+

+## Routes

+

+| Route | URL |

+|---|---|

+| index | `/` |

+| repo | `/{repo}/` — default branch, last update, latest commit, README |

+| files | `/{repo}/tree/{ref}/{path}` |

+| file | `/{repo}/blob/{ref}/{path}` |

+| **raw bytes** | `/{repo}/raw/{ref}/{path}` |

+| log | `/{repo}/log/{ref}` |

+| refs | `/{repo}/refs/` |

+| commit | `/{repo}/commit/{sha}` |

+| **compare** | `/{repo}/compare/{base}..{head}` or `{base}...{head}` |

+| **branch graph** | `/{repo}/graph/` |

+

+### Compare

+

+`a..b` is the literal endpoint difference. `a...b` diffs from the merge

+base, which is what you want when reviewing a branch — it excludes changes

+that landed on the base since the branch forked. Verified against

+`git merge-base` on a diverged fixture: `topic..main` lists `topic.txt` as

+removed, `topic...main` does not.

+

+### Raw files

+

+A repository can contain an `.html` file with a `<script>` tag. Serving that

+as `text/html` on your own origin turns any push into stored XSS against the

+whole site — which is why GitHub puts raw content on

+`raw.githubusercontent.com`, a separate origin. Same-host serving is only

+safe if the response cannot be interpreted as a document, so `/raw/` sends

+`text/plain` (or `application/octet-stream` for binaries, plus

+`Content-Disposition: attachment`), with `X-Content-Type-Options: nosniff`

+and `Content-Security-Policy: default-src \'none\'; sandbox` as a backstop.

+

+The exception is a validated raster image (PNG, JPEG, GIF, WebP, BMP, ICO,

+AVIF): when the extension and the magic bytes agree, `/raw/` declares the

+real `image/*` type inline so the blob page can preview it. An extension by

+itself is not enough — an `.png` whose contents are HTML still downloads as

+`application/octet-stream`. SVG is deliberately excluded: it is an XML

+document that can execute script, so it stays `text/plain`.

+

+If you would rather have real isolation, serve `/raw/` from a second

+hostname and the CSP becomes belt-and-braces rather than the only line.

+

+### Images and structured config files

+

+An image blob shows an inline preview with a `download` link to the same

+`/raw/` URL; images over 10 MiB skip the preview and offer the download only.

+

+JSON and YAML blobs get per-level indent guides, fold controls, key/value

+search, and YAML anchor/alias links. The search box also accepts a value

+path: typing `obj1.property3.items[4].val` resolves it against the parsed

+document and highlights that line and, for a container, its subtree. A

+query containing `.` or `[` is tried as a path first and falls back to

+plain substring search when it does not resolve, so dotted text stays

+searchable. Paths quote keys that need it (`obj1["a.b"]`) and attach indices

+directly; SVG is never previewed, and files past 512 KiB skip the parsing

+tooling entirely.

+

+### Branch graph

+

+`modules/graph.go` lays out the DAG in lanes in one pass over

+`git log --all --topo-order`, which guarantees a child is emitted before its

+parents. `active` holds, per lane, the SHA that lane is waiting to draw; a

+commit claims the lane expecting it (or a fresh one), hands that lane to its

+first parent, and opens a new lane per additional parent — which is what