docs(phrasebook,sieve,towel,wire,wristband): compile README Go examples via src= (quick-261118-qsd)
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user