docs(phrasebook,sieve,towel,wire,wristband): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:01:05 +01:00
parent c517db564c
commit 6409837b0c
12 changed files with 509 additions and 148 deletions

View File

@@ -53,32 +53,43 @@ A request that no route matches, or that uses a method its path does not accept,
WinterCMS reads the current locale and user through facades. SummerCMS carries them on the request's `context.Context`. surf stores the locale with `towel.WithLocale`, the authentication middleware stores the signed-in principal, and your own middleware can add the organization or collection with `towel.WithOrganization` and `towel.WithCollection`. Any code that receives the context reads them back without a global lookup:
```go src=modules/towel/example_test.go#ExampleWithLocale
// A middleware stores the organization once for the whole request.
withAcme := func(next http.Handler) http.Handler {
```go src=modules/towel/example_test.go#withAcmeScope
// withAcmeScope tags every request with the organization and collection it serves.
func withAcmeScope(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := towel.WithOrganization(r.Context(), "acme")
ctx = towel.WithCollection(ctx, "blog")
next.ServeHTTP(w, r.WithContext(ctx))
})
}
```
// The handler reads the values back from its request context.
listPosts := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
```go src=modules/towel/example_test.go#listPosts
func listPosts(w http.ResponseWriter, r *http.Request) {
org, _ := towel.Organization(r.Context())
locale, ok := towel.Locale(r.Context())
if !ok {
locale = "en"
}
fmt.Fprintf(w, "posts for %s in %s", org, locale)
})
fmt.Fprintf(w, "posts for %s in %s\n", org, locale)
}
```
```go src=modules/towel/example_test.go#ExampleWithLocale
// surf sets the locale from Accept-Language; here the test sets it.
req := httptest.NewRequest(http.MethodGet, "/api/blog/posts", nil)
req = req.WithContext(towel.WithLocale(req.Context(), "pl"))
rec := httptest.NewRecorder()
withAcme(listPosts).ServeHTTP(rec, req)
fmt.Println(rec.Body.String())
// Output: posts for acme in pl
withAcmeScope(http.HandlerFunc(listPosts)).ServeHTTP(rec, req)
fmt.Print(rec.Body.String())
// Without a locale the handler falls back to English.
rec = httptest.NewRecorder()
withAcmeScope(http.HandlerFunc(listPosts)).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/blog/posts", nil))
fmt.Print(rec.Body.String())
// Output:
// posts for acme in pl
// posts for acme in en
```
## Writing responses

View File

@@ -27,12 +27,15 @@ wristband reads no configuration keys. The application builds a `wristband.Optio
// newServer builds the authorization server of an application served at
// https://blog.example.com. The application sets Issuer and Resource for
// its own deployment; the defaults cover everything else.
func newServer() *wristband.Server {
func newServer(backend wristband.Backend) *wristband.Server {
opts := wristband.DefaultOptions()
opts.Issuer = "https://blog.example.com"
opts.Issuer = "https://blog.example.com" // app URL without a trailing slash
opts.Resource = "https://blog.example.com/mcp"
opts.ScopesSupported = []string{"read", "write", "offline_access"}
return wristband.NewServer(opts)
srv := wristband.NewServer(opts)
srv.SetBackend(backend) // the application's transactional store adapter
return srv
}
```
@@ -44,9 +47,8 @@ The defaults cover the rest: pending requests and codes live 10 minutes, access
The MCP advertised set is that resolved list. The fixed names `read`, `write`, `ai`, `offline_access` and `backend` are always on it. Declared member scopes (`pact.FrontendTokenScope`, including `pact.FrontendTokenScope.Implies`) come from the published `pact.MemberTokenScopeCatalog` and are filtered by the OAuth server plugin's key `golem15.oauthserver.mcp_scopes`. That key is the plugin's, not a framework config key: unset means every declared member scope, a set filter means only those declared names, and an empty filter means the five fixed names only. The plugin publishes the list as `pact.MCPAdvertisedScopes`. pier copies `pact.MCPAdvertisedScopes.MCPScopesSupported` when it is non-empty and otherwise keeps `pier.PRMScopes`. The read/write ceiling is unchanged. A route the endpoint runs reads the caller with `pact.MCPCallFrom`: `pact.MCPSubject.TokenID` is a member personal-token id only when `pact.MCPSubject.ClientID` is empty, and the OAuth access-token row otherwise, and `pact.MCPSubject.Scopes` is the grant, not an implied expansion. The metadata document serves the configured values:
```go src=modules/wristband/example_test.go#ExampleServer_Metadata
srv := newServer()
// srv.SetBackend(backend) attaches the application's stores; the
// metadata document does not need them.
// The metadata document does not need the application's stores.
srv := newServer(nil)
rec := httptest.NewRecorder()
srv.Metadata(rec, httptest.NewRequest("GET", "/.well-known/oauth-authorization-server", nil))
@@ -180,12 +182,12 @@ func newOIDCServer(backend wristband.OIDCBackend, keys wristband.KeyStore, host
opts.Issuer = "https://id.example.com"
oidc := wristband.DefaultOIDCOptions()
oidc.LoginURL = "/account/login"
oidc.RefreshEnabled = true // only clients with OfflineAccess get refresh tokens
oidc.LoginURL = "/account/login" // anonymous users land here with ?redirect=<resume path>
oidc.RefreshEnabled = true // only clients with OfflineAccess get refresh tokens
srv := wristband.NewOIDCServer(opts, oidc)
if err := srv.SetOIDCBackend(backend, keys, host); err != nil {
return nil, err
return nil, err // nil argument, or called on an MCP server
}
return srv, nil
}