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:
@@ -26,8 +26,10 @@ WinterCMS keeps this data in a plugin's `Plugin.php` `pluginDetails()` and in `c
|
||||
|
||||
## Usage
|
||||
|
||||
```go
|
||||
path, warnings, err := kiosk.Write(ctx, "plugins/acme/blog", kiosk.DeriveOptions{})
|
||||
Regenerating the manifest of a plugin directory (plugins/acme/blog, say) and checking it:
|
||||
|
||||
```go src=modules/kiosk/example_test.go#write
|
||||
path, warnings, err := kiosk.Write(ctx, dir, kiosk.DeriveOptions{})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -36,7 +38,7 @@ for _, w := range warnings {
|
||||
}
|
||||
fmt.Println("wrote", path)
|
||||
|
||||
if err := kiosk.Check(ctx, "plugins/acme/blog"); err != nil {
|
||||
if err := kiosk.Check(ctx, dir); err != nil {
|
||||
var stale *kiosk.StaleError
|
||||
if errors.As(err, &stale) {
|
||||
fmt.Printf("expected:\n%s", stale.Want)
|
||||
@@ -47,7 +49,7 @@ if err := kiosk.Check(ctx, "plugins/acme/blog"); err != nil {
|
||||
|
||||
Picking the newest release of a plugin that an application on framework v0.6.2 can install:
|
||||
|
||||
```go
|
||||
```go src=modules/kiosk/example_test.go#newest
|
||||
var versions kiosk.VersionsResponse
|
||||
if err := json.Unmarshal(body, &versions); err != nil {
|
||||
return err
|
||||
@@ -61,25 +63,28 @@ fmt.Println("go get", v.Module+"@"+v.Version)
|
||||
|
||||
Asking the configured registry for a plugin's releases:
|
||||
|
||||
```go
|
||||
```go src=modules/kiosk/example_test.go#client
|
||||
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
|
||||
if errors.Is(err, kiosk.ErrRegistryDisabled) {
|
||||
return nil // plugins.registry_url is empty: no registry calls
|
||||
return nil, nil // plugins.registry_url is empty: no registry calls
|
||||
}
|
||||
if err != nil {
|
||||
return err
|
||||
return nil, err
|
||||
}
|
||||
versions, err := client.Versions(ctx, "acme.blog")
|
||||
if errors.Is(err, kiosk.ErrNotFound) {
|
||||
return fmt.Errorf("acme.blog is not listed")
|
||||
return nil, fmt.Errorf("acme.blog is not listed")
|
||||
}
|
||||
```
|
||||
|
||||
A plugin repository keeps its manifest current with one test:
|
||||
|
||||
```go
|
||||
```go src=modules/kiosk/checkt_test.go#TestPluginManifest
|
||||
// TestPluginManifest is the test a plugin repository adds next to its
|
||||
// plugin.go, with "." as the directory. Here it guards the committed
|
||||
// manifest of the literal fixture.
|
||||
func TestPluginManifest(t *testing.T) {
|
||||
kiosk.CheckT(t, ".")
|
||||
kiosk.CheckT(t, "testdata/literal")
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user