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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user