docs(pact,party,surf): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:07:39 +01:00
parent cd55a3980d
commit a2551d83d7
6 changed files with 257 additions and 86 deletions

View File

@@ -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.