docs(pact,party,surf): compile README Go examples via src= (quick-261118-qsd)
This commit is contained in:
@@ -48,58 +48,56 @@ Use cases:
|
||||
|
||||
A plugin declares routes, middleware and a rate-limit bucket; the runtime assembles them:
|
||||
|
||||
```go
|
||||
package blog
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
"git.golem15.com/golem15/summercms/modules/pact"
|
||||
"git.golem15.com/golem15/summercms/modules/surf"
|
||||
"git.golem15.com/golem15/summercms/modules/wire"
|
||||
)
|
||||
|
||||
type Plugin struct{}
|
||||
|
||||
func (Plugin) ID() string { return "acme.blog" }
|
||||
func (Plugin) Requires() []string { return nil }
|
||||
func (Plugin) Register(*backpack.App) error { return nil }
|
||||
func (Plugin) Boot(*backpack.App) error { return nil }
|
||||
|
||||
func (Plugin) Middlewares() map[string]pact.Middleware {
|
||||
return map[string]pact.Middleware{
|
||||
"blog.no-store": func(next http.Handler) http.Handler {
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Cache-Control", "no-store")
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
},
|
||||
```go src=modules/surf/example_test.go#BlogPlugin.Middlewares
|
||||
// Middlewares registers the plugin's named middleware: here, a JWT guard
|
||||
// that answers 401 when the request has no valid token.
|
||||
func (p *BlogPlugin) Middlewares() map[string]pact.Middleware {
|
||||
guards := bouncer.NewRegistry()
|
||||
guard := bouncer.NewJWTGuard(secret, users{}, bouncer.NewMemoryBlacklist())
|
||||
if err := guards.Register(p.ID(), "acme.auth", guard); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
auth, err := guards.Middleware("acme.auth")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return map[string]pact.Middleware{"acme.auth": auth}
|
||||
}
|
||||
```
|
||||
|
||||
func (Plugin) Buckets() map[string]surf.Bucket {
|
||||
```go src=modules/surf/example_test.go#BlogPlugin.Buckets
|
||||
// Buckets declares a named rate limit, used as throttle:blog.comments.
|
||||
func (p *BlogPlugin) Buckets() map[string]surf.Bucket {
|
||||
return map[string]surf.Bucket{
|
||||
"blog.comments": {
|
||||
Max: 5,
|
||||
Max: 1,
|
||||
Decay: time.Minute,
|
||||
Key: func(r *http.Request) string { return "comments|" + surf.ClientIP(r, nil) },
|
||||
Key: func(r *http.Request) string { return "comments|" + surf.ClientIP(r, p.trusted) },
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
func (Plugin) Routes(r pact.Router) error {
|
||||
```go src=modules/surf/example_test.go#BlogPlugin.Routes
|
||||
// Routes is the Go form of the plugin's routes.php.
|
||||
func (p *BlogPlugin) Routes(r pact.Router) error {
|
||||
r.Group("/api/blog", surf.Use("throttle:60,1"), func(g pact.Router) {
|
||||
g.Get("/posts/{id}", showPost)
|
||||
g.Where("id", `[0-9]+`)
|
||||
g.Get("/posts/{status}/list", listPosts, "blog.no-store")
|
||||
g.Get("/posts/{status}/list", listPosts)
|
||||
g.WhereIn("status", "draft", "published")
|
||||
g.Post("/posts/{id}/comments", addComment, "throttle:blog.comments", "body.limit:65536")
|
||||
|
||||
// An auth group: every route inside needs a signed-in user.
|
||||
g.Group("", surf.Use("acme.auth"), func(auth pact.Router) {
|
||||
auth.Get("/me", showMe)
|
||||
auth.Post("/posts/{id}/comments", addComment, "throttle:blog.comments", "body.limit:65536")
|
||||
})
|
||||
})
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
```go src=modules/surf/example_test.go#showPost
|
||||
func showPost(w http.ResponseWriter, r *http.Request) {
|
||||
id, ok := surf.IntParam(r, "id")
|
||||
if !ok {
|
||||
@@ -108,9 +106,6 @@ func showPost(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
wire.WriteJSON(w, http.StatusOK, map[string]any{"id": id})
|
||||
}
|
||||
|
||||
func listPosts(w http.ResponseWriter, r *http.Request) { wire.WriteJSON(w, http.StatusOK, []string{}) }
|
||||
func addComment(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusCreated) }
|
||||
```
|
||||
|
||||
Routes ported from a `routes.php` sometimes overlap: `GET /shelves/items/{id}` with `id` numeric and `GET /shelves/{shelfId}/follow` with `shelfId` numeric both match `/shelves/items/follow` as patterns, so ServeMux alone would refuse to register them. surf registers such routes as an overlap family and tries them in registration order, checking literal segments and `Where` constraints, so declare them in the same order as the PHP file. A request no member matches gets the bare 404. Overlapping routes must use literal segments and single-segment `{name}` wildcards; two routes of one method with the same shape, a `{name...}` wildcard in a family, or a more general route that would take a member's requests still fail at boot. `surf.Router.Routes` and `route:list` keep listing every route on its own.
|
||||
|
||||
Reference in New Issue
Block a user