docs(cooler,diary,festival,fetchguard): compile README Go examples via src= (quick-261118-qsd)
- cooler: ExampleFromApp and the articlesController purge declarations; AllowExport run by TestDocsAllowExport on miniredis - diary: blogLog and ExampleFor; the generated main's run function, run by TestDocsRun in a temp directory with diary.Reset on cleanup - festival: PostPublished/ExampleBus_Fire and PostFormExtended/Collected/ ExampleBus_Collect, with a TestDocsDeclarations for Collected - fetchguard: fetch region run by TestDocsFetchImage (loopback refused as private_ip), client region run by TestDocsSyncItems on a stub transport
This commit is contained in:
@@ -46,25 +46,35 @@ Use cases:
|
|||||||
|
|
||||||
A plugin or job reads and writes the cache the framework published:
|
A plugin or job reads and writes the cache the framework published:
|
||||||
|
|
||||||
```go
|
```go src=modules/cooler/example_test.go#ExampleFromApp
|
||||||
package blog
|
// serve publishes the Cache at start-up; a job or console command asks
|
||||||
|
// FromApp, which builds the configured driver (memory here) once.
|
||||||
import (
|
app := backpack.New(nil)
|
||||||
"context"
|
cache, err := cooler.FromApp(app)
|
||||||
"time"
|
if err != nil {
|
||||||
|
fmt.Println(err)
|
||||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
return
|
||||||
"git.golem15.com/golem15/summercms/modules/cooler"
|
|
||||||
)
|
|
||||||
|
|
||||||
// Sidebar returns the rendered sidebar, cached for five minutes.
|
|
||||||
func Sidebar(ctx context.Context, app *backpack.App, render func(context.Context) ([]byte, error)) ([]byte, error) {
|
|
||||||
cache, err := cooler.FromApp(app)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
return cache.Remember(ctx, "blog:sidebar", 5*time.Minute, render)
|
|
||||||
}
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
loads := 0
|
||||||
|
popular := func(context.Context) ([]byte, error) {
|
||||||
|
loads++
|
||||||
|
return json.Marshal([]string{"Hello", "Summer"})
|
||||||
|
}
|
||||||
|
var titles []string
|
||||||
|
for range 2 {
|
||||||
|
raw, err := cache.Remember(ctx, "blog:popular", 10*time.Minute, popular)
|
||||||
|
if err != nil {
|
||||||
|
fmt.Println(err)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
if err := json.Unmarshal(raw, &titles); err != nil {
|
||||||
|
fmt.Println(err)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
}
|
||||||
|
fmt.Println(titles, loads)
|
||||||
|
// Output: [Hello Summer] 1
|
||||||
```
|
```
|
||||||
|
|
||||||
`cooler.FromApp` returns the Cache `serve` published, so in a request handler `app.Lookup[cooler.Cache]()` works as well. In a separate `queue:work` process or a console command, `cooler.FromApp` builds the configured Cache the first time.
|
`cooler.FromApp` returns the Cache `serve` published, so in a request handler `app.Lookup[cooler.Cache]()` works as well. In a separate `queue:work` process or a console command, `cooler.FromApp` builds the configured Cache the first time.
|
||||||
@@ -93,51 +103,46 @@ Nothing else changes: routes keep `throttle:60,1` or `throttle:<bucket>`, and `s
|
|||||||
|
|
||||||
An admin controller purges the host site's page cache after its saves. The hook runs inside the save transaction, and the purge waits for the commit:
|
An admin controller purges the host site's page cache after its saves. The hook runs inside the save transaction, and the purge waits for the commit:
|
||||||
|
|
||||||
```go
|
```go src=modules/cooler/example_test.go#Article
|
||||||
package blog
|
// Article is a blog's article model.
|
||||||
|
|
||||||
import (
|
|
||||||
"context"
|
|
||||||
|
|
||||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
|
||||||
"git.golem15.com/golem15/summercms/modules/cabana"
|
|
||||||
"git.golem15.com/golem15/summercms/modules/cooler"
|
|
||||||
)
|
|
||||||
|
|
||||||
// Article is the blog's article model.
|
|
||||||
type Article struct {
|
type Article struct {
|
||||||
Slug string
|
Slug string
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```go src=modules/cooler/example_test.go#articlesController
|
||||||
|
// articlesController is a blog's admin controller (its pact.AdminController
|
||||||
|
// methods are left out here).
|
||||||
type articlesController struct {
|
type articlesController struct {
|
||||||
app func() *backpack.App
|
app func() *backpack.App
|
||||||
}
|
}
|
||||||
|
```
|
||||||
|
|
||||||
// FormAfterUpdate purges the site cache once the save commits.
|
```go src=modules/cooler/example_test.go#articlesController.purge
|
||||||
func (c articlesController) FormAfterUpdate(ctx context.Context, model any) error {
|
// purge queues one site-cache purge for the saved article once the save
|
||||||
tx, ok := cabana.TxFromContext(ctx)
|
// transaction commits (at once outside one); the save never waits for the
|
||||||
|
// site. Without a purge configured the purger is nil and nothing is sent.
|
||||||
|
func (c articlesController) purge(ctx context.Context, model any) error {
|
||||||
|
article, ok := model.(*Article)
|
||||||
if !ok {
|
if !ok {
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
purger := cooler.SiteCacheFromApp(c.app())
|
tx, _ := cabana.TxFromContext(ctx)
|
||||||
cooler.PurgeSiteCacheAfterCommit(ctx, tx, purger, "article", model.(*Article).Slug)
|
cooler.PurgeSiteCacheAfterCommit(ctx, tx, cooler.SiteCacheFromApp(c.app()), "article", article.Slug)
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
```go src=modules/cooler/example_test.go#articlesController.FormAfterUpdate
|
||||||
|
// FormAfterUpdate runs inside the update's transaction.
|
||||||
|
func (c articlesController) FormAfterUpdate(ctx context.Context, model any) error {
|
||||||
|
return c.purge(ctx, model)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
A tool outside `serve` can use the store directly:
|
A tool outside `serve` can use the store directly:
|
||||||
|
|
||||||
```go
|
```go src=modules/cooler/example_test.go#AllowExport
|
||||||
package blog
|
|
||||||
|
|
||||||
import (
|
|
||||||
"context"
|
|
||||||
"time"
|
|
||||||
|
|
||||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
|
||||||
"git.golem15.com/golem15/summercms/modules/cooler"
|
|
||||||
)
|
|
||||||
|
|
||||||
// AllowExport admits five exports a minute per user across all instances.
|
// AllowExport admits five exports a minute per user across all instances.
|
||||||
func AllowExport(ctx context.Context, app *backpack.App, fallback cooler.Attempter, userKey string) (bool, error) {
|
func AllowExport(ctx context.Context, app *backpack.App, fallback cooler.Attempter, userKey string) (bool, error) {
|
||||||
client, err := cooler.OpenRedis(ctx, app.Config.String(cooler.RedisURLKey))
|
client, err := cooler.OpenRedis(ctx, app.Config.String(cooler.RedisURLKey))
|
||||||
|
|||||||
@@ -8,6 +8,7 @@ import (
|
|||||||
"net/http"
|
"net/http"
|
||||||
"net/http/httptest"
|
"net/http/httptest"
|
||||||
"os"
|
"os"
|
||||||
|
"testing"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||||
@@ -15,6 +16,8 @@ import (
|
|||||||
"git.golem15.com/golem15/summercms/modules/compass"
|
"git.golem15.com/golem15/summercms/modules/compass"
|
||||||
"git.golem15.com/golem15/summercms/modules/cooler"
|
"git.golem15.com/golem15/summercms/modules/cooler"
|
||||||
"git.golem15.com/golem15/summercms/modules/pact"
|
"git.golem15.com/golem15/summercms/modules/pact"
|
||||||
|
"git.golem15.com/golem15/summercms/modules/surf"
|
||||||
|
"github.com/alicebob/miniredis/v2"
|
||||||
)
|
)
|
||||||
|
|
||||||
func ExampleFromApp() {
|
func ExampleFromApp() {
|
||||||
@@ -157,3 +160,42 @@ func ExampleSiteCacheFromApp() {
|
|||||||
}
|
}
|
||||||
// Output: POST /api/__site__/cache/purge {"kind":"article","slug":"hello-summer"}
|
// Output: POST /api/__site__/cache/purge {"kind":"article","slug":"hello-summer"}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// AllowExport admits five exports a minute per user across all instances.
|
||||||
|
func AllowExport(ctx context.Context, app *backpack.App, fallback cooler.Attempter, userKey string) (bool, error) {
|
||||||
|
client, err := cooler.OpenRedis(ctx, app.Config.String(cooler.RedisURLKey))
|
||||||
|
if err != nil {
|
||||||
|
return false, err
|
||||||
|
}
|
||||||
|
defer client.Close()
|
||||||
|
store := cooler.NewRateLimitStore(client, "acme:", fallback)
|
||||||
|
allowed, _, _ := store.Attempt("export|"+userKey, 5, time.Minute)
|
||||||
|
return allowed, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestDocsAllowExport runs AllowExport on miniredis: a user's sixth export
|
||||||
|
// in a minute is refused, and another user's first one passes.
|
||||||
|
func TestDocsAllowExport(t *testing.T) {
|
||||||
|
mr := miniredis.RunT(t)
|
||||||
|
cfg, err := compass.Open(compass.Options{Dir: t.TempDir(), Environ: []string{"SUMMER_REDIS__URL=redis://" + mr.Addr() + "/0"}})
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
app := backpack.New(cfg)
|
||||||
|
fallback := surf.NewMemoryStore(0)
|
||||||
|
for i := 1; i <= 6; i++ {
|
||||||
|
allowed, err := AllowExport(t.Context(), app, fallback, "user:7")
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if allowed != (i <= 5) {
|
||||||
|
t.Fatalf("export %d allowed = %v", i, allowed)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if allowed, err := AllowExport(t.Context(), app, fallback, "user:8"); err != nil || !allowed {
|
||||||
|
t.Fatalf("another user's export = %v, %v", allowed, err)
|
||||||
|
}
|
||||||
|
if len(mr.Keys()) == 0 {
|
||||||
|
t.Fatal("the store wrote no key to Redis")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -41,12 +41,31 @@ Use cases:
|
|||||||
|
|
||||||
A plugin or module creates its logger once:
|
A plugin or module creates its logger once:
|
||||||
|
|
||||||
```go
|
```go src=modules/diary/example_test.go#blogLog
|
||||||
var logger = diary.For("blog")
|
// blogLog is the component logger of a blog plugin, created once in a
|
||||||
|
// package var block, before diary is set up.
|
||||||
|
var blogLog = diary.For("blog")
|
||||||
|
```
|
||||||
|
|
||||||
func publish(ctx context.Context, id int) {
|
```go src=modules/diary/example_test.go#ExampleFor
|
||||||
logger.InfoContext(ctx, "post published", "id", id)
|
// Before diary.Setup runs, records go to the process default logger.
|
||||||
}
|
// This one drops the time so the output is stable.
|
||||||
|
previous := slog.Default()
|
||||||
|
defer slog.SetDefault(previous)
|
||||||
|
slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
|
||||||
|
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
|
||||||
|
if len(groups) == 0 && a.Key == slog.TimeKey {
|
||||||
|
return slog.Attr{}
|
||||||
|
}
|
||||||
|
return a
|
||||||
|
},
|
||||||
|
})))
|
||||||
|
|
||||||
|
// After diary.Setup the same record reaches the configured channels and
|
||||||
|
// passes log.components.blog, else log.level.
|
||||||
|
blogLog.InfoContext(context.Background(), "post published", "id", 7)
|
||||||
|
// Output:
|
||||||
|
// level=INFO msg="post published" component=blog id=7
|
||||||
```
|
```
|
||||||
|
|
||||||
With the default configuration this prints on a terminal:
|
With the default configuration this prints on a terminal:
|
||||||
@@ -59,8 +78,10 @@ and writes warnings and errors as JSON to `storage/logs/summer-YYYY-MM-DD.log`.
|
|||||||
|
|
||||||
The generated `main` installs it:
|
The generated `main` installs it:
|
||||||
|
|
||||||
```go
|
```go src=modules/diary/example_test.go#run
|
||||||
func run(args []string, out io.Writer) int {
|
// run is the body of the generated main, which calls
|
||||||
|
// os.Exit(run(os.Args[1:], os.Stdout, commands)).
|
||||||
|
func run(args []string, out io.Writer, commands []bonfire.Command) int {
|
||||||
g := bonfire.PeekGlobals(args)
|
g := bonfire.PeekGlobals(args)
|
||||||
diary.Bootstrap(os.Stderr, diary.FromGlobals(g))
|
diary.Bootstrap(os.Stderr, diary.FromGlobals(g))
|
||||||
cfg, err := compass.Open(compass.Options{Dir: "config", Env: g.Env})
|
cfg, err := compass.Open(compass.Options{Dir: "config", Env: g.Env})
|
||||||
@@ -70,10 +91,12 @@ func run(args []string, out io.Writer) int {
|
|||||||
if err := diary.Setup(cfg, diary.FromGlobals(g)); err != nil {
|
if err := diary.Setup(cfg, diary.FromGlobals(g)); err != nil {
|
||||||
return bonfire.Fail(os.Stderr, "acme", err, g)
|
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||||
}
|
}
|
||||||
// ...
|
|
||||||
root, err := bonfire.NewRoot("acme", commands, out,
|
root, err := bonfire.NewRoot("acme", commands, out,
|
||||||
bonfire.WithVersion(bonfire.BuildVersion()), bonfire.OnGlobals(diary.ApplyGlobals))
|
bonfire.WithVersion(bonfire.BuildVersion()), bonfire.OnGlobals(diary.ApplyGlobals))
|
||||||
// ...
|
if err != nil {
|
||||||
|
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||||
|
}
|
||||||
|
return bonfire.Execute(context.Background(), root, args)
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -1,10 +1,15 @@
|
|||||||
package diary_test
|
package diary_test
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
"bytes"
|
||||||
"context"
|
"context"
|
||||||
|
"io"
|
||||||
"log/slog"
|
"log/slog"
|
||||||
"os"
|
"os"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
"git.golem15.com/golem15/summercms/modules/bonfire"
|
||||||
|
"git.golem15.com/golem15/summercms/modules/compass"
|
||||||
"git.golem15.com/golem15/summercms/modules/diary"
|
"git.golem15.com/golem15/summercms/modules/diary"
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -32,3 +37,49 @@ func ExampleFor() {
|
|||||||
// Output:
|
// Output:
|
||||||
// level=INFO msg="post published" component=blog id=7
|
// level=INFO msg="post published" component=blog id=7
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// run is the body of the generated main, which calls
|
||||||
|
// os.Exit(run(os.Args[1:], os.Stdout, commands)).
|
||||||
|
func run(args []string, out io.Writer, commands []bonfire.Command) int {
|
||||||
|
g := bonfire.PeekGlobals(args)
|
||||||
|
diary.Bootstrap(os.Stderr, diary.FromGlobals(g))
|
||||||
|
cfg, err := compass.Open(compass.Options{Dir: "config", Env: g.Env})
|
||||||
|
if err != nil {
|
||||||
|
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||||
|
}
|
||||||
|
if err := diary.Setup(cfg, diary.FromGlobals(g)); err != nil {
|
||||||
|
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||||
|
}
|
||||||
|
root, err := bonfire.NewRoot("acme", commands, out,
|
||||||
|
bonfire.WithVersion(bonfire.BuildVersion()), bonfire.OnGlobals(diary.ApplyGlobals))
|
||||||
|
if err != nil {
|
||||||
|
return bonfire.Fail(os.Stderr, "acme", err, g)
|
||||||
|
}
|
||||||
|
return bonfire.Execute(context.Background(), root, args)
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestDocsRun runs a command through run in an application directory
|
||||||
|
// without a config/ directory, then restores the process logger.
|
||||||
|
func TestDocsRun(t *testing.T) {
|
||||||
|
t.Chdir(t.TempDir())
|
||||||
|
t.Cleanup(diary.Reset)
|
||||||
|
publish := bonfire.Command{
|
||||||
|
Name: "blog:publish",
|
||||||
|
Description: "Publish a post",
|
||||||
|
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
|
||||||
|
blogLog.InfoContext(ctx, "post published", "id", 7)
|
||||||
|
out.Println("published")
|
||||||
|
return nil
|
||||||
|
},
|
||||||
|
}
|
||||||
|
var out bytes.Buffer
|
||||||
|
if code := run([]string{"blog:publish", "-vv"}, &out, []bonfire.Command{publish}); code != bonfire.ExitOK {
|
||||||
|
t.Fatalf("exit code %d, output %q", code, out.String())
|
||||||
|
}
|
||||||
|
if out.String() != "published\n" {
|
||||||
|
t.Fatalf("output = %q", out.String())
|
||||||
|
}
|
||||||
|
if diary.Verbosity() != 2 {
|
||||||
|
t.Fatalf("verbosity = %d after -vv, want 2", diary.Verbosity())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -33,39 +33,65 @@ Use cases:
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
```go
|
```go src=modules/festival/example_test.go#PostPublished
|
||||||
package blog
|
// PostPublished is the event the acme.blog plugin fires after a post goes live.
|
||||||
|
|
||||||
import (
|
|
||||||
"context"
|
|
||||||
|
|
||||||
"git.golem15.com/golem15/summercms/modules/festival"
|
|
||||||
)
|
|
||||||
|
|
||||||
// PostPublished is fired after a post goes live. Listeners add payload
|
|
||||||
// entries and may mark the event handled.
|
|
||||||
type PostPublished struct {
|
type PostPublished struct {
|
||||||
PostID uint
|
Title string
|
||||||
payload map[string]any
|
|
||||||
handled bool
|
|
||||||
}
|
|
||||||
|
|
||||||
func (e *PostPublished) Collected() map[string]any { return e.payload }
|
|
||||||
func (e *PostPublished) IsHandled() bool { return e.handled }
|
|
||||||
|
|
||||||
func publish(ctx context.Context, bus *festival.Bus) (map[string]any, error) {
|
|
||||||
bus.ListenPriority("acme.search", 10, func(ctx context.Context, e *PostPublished) error {
|
|
||||||
if e.payload == nil {
|
|
||||||
e.payload = map[string]any{}
|
|
||||||
}
|
|
||||||
e.payload["indexed"] = true
|
|
||||||
return nil
|
|
||||||
})
|
|
||||||
return bus.Collect(ctx, &PostPublished{PostID: 42})
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
The event type is inferred from the listener's parameter, so this listener only receives `*PostPublished` events. In a plugin, the bus is `app.Events` on the `backpack.App` passed to Boot; `festival.New` is for tests and standalone use.
|
```go src=modules/festival/example_test.go#ExampleBus_Fire
|
||||||
|
bus := festival.New() // in a plugin, use app.Events
|
||||||
|
|
||||||
|
// acme.search and acme.notify extend acme.blog from their Boot steps.
|
||||||
|
bus.Listen("acme.search", func(ctx context.Context, e PostPublished) error {
|
||||||
|
fmt.Println("index", e.Title)
|
||||||
|
return nil
|
||||||
|
})
|
||||||
|
bus.ListenPriority("acme.notify", 10, func(ctx context.Context, e PostPublished) error {
|
||||||
|
fmt.Println("notify subscribers of", e.Title)
|
||||||
|
return nil
|
||||||
|
})
|
||||||
|
|
||||||
|
// acme.blog fires the event; higher priorities run first.
|
||||||
|
if err := bus.Fire(context.Background(), PostPublished{Title: "Hello"}); err != nil {
|
||||||
|
fmt.Println(err)
|
||||||
|
}
|
||||||
|
// Output:
|
||||||
|
// notify subscribers of Hello
|
||||||
|
// index Hello
|
||||||
|
```
|
||||||
|
|
||||||
|
The event type is inferred from the listener's parameter, so these listeners only receive `PostPublished` events. Events that listeners modify are pointers; `festival.Bus.Collect` merges what each listener collected:
|
||||||
|
|
||||||
|
```go src=modules/festival/example_test.go#PostFormExtended
|
||||||
|
// PostFormExtended gathers extra fields other plugins add to the post form.
|
||||||
|
type PostFormExtended struct {
|
||||||
|
fields map[string]any
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```go src=modules/festival/example_test.go#PostFormExtended.Collected
|
||||||
|
func (e *PostFormExtended) Collected() map[string]any { return e.fields }
|
||||||
|
```
|
||||||
|
|
||||||
|
```go src=modules/festival/example_test.go#ExampleBus_Collect
|
||||||
|
bus := festival.New()
|
||||||
|
bus.Listen("acme.seo", func(ctx context.Context, e *PostFormExtended) error {
|
||||||
|
e.fields = map[string]any{"meta_title": "text"}
|
||||||
|
return nil
|
||||||
|
})
|
||||||
|
bus.Listen("acme.gallery", func(ctx context.Context, e *PostFormExtended) error {
|
||||||
|
e.fields = map[string]any{"cover": "fileupload"}
|
||||||
|
return nil
|
||||||
|
})
|
||||||
|
|
||||||
|
fields, err := bus.Collect(context.Background(), &PostFormExtended{})
|
||||||
|
fmt.Println(fields, err)
|
||||||
|
// Output: map[cover:fileupload meta_title:text] <nil>
|
||||||
|
```
|
||||||
|
|
||||||
|
In a plugin, the bus is `app.Events` on the `backpack.App` passed to Boot; `festival.New` is for tests and standalone use.
|
||||||
|
|
||||||
## API reference
|
## API reference
|
||||||
|
|
||||||
|
|||||||
@@ -3,6 +3,7 @@ package festival_test
|
|||||||
import (
|
import (
|
||||||
"context"
|
"context"
|
||||||
"fmt"
|
"fmt"
|
||||||
|
"testing"
|
||||||
|
|
||||||
"git.golem15.com/golem15/summercms/modules/festival"
|
"git.golem15.com/golem15/summercms/modules/festival"
|
||||||
)
|
)
|
||||||
@@ -90,3 +91,12 @@ func ExampleBus_UntilHandled() {
|
|||||||
// acme.blog asked for hello-world
|
// acme.blog asked for hello-world
|
||||||
// hello-world true post <nil>
|
// hello-world true post <nil>
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// TestDocsDeclarations checks the event methods the README shows.
|
||||||
|
func TestDocsDeclarations(t *testing.T) {
|
||||||
|
var _ festival.Collectable = &PostFormExtended{}
|
||||||
|
e := &PostFormExtended{fields: map[string]any{"cover": "fileupload"}}
|
||||||
|
if got := e.Collected(); len(got) != 1 || got["cover"] != "fileupload" {
|
||||||
|
t.Fatalf("Collected() = %v", got)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -38,49 +38,51 @@ Use cases:
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
```go
|
Fetching an image URL a user supplied, from the application's image host (images.example.com, say) or its subdomains only:
|
||||||
|
|
||||||
|
```go src=modules/fetchguard/example_test.go#fetch
|
||||||
policy := fetchguard.Policy{
|
policy := fetchguard.Policy{
|
||||||
Mode: fetchguard.AllowHostsMode,
|
Mode: fetchguard.AllowHostsMode,
|
||||||
AllowHosts: []string{"images.example.com"},
|
AllowHosts: []string{imageHost},
|
||||||
MaxBytes: 5 << 20,
|
MaxBytes: 5 << 20,
|
||||||
Timeout: 5 * time.Second,
|
Timeout: 5 * time.Second,
|
||||||
}
|
}
|
||||||
|
|
||||||
res, err := fetchguard.Fetch(ctx, imageURL, policy, app.Config)
|
res, err := fetchguard.Fetch(ctx, imageURL, policy, cfg)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
var fe *fetchguard.Error
|
var fe *fetchguard.Error
|
||||||
if errors.As(err, &fe) && fe.Reason == fetchguard.ReasonPrivateIP {
|
if errors.As(err, &fe) && fe.Reason == fetchguard.ReasonPrivateIP {
|
||||||
return errRejectedURL
|
return nil, errRejectedURL
|
||||||
}
|
}
|
||||||
return err
|
return nil, err
|
||||||
}
|
}
|
||||||
if res.StatusCode != http.StatusOK {
|
if res.StatusCode != http.StatusOK {
|
||||||
return fmt.Errorf("image fetch: status %d", res.StatusCode)
|
return nil, fmt.Errorf("image fetch: status %d", res.StatusCode)
|
||||||
}
|
}
|
||||||
image := res.Body
|
image := res.Body
|
||||||
```
|
```
|
||||||
|
|
||||||
Calling a service API with a reusable client:
|
Calling a service API with a reusable client:
|
||||||
|
|
||||||
```go
|
```go src=modules/fetchguard/example_test.go#client
|
||||||
vendor, err := fetchguard.NewClient(fetchguard.Policy{
|
vendor, err := fetchguard.NewClient(fetchguard.Policy{
|
||||||
Mode: fetchguard.AllowHostsMode,
|
Mode: fetchguard.AllowHostsMode,
|
||||||
AllowHosts: []string{"api.example.com"},
|
AllowHosts: []string{"api.example.com"},
|
||||||
Timeout: 10 * time.Second,
|
Timeout: 10 * time.Second,
|
||||||
}, app.Config)
|
}, cfg)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
return nil, err
|
||||||
}
|
}
|
||||||
|
|
||||||
header := http.Header{}
|
header := http.Header{}
|
||||||
header.Set("Authorization", fetchguard.Bearer(token))
|
header.Set("Authorization", fetchguard.Bearer(token))
|
||||||
res, err := vendor.PostJSON(ctx, "https://api.example.com/v1/items", header, payload)
|
res, err := vendor.PostJSON(ctx, "https://api.example.com/v1/items", header, payload)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
return nil, err
|
||||||
}
|
}
|
||||||
if res.StatusCode == http.StatusTooManyRequests {
|
if res.StatusCode == http.StatusTooManyRequests {
|
||||||
wait := res.Header.Get("Retry-After")
|
wait := res.Header.Get("Retry-After")
|
||||||
// ...
|
return nil, fmt.Errorf("vendor busy, retry after %s seconds", wait)
|
||||||
}
|
}
|
||||||
|
|
||||||
// Multipart upload: fields first, then files, each in slice order.
|
// Multipart upload: fields first, then files, each in slice order.
|
||||||
|
|||||||
@@ -6,10 +6,13 @@ import (
|
|||||||
"fmt"
|
"fmt"
|
||||||
"io"
|
"io"
|
||||||
"net/http"
|
"net/http"
|
||||||
|
"net/http/httptest"
|
||||||
"net/netip"
|
"net/netip"
|
||||||
"strings"
|
"strings"
|
||||||
|
"testing"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
|
"git.golem15.com/golem15/summercms/modules/compass"
|
||||||
"git.golem15.com/golem15/summercms/modules/fetchguard"
|
"git.golem15.com/golem15/summercms/modules/fetchguard"
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -105,3 +108,131 @@ func ExampleIsPrivateAddr() {
|
|||||||
// 10.0.0.7 true
|
// 10.0.0.7 true
|
||||||
// ::ffff:127.0.0.1 true
|
// ::ffff:127.0.0.1 true
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// errRejectedURL answers an image URL that points inside the network.
|
||||||
|
var errRejectedURL = errors.New("image URL rejected")
|
||||||
|
|
||||||
|
// fetchImage downloads an image from imageHost or one of its subdomains
|
||||||
|
// (images.example.com in production). cfg is the application's config
|
||||||
|
// (app.Config).
|
||||||
|
func fetchImage(ctx context.Context, cfg *compass.Config, imageHost, imageURL string) ([]byte, error) {
|
||||||
|
// docs:start fetch
|
||||||
|
policy := fetchguard.Policy{
|
||||||
|
Mode: fetchguard.AllowHostsMode,
|
||||||
|
AllowHosts: []string{imageHost},
|
||||||
|
MaxBytes: 5 << 20,
|
||||||
|
Timeout: 5 * time.Second,
|
||||||
|
}
|
||||||
|
|
||||||
|
res, err := fetchguard.Fetch(ctx, imageURL, policy, cfg)
|
||||||
|
if err != nil {
|
||||||
|
var fe *fetchguard.Error
|
||||||
|
if errors.As(err, &fe) && fe.Reason == fetchguard.ReasonPrivateIP {
|
||||||
|
return nil, errRejectedURL
|
||||||
|
}
|
||||||
|
return nil, err
|
||||||
|
}
|
||||||
|
if res.StatusCode != http.StatusOK {
|
||||||
|
return nil, fmt.Errorf("image fetch: status %d", res.StatusCode)
|
||||||
|
}
|
||||||
|
image := res.Body
|
||||||
|
// docs:end fetch
|
||||||
|
return image, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestDocsFetchImage runs fetchImage offline: an allowed host that resolves
|
||||||
|
// into the network is rejected at dial time, a host outside the list and a
|
||||||
|
// plain http URL never reach the network.
|
||||||
|
func TestDocsFetchImage(t *testing.T) {
|
||||||
|
site := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
t.Error("the guard let a request through to a loopback server")
|
||||||
|
}))
|
||||||
|
defer site.Close()
|
||||||
|
if _, err := fetchImage(t.Context(), nil, "127.0.0.1", site.URL+"/cover.jpg"); !errors.Is(err, errRejectedURL) {
|
||||||
|
t.Fatalf("loopback image = %v, want errRejectedURL", err)
|
||||||
|
}
|
||||||
|
for url, want := range map[string]fetchguard.Reason{
|
||||||
|
"https://cdn.attacker.example/cover.jpg": fetchguard.ReasonInvalidURL,
|
||||||
|
"http://images.example.com/cover.jpg": fetchguard.ReasonScheme,
|
||||||
|
} {
|
||||||
|
_, err := fetchImage(t.Context(), nil, "images.example.com", url)
|
||||||
|
var fe *fetchguard.Error
|
||||||
|
if !errors.As(err, &fe) || fe.Reason != want {
|
||||||
|
t.Fatalf("%s: %v, want %s", url, err, want)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// vendorFunc is a vendor API stand-in for WithTransport.
|
||||||
|
type vendorFunc func(*http.Request) (*http.Response, error)
|
||||||
|
|
||||||
|
func (f vendorFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
|
||||||
|
|
||||||
|
// syncItems sends payload to the vendor API, then uploads a report file.
|
||||||
|
func syncItems(ctx context.Context, cfg *compass.Config, token string, payload any, f io.Reader) (*fetchguard.Result, error) {
|
||||||
|
// docs:start client
|
||||||
|
vendor, err := fetchguard.NewClient(fetchguard.Policy{
|
||||||
|
Mode: fetchguard.AllowHostsMode,
|
||||||
|
AllowHosts: []string{"api.example.com"},
|
||||||
|
Timeout: 10 * time.Second,
|
||||||
|
}, cfg)
|
||||||
|
if err != nil {
|
||||||
|
return nil, err
|
||||||
|
}
|
||||||
|
|
||||||
|
header := http.Header{}
|
||||||
|
header.Set("Authorization", fetchguard.Bearer(token))
|
||||||
|
res, err := vendor.PostJSON(ctx, "https://api.example.com/v1/items", header, payload)
|
||||||
|
if err != nil {
|
||||||
|
return nil, err
|
||||||
|
}
|
||||||
|
if res.StatusCode == http.StatusTooManyRequests {
|
||||||
|
wait := res.Header.Get("Retry-After")
|
||||||
|
return nil, fmt.Errorf("vendor busy, retry after %s seconds", wait)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Multipart upload: fields first, then files, each in slice order.
|
||||||
|
res, err = vendor.PostMultipart(ctx, "https://api.example.com/v1/files", header,
|
||||||
|
[]fetchguard.FormField{{Name: "title", Value: "Report"}},
|
||||||
|
[]fetchguard.FormFile{{Field: "file", Filename: "report.pdf", ContentType: "application/pdf", Body: f}},
|
||||||
|
)
|
||||||
|
// docs:end client
|
||||||
|
return res, err
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestDocsSyncItems runs syncItems against a stub vendor: the JSON call and
|
||||||
|
// the upload carry the bearer token, and a 429 stops before the upload.
|
||||||
|
func TestDocsSyncItems(t *testing.T) {
|
||||||
|
var calls []string
|
||||||
|
busy := false
|
||||||
|
vendor := vendorFunc(func(r *http.Request) (*http.Response, error) {
|
||||||
|
body, _ := io.ReadAll(r.Body)
|
||||||
|
calls = append(calls, r.URL.Path+" "+r.Header.Get("Authorization"))
|
||||||
|
status, header := http.StatusCreated, http.Header{}
|
||||||
|
if busy {
|
||||||
|
status = http.StatusTooManyRequests
|
||||||
|
header.Set("Retry-After", "30")
|
||||||
|
}
|
||||||
|
if r.URL.Path == "/v1/files" && (!strings.HasPrefix(r.Header.Get("Content-Type"), "multipart/form-data") ||
|
||||||
|
!strings.Contains(string(body), `filename="report.pdf"`) || !strings.Contains(string(body), "Report")) {
|
||||||
|
status = http.StatusBadRequest
|
||||||
|
}
|
||||||
|
return &http.Response{StatusCode: status, Header: header, Body: io.NopCloser(strings.NewReader(`{}`)), Request: r}, nil
|
||||||
|
})
|
||||||
|
ctx := fetchguard.WithTransport(t.Context(), vendor)
|
||||||
|
|
||||||
|
res, err := syncItems(ctx, nil, "example-token", map[string]string{"name": "widget"}, strings.NewReader("%PDF-1.7"))
|
||||||
|
if err != nil || res.StatusCode != http.StatusCreated {
|
||||||
|
t.Fatalf("syncItems = %+v, %v", res, err)
|
||||||
|
}
|
||||||
|
want := []string{"/v1/items Bearer example-token", "/v1/files Bearer example-token"}
|
||||||
|
if strings.Join(calls, "|") != strings.Join(want, "|") {
|
||||||
|
t.Fatalf("calls = %q", calls)
|
||||||
|
}
|
||||||
|
|
||||||
|
calls, busy = nil, true
|
||||||
|
if _, err := syncItems(ctx, nil, "example-token", nil, strings.NewReader("")); err == nil ||
|
||||||
|
!strings.Contains(err.Error(), "retry after 30 seconds") || len(calls) != 1 {
|
||||||
|
t.Fatalf("busy vendor: %v after %q", err, calls)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user