docs(flare,kiosk,lagoon): compile README Go examples via src= (quick-261118-qsd)

- flare: send region run by TestDocsNotifyReply against a loopback TLS push
  service; blogSubscriptions and the publish-source region run by
  TestDocsSubscriptionSource on a Postgres container (skips under -short)
- kiosk: write, newest and client regions run by TestDocsWriteManifest (a
  copy of the literal fixture), ExampleVersionsResponse and
  TestDocsBlogReleases (httptest registry); the CheckT fence reuses
  TestPluginManifest
- lagoon: new open region run by TestDocsOpenFromApp (DocsDSN added to
  export_docs_test.go); the model, create-post, on-database, publish and
  migrations fences reuse the Database pages' targets
This commit is contained in:
Jakub Zych
2026-11-18 19:53:27 +01:00
parent d04454c57b
commit c517db564c
7 changed files with 535 additions and 63 deletions

View File

@@ -1,8 +1,19 @@
package kiosk_test
import (
"context"
"encoding/json"
"errors"
"fmt"
"log"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"testing"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/compass"
"git.golem15.com/golem15/summercms/modules/kiosk"
)
@@ -55,3 +66,143 @@ func ExampleNewestCompatible() {
// v0.7.0 v0.3.0 true
// v0.4.0 false
}
// writeManifest regenerates the plugin.yaml of the plugin in dir and checks
// that the committed file is current.
func writeManifest(ctx context.Context, dir string) error {
// docs:start write
path, warnings, err := kiosk.Write(ctx, dir, kiosk.DeriveOptions{})
if err != nil {
return err
}
for _, w := range warnings {
log.Println(w)
}
fmt.Println("wrote", path)
if err := kiosk.Check(ctx, dir); err != nil {
var stale *kiosk.StaleError
if errors.As(err, &stale) {
fmt.Printf("expected:\n%s", stale.Want)
}
return err
}
// docs:end write
return nil
}
// TestDocsWriteManifest runs writeManifest on a copy of the literal fixture
// plugin without its plugin.yaml and compares the result with the
// committed one.
func TestDocsWriteManifest(t *testing.T) {
dir := t.TempDir()
if err := os.CopyFS(dir, os.DirFS("testdata/literal")); err != nil {
t.Fatal(err)
}
if err := os.Remove(filepath.Join(dir, kiosk.FileName)); err != nil {
t.Fatal(err)
}
if err := writeManifest(t.Context(), dir); err != nil {
t.Fatal(err)
}
got, err := os.ReadFile(filepath.Join(dir, kiosk.FileName))
if err != nil {
t.Fatal(err)
}
want, err := os.ReadFile(filepath.Join("testdata", "literal", kiosk.FileName))
if err != nil {
t.Fatal(err)
}
if string(got) != string(want) {
t.Fatalf("plugin.yaml =\n%s\nwant\n%s", got, want)
}
}
// pickRelease prints the go get line of the newest release in a registry
// versions answer that an application on framework v0.6.2 can install.
func pickRelease(body []byte) error {
// docs:start newest
var versions kiosk.VersionsResponse
if err := json.Unmarshal(body, &versions); err != nil {
return err
}
v, ok := kiosk.NewestCompatible(versions.Data, "v0.6.2")
if !ok {
return errors.New("every release needs a newer framework")
}
fmt.Println("go get", v.Module+"@"+v.Version)
// docs:end newest
return nil
}
func ExampleVersionsResponse() {
// The body of GET {registry}/api/v1/plugins/acme.blog/versions.
body := []byte(`{"data":[
{"version":"v0.3.0","framework":"v0.7.0","module":"example.test/sm-blog-plugin"},
{"version":"v0.2.1","framework":"v0.6.0","module":"example.test/sm-blog-plugin"}
]}`)
if err := pickRelease(body); err != nil {
fmt.Println(err)
}
if err := pickRelease([]byte(`{"data":[{"version":"v0.3.0","framework":"v0.7.0"}]}`)); err != nil {
fmt.Println(err)
}
// Output:
// go get example.test/sm-blog-plugin@v0.2.1
// every release needs a newer framework
}
// blogReleases asks the configured registry for the releases of acme.blog.
func blogReleases(ctx context.Context, app *backpack.App) ([]kiosk.RegistryVersion, error) {
// docs:start client
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
if errors.Is(err, kiosk.ErrRegistryDisabled) {
return nil, nil // plugins.registry_url is empty: no registry calls
}
if err != nil {
return nil, err
}
versions, err := client.Versions(ctx, "acme.blog")
if errors.Is(err, kiosk.ErrNotFound) {
return nil, fmt.Errorf("acme.blog is not listed")
}
// docs:end client
return versions, err
}
// TestDocsBlogReleases runs blogReleases against a stand-in registry, with
// the registry disabled, and against a registry that does not list the
// plugin.
func TestDocsBlogReleases(t *testing.T) {
listed := true
registry := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !listed || r.URL.Path != kiosk.RegistryAPIPath+"/plugins/acme.blog/versions" {
w.WriteHeader(http.StatusNotFound)
return
}
_ = json.NewEncoder(w).Encode(kiosk.VersionsResponse{Data: []kiosk.RegistryVersion{{Version: "v0.2.1", Framework: "v0.6.0"}}})
}))
defer registry.Close()
appWith := func(url string) *backpack.App {
cfg, err := compass.Open(compass.Options{Dir: t.TempDir(), Environ: []string{}})
if err != nil {
t.Fatal(err)
}
if err := cfg.Set("plugins.registry_url", url); err != nil {
t.Fatal(err)
}
return backpack.New(cfg)
}
versions, err := blogReleases(t.Context(), appWith(registry.URL))
if err != nil || len(versions) != 1 || versions[0].Version != "v0.2.1" {
t.Fatalf("releases = %+v, %v", versions, err)
}
if versions, err := blogReleases(t.Context(), appWith("")); err != nil || versions != nil {
t.Fatalf("disabled registry = %+v, %v", versions, err)
}
listed = false
if _, err := blogReleases(t.Context(), appWith(registry.URL)); err == nil || err.Error() != "acme.blog is not listed" {
t.Fatalf("unlisted plugin = %v", err)
}
}