feat(11.1-04): add the Database section and the core Services pages

- docs/database: models, migrations, queries and pagination, relations,
  casts and validation, attachments and transactions (lagoon.Transaction,
  lagoon.AfterCommit, nested savepoints, lagoon.OnDatabase)
- docs/services: configuration, events, routing with auth groups, rate
  limiting, authentication, the OAuth server, mail and localization
- runnable Examples for lagoon, attach, compass, surf, wire, bouncer,
  wristband, postcard, phrasebook and festival; lagoon TestDocs* regions
  run on the package's Postgres harness through DocsDB
- 15 new required pages

modules/lagoon/attach/example_test.go

@@ -0,0 +1,81 @@
+package attach_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/jpeg"
+	"os"
+
+	"git.golem15.com/golem15/summercms/modules/compass"
+	"git.golem15.com/golem15/summercms/modules/lagoon/attach"
+)
+
+// Post owns attachments. MorphName is the attachment_type value its rows
+// carry: the PHP class name, so rows copied from WinterCMS keep matching.
+type Post struct {
+	ID uint
+}
+
+func (Post) MorphName() string { return `Acme\Blog\Models\Post` }
+
+func ExampleFile_Thumb() {
+	ctx := context.Background()
+	dir, err := os.MkdirTemp("", "acme-config")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(dir)
+
+	// storage.uploads.bucket_url is a file:// URL in production; mem:// keeps
+	// the example in memory.
+	cfg, err := compass.Open(compass.Options{Dir: dir, Env: "development", Environ: []string{}})
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	_ = cfg.Set("storage.uploads.bucket_url", "mem://")
+	bucket, err := attach.OpenBucket(ctx, cfg)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer bucket.Close()
+
+	// The system_files row of a post's cover image.
+	var owner attach.Owner = Post{ID: 1}
+	f := attach.File{
+		ID:             7,
+		DiskName:       "5f1d0c2e9a7b4c3d8e6f.jpg",
+		FileName:       "cover.jpg",
+		ContentType:    "image/jpeg",
+		Field:          "cover",
+		AttachmentType: owner.MorphName(),
+		AttachmentID:   "1",
+	}
+
+	// The original is stored under its partitioned WinterCMS key.
+	var img bytes.Buffer
+	if err := jpeg.Encode(&img, image.NewRGBA(image.Rect(0, 0, 640, 480)), nil); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := bucket.WriteAll(ctx, attach.BlobKey(f.DiskName), img.Bytes(), nil); err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println(attach.BlobKey(f.DiskName))
+
+	// A thumbnail is generated on first use and reused afterwards.
+	url, err := f.Thumb(ctx, bucket, 200, 200, "crop")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println(url)
+	// Output:
+	// 5f1/d0c/2e9/5f1d0c2e9a7b4c3d8e6f.jpg
+	// /storage/uploads/5f1/d0c/2e9/thumb_7_200_200_0_0_crop.jpg
+}