docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd)

- backpack: Greeter and ExampleApp_Publish replace the whole-file fence
- beachcomber: Post's Searchable methods plus a new SearchIndexSchema, a
  Plugin.Boot that installs the gate, and the existing gate/search regions
- boardwalk: new example_test.go; the mount region runs in ExampleHandler
- bonfire: importPostsCommand and acmeMain (the binary's main as a function
  returning the exit code), run by ExampleExecute; ExampleCatalog_Has
- bouncer: users/FindByID and ExampleNewJWTGuard; RefreshRoute run by
  TestDocsRefreshRoute on a production compass config
This commit is contained in:
Jakub Zych
2026-11-18 19:39:50 +01:00
parent 48527e4206
commit a0f5b5e561
9 changed files with 366 additions and 125 deletions

View File

@@ -39,64 +39,56 @@ Use cases:
## Usage
```go
package blog
import (
"context"
"fmt"
"net/http"
"time"
"git.golem15.com/golem15/summercms/modules/bouncer"
)
```go src=modules/bouncer/example_test.go#users
// users loads the principal behind a token subject.
type users struct{}
```
```go src=modules/bouncer/example_test.go#users.FindByID
// FindByID loads the user behind a token subject; nil means "not found".
func (users) FindByID(ctx context.Context, id uint) (*bouncer.Principal, error) {
return &bouncer.Principal{ID: id, PreferredLocale: "en"}, nil
return &bouncer.Principal{ID: id, PreferredLocale: "pl"}, nil
}
```
func Routes(secret string) (http.Handler, error) {
guards := bouncer.NewRegistry()
guard := bouncer.NewJWTGuard(secret, users{}, bouncer.NewMemoryBlacklist(), "token")
if err := guards.Register("acme.blog", "jwt", guard); err != nil {
return nil, err
}
auth, err := guards.Middleware("jwt")
if err != nil {
return nil, err
}
mux := http.NewServeMux()
mux.Handle("GET /api/me", auth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
user, _ := bouncer.User(r.Context())
fmt.Fprintf(w, "user %d", user.ID)
})))
return mux, nil
```go src=modules/bouncer/example_test.go#ExampleNewJWTGuard
guards := bouncer.NewRegistry()
guard := bouncer.NewJWTGuard(testSecret, users{}, bouncer.NewMemoryBlacklist(), "token")
if err := guards.Register("acme.blog", "acme.auth", guard); err != nil {
fmt.Println(err)
return
}
func Login(secret string) (string, error) {
token, _, err := bouncer.Mint(secret, "42", "https://example.com/api/login", time.Hour)
return token, err
auth, err := guards.Middleware("acme.auth")
if err != nil {
fmt.Println(err)
return
}
me := auth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
user, _ := bouncer.User(r.Context())
fmt.Fprintf(w, "user %d, locale %s", user.ID, user.PreferredLocale)
}))
token, _, _ := bouncer.Mint(testSecret, "42", "http://127.0.0.1:8080/api/login", time.Hour)
for _, set := range []func(*http.Request){
func(r *http.Request) {},
func(r *http.Request) { r.Header.Set("Authorization", "Bearer "+token) },
func(r *http.Request) { r.AddCookie(&http.Cookie{Name: "token", Value: token}) },
} {
req := httptest.NewRequest("GET", "/api/me", nil)
set(req)
rec := httptest.NewRecorder()
me.ServeHTTP(rec, req)
fmt.Println(rec.Code, strings.TrimSpace(rec.Body.String()))
}
// Output:
// 401 {"error":true,"message":"Token not provided"}
// 200 user 42, locale pl
// 200 user 42, locale pl
```
An application that keeps the token in an httpOnly cookie, for a frontend on `www.example.com` calling the API on `api.example.com`, loads the cookie config at boot and mounts the refresh handler on a POST route:
```go
package acme
import (
"context"
"encoding/json"
"net/http"
"time"
"git.golem15.com/golem15/summercms/modules/bouncer"
)
```go src=modules/bouncer/example_test.go#RefreshRoute
// RefreshRoute rotates the cookie's token. cfg is the app config
// (app.Config); users, secret and bl are the guard's; refreshTTL is its
// refresh_ttl.