From b3d1a8cf0fe12e388e56cc87d254af172531e0f0 Mon Sep 17 00:00:00 2001
From: tweinmann
Date: Tue, 29 Sep 2026 13:09:42 +0000
Subject: [PATCH 1/5] feat: offer packages, tags and zones as choices in the
forms
The add form lists the deploy artifacts and tags of the registry
connection's user (GitHub API, internal/github) and the zones in the
account of the Cloudflare connection; the app page lists the tags of the
app's artifact. form.js fills the existing text fields, which remain the
fallback without JavaScript, without a connection or when a list cannot
be read. Cloudflare zones are now filtered by account and paged.
The same lists are `shelf connection packages`, `shelf connection zones`
and `shelf app tags`.
Co-Authored-By: Claude Opus 5.5
---
CLAUDE.md | 4 +
docs/plan.md | 15 +-
internal/cli/access_test.go | 2 +-
internal/cli/app.go | 2 +-
internal/cli/choices.go | 130 ++++++++++++
internal/cli/choices_test.go | 105 ++++++++++
internal/cli/connection.go | 3 +-
internal/cli/harness_test.go | 6 +
internal/cloudflare/cloudflare.go | 32 ++-
internal/cloudflare/cloudflare_test.go | 28 ++-
internal/cloudflare/dns.go | 23 ++-
internal/github/github.go | 169 ++++++++++++++++
internal/github/github_test.go | 121 +++++++++++
internal/ops/connections.go | 33 +--
internal/ops/ops.go | 2 +
internal/ops/packages.go | 148 ++++++++++++++
internal/ops/tunnel.go | 2 +-
internal/server/actions.go | 17 +-
internal/server/pages.go | 41 +++-
internal/server/render.go | 19 +-
internal/server/server.go | 8 +-
internal/server/server_test.go | 58 +++++-
internal/server/testdata/app-failed.html | 4 +-
internal/server/testdata/app-ready.html | 6 +-
internal/server/testdata/new.html | 11 +-
internal/server/ui/app.html | 6 +-
internal/server/ui/new.html | 11 +-
internal/server/ui/static/form.js | 243 +++++++++++++++++++++++
internal/server/ui/static/style.css | 4 +
29 files changed, 1174 insertions(+), 79 deletions(-)
create mode 100644 internal/cli/choices.go
create mode 100644 internal/cli/choices_test.go
create mode 100644 internal/github/github.go
create mode 100644 internal/github/github_test.go
create mode 100644 internal/ops/packages.go
create mode 100644 internal/server/ui/static/form.js
diff --git a/CLAUDE.md b/CLAUDE.md
index 86168d8..ff331ac 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,6 +52,10 @@ green; level 2 and 3 not run yet, because migrating the dev cluster takes `greet
off the shared tunnel.
Also in 8b (2026-09-29): `name` in app.yaml names the packages only; the app's name is chosen at
`shelf app add`, so one artifact can run as several apps. Level 1 green; release v0.5.0 open.
+Also in 8b (2026-09-29): the forms offer the deploy artifacts and tags of the registry connection
+(GitHub API, `internal/github`) and the zones of the Cloudflare connection as selects, with free
+text as the fallback; `shelf connection packages|zones` and `shelf app tags` list the same. Level 1
+green; `form.js` untested against real connections.
Next: Phase 9 (Mac mini: host setup, Colima, `shelf doctor`, `shelf destroy`).
## Working agreements
diff --git a/docs/plan.md b/docs/plan.md
index 179a485..8834cc7 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -179,6 +179,7 @@ connections the apps choose:
| The cluster's domain | **Stays, as the default.** `init cluster --domain` is where an app without a domain of its own answers; the host suffix stays per cluster, so the dev cluster never takes the mini's names. `--move-hosts` now only counts the apps a change actually moves: a new suffix moves all of them, a new domain those on the cluster's. |
| How it is given | **`shelf connection add registry|cloudflare `** reads `GHCR_USERNAME`/`GHCR_TOKEN` or `CF_API_TOKEN`/`CF_ACCOUNT_ID`; `shelf connection list` and `rm` go with it. `shelf app add` and `shelf app credentials` take `--registry `, `--cloudflare ` and `--domain`, and `credentials` also `--no-registry` and `--no-cloudflare`; they read no tokens at all. In the admin UI connections are defined **only on the page `/connections`**, the one page with token fields; the add form and the app page offer them as a choice. A token is never rendered, not even back into a form that was refused. |
| Phase | **A phase of its own, 8b**, before the Mac mini. Phase 8 is accepted as it was. |
+| Choices in the forms (2026-09-29) | **The forms offer what a connection can reach, as real choices.** The add form lists the deploy artifacts of the registry connection's user and their tags (newest first), and the zones in the account of the Cloudflare connection; the app page lists the tags of the app's own artifact, so going back is a choice. The packages and tags come from the **GitHub API** (`/user/packages`, the versions of a package) with the connection's token — a classic PAT with `read:packages` is enough. That is the host service talking to a forge for convenience, which the guardrail allows: the form still sends a plain `oci://…:tag`, parsed and checked as before, and when a list cannot be read, or there is no connection, the text field is shown as it always was. Only the user's own packages are listed; the images of the components (`/`) and signature tags (`sha256-…`) are left out. The domain is a select with the cluster's domain, the zones and "other…", which keeps a subdomain of a zone or a LAN-only domain possible. A small `form.js` follows a change of connection through three JSON routes under `/api/connections/`; without JavaScript the page is the one it was. The same lists are `shelf connection packages `, `shelf connection zones ` and `shelf app tags `. Packages of an organisation are not listed yet. |
Tried and reverted on 2026-09-29: **app.yaml without a name** (the short-lived Phase 8c). shelf
named an app only at `shelf app add`, so one artifact could run as several apps, and the reusable
@@ -1610,8 +1611,9 @@ Design:
the token that made them.
- **Admin UI**: the page `/connections` lists both kinds with the apps that use each and holds
the only token fields; saving and removing run as jobs like every other change, audited without
- values. The add form and the app's "Access" section offer the connections as choices, and the
- domain with the zones the Cloudflare connections see as suggestions.
+ values. The add form and the app's "Access" section offer the connections as choices; once one
+ is chosen, the add form offers its deploy artifacts, their tags and the zones of its account,
+ and the app page the tags of the app's artifact (see "Choices in the forms" above).
Steps:
@@ -1651,6 +1653,12 @@ Results so far (2026-09-29):
- The templates in the ResourceSet are strings to kubeconform, so they were rendered offline with
`text/template`, the operator's `<< >>` delimiters and `missingkey=error`, with and without a
registry connection and a tunnel.
+- The choices in the forms: `internal/github` is tested against a fake API (paging, a package
+ name with a slash, a next page on another host is not followed, errors without the token), the
+ Cloudflare zones page through `result_info` and are filtered by account, the three CLI lists run
+ against fakes, and the server tests pin the JSON routes (items, the reason as a 502, 401 without
+ a session). `form.js` itself has no automated test; it is part of the level-3 check with real
+ connections.
- Not run yet: level 2 and 3. The dev cluster still serves `greeter-dev.tobile.ch` through the
shared tunnel of Phase 5; the migration switches that off, and exposing the app again needs the
Cloudflare token. That is the maintainer's call, not a side effect of a test.
@@ -1732,6 +1740,9 @@ Due in Phase 9:
miss, unpleasant to debug remotely.
Later:
+- **Packages of an organisation** in the choices of the forms: `/user/packages` lists the
+ user's own only. An organisation's would need `/orgs//packages` and a way to know which
+ organisations to ask (`read:org`, or the owner typed once).
- **Short 504 during a rollout** (seen once in Phase 4, not reproduced in Phase 5): Traefik
answered 504 for a moment while a single-instance app was replaced. Worth a look under real
traffic on the mini.
diff --git a/internal/cli/access_test.go b/internal/cli/access_test.go
index 661e4e9..5cae83c 100644
--- a/internal/cli/access_test.go
+++ b/internal/cli/access_test.go
@@ -35,7 +35,7 @@ func tunnelKey(account, name string) string { return account + "/" + name }
func (f *fakeCloudflare) VerifyToken(context.Context) error { return f.verifyErr }
-func (f *fakeCloudflare) Zones(context.Context) ([]cloudflare.Zone, error) {
+func (f *fakeCloudflare) Zones(context.Context, string) ([]cloudflare.Zone, error) {
return []cloudflare.Zone{{ID: "zone-example.com", Name: "example.com"}, {ID: "zone-shop.ch", Name: "shop.ch"}}, nil
}
diff --git a/internal/cli/app.go b/internal/cli/app.go
index 265224a..87059e7 100644
--- a/internal/cli/app.go
+++ b/internal/cli/app.go
@@ -18,7 +18,7 @@ func newAppCmd(o Options) *cobra.Command {
}
cmd.AddCommand(
newAppAddCmd(o), newAppRmCmd(o), newAppStatusCmd(o),
- newAppRedeployCmd(o), newAppSecretsCmd(o), newAppCredentialsCmd(o),
+ newAppRedeployCmd(o), newAppSecretsCmd(o), newAppCredentialsCmd(o), newAppTagsCmd(o),
)
return cmd
}
diff --git a/internal/cli/choices.go b/internal/cli/choices.go
new file mode 100644
index 0000000..a333f5f
--- /dev/null
+++ b/internal/cli/choices.go
@@ -0,0 +1,130 @@
+package cli
+
+import (
+ "fmt"
+ "text/tabwriter"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tweinmann/shelf/internal/ops"
+)
+
+// The commands in this file list what the admin UI offers as choices: the deploy artifacts a
+// registry connection can pull, their tags, and the zones of a Cloudflare connection.
+
+const listTime = "2006-01-02 15:04"
+
+func newConnectionPackagesCmd(o Options) *cobra.Command {
+ var target clusterFlags
+ cmd := &cobra.Command{
+ Use: "packages ",
+ Short: "List the deploy artifacts a registry connection can pull",
+ Long: `List the deploy artifacts of the connection's GitHub user, read from the GitHub API with the
+connection's token. The images the workflow builds for the components are left out.`,
+ Args: cobra.ExactArgs(1),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ shelf, err := target.load(o)
+ if err != nil {
+ return err
+ }
+ pkgs, err := shelf.Packages(cmd.Context(), args[0])
+ if err != nil {
+ return err
+ }
+ out := cmd.OutOrStdout()
+ if len(pkgs) == 0 {
+ fmt.Fprintln(out, "No deploy artifacts.")
+ return nil
+ }
+ tw := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+ for _, p := range pkgs {
+ fmt.Fprintf(tw, "%s\t%s\t%s\n", p.Name, p.Artifact, stamp(p.Updated))
+ }
+ return tw.Flush()
+ },
+ }
+ target.registerTarget(cmd.Flags())
+ return cmd
+}
+
+func newConnectionZonesCmd(o Options) *cobra.Command {
+ var target clusterFlags
+ cmd := &cobra.Command{
+ Use: "zones ",
+ Short: "List the zones in the account of a Cloudflare connection",
+ Args: cobra.ExactArgs(1),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ shelf, err := target.load(o)
+ if err != nil {
+ return err
+ }
+ zones, err := shelf.Zones(cmd.Context(), args[0])
+ if err != nil {
+ return err
+ }
+ out := cmd.OutOrStdout()
+ if len(zones) == 0 {
+ fmt.Fprintln(out, "No zones.")
+ }
+ for _, z := range zones {
+ fmt.Fprintln(out, z)
+ }
+ return nil
+ },
+ }
+ target.registerTarget(cmd.Flags())
+ return cmd
+}
+
+func newAppTagsCmd(o Options) *cobra.Command {
+ var target clusterFlags
+ cmd := &cobra.Command{
+ Use: "tags ",
+ Short: "List the tags of an app's deploy artifact, newest first",
+ Long: `List the tags of the deploy artifact an app runs, newest first, read from the GitHub API with
+the app's registry connection. The tag the app is on is marked with *. Move the app to another
+one with ` + "`shelf app add :`" + `.`,
+ Args: cobra.ExactArgs(1),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ if err := ops.CheckAppName(args[0]); err != nil {
+ return err
+ }
+ shelf, err := target.load(o)
+ if err != nil {
+ return err
+ }
+ app, err := shelf.App(cmd.Context(), args[0])
+ if err != nil {
+ return err
+ }
+ tags, err := shelf.AppTags(cmd.Context(), args[0])
+ if err != nil {
+ return err
+ }
+ out := cmd.OutOrStdout()
+ if len(tags) == 0 {
+ fmt.Fprintln(out, "No tags.")
+ return nil
+ }
+ tw := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+ for _, t := range tags {
+ mark := " "
+ if t.Name == app.Artifact.Tag {
+ mark = "*"
+ }
+ fmt.Fprintf(tw, "%s %s\t%s\n", mark, t.Name, stamp(t.Created))
+ }
+ return tw.Flush()
+ },
+ }
+ target.registerTarget(cmd.Flags())
+ return cmd
+}
+
+func stamp(t time.Time) string {
+ if t.IsZero() {
+ return "-"
+ }
+ return t.UTC().Format(listTime)
+}
diff --git a/internal/cli/choices_test.go b/internal/cli/choices_test.go
new file mode 100644
index 0000000..0866e75
--- /dev/null
+++ b/internal/cli/choices_test.go
@@ -0,0 +1,105 @@
+package cli
+
+import (
+ "context"
+ "errors"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/tweinmann/shelf/internal/github"
+)
+
+// fakeGitHub answers like the GitHub packages API of the user "o".
+type fakeGitHub struct {
+ // token is the token the last client was made with.
+ token string
+ err error
+}
+
+func (f *fakeGitHub) Packages(context.Context) ([]github.Package, error) {
+ return []github.Package{
+ {Name: "shop", Owner: "O", Updated: time.Date(2026, 9, 2, 8, 0, 0, 0, time.UTC)},
+ {Name: "greeter/web", Owner: "O"},
+ {Name: "greeter", Owner: "O", Updated: time.Date(2026, 9, 1, 8, 0, 0, 0, time.UTC)},
+ }, f.err
+}
+
+func (f *fakeGitHub) Tags(_ context.Context, pkg string) ([]github.Tag, error) {
+ if pkg != "greeter" {
+ return nil, errors.New("Not Found (HTTP 404)")
+ }
+ day := func(d int) time.Time { return time.Date(2026, 9, d, 8, 0, 0, 0, time.UTC) }
+ return []github.Tag{
+ {Name: "main", Created: day(3)}, {Name: "sha-333", Created: day(3)},
+ {Name: "sha256-abc.sig", Created: day(3)}, {Name: "sha-111", Created: day(1)},
+ }, f.err
+}
+
+func TestConnectionPackages(t *testing.T) {
+ t.Parallel()
+ h := newHarness(t)
+ h.defineRegistry(t, "ghcr", "o", "ghcr-secret-token")
+
+ stdout := h.mustRun(t, "connection", "packages", "ghcr")
+ want := "greeter oci://ghcr.io/o/greeter 2026-09-01 08:00\n" +
+ "shop oci://ghcr.io/o/shop 2026-09-02 08:00\n"
+ if stdout != want {
+ t.Errorf("stdout:\n%s\nwant:\n%s", stdout, want)
+ }
+ if h.gh.token != "ghcr-secret-token" {
+ t.Errorf("the list was read with %q, not the connection's token", h.gh.token)
+ }
+
+ if _, stderr, code := h.run(t, "connection", "packages", "missing"); code == 0 ||
+ !strings.Contains(stderr, "there is no registry connection missing") {
+ t.Errorf("missing connection: exit code %d, stderr %q", code, stderr)
+ }
+ h.gh.err = errors.New("Bad credentials (HTTP 401)")
+ if _, stderr, code := h.run(t, "connection", "packages", "ghcr"); code == 0 || !strings.Contains(stderr, "Bad credentials") {
+ t.Errorf("refused token: exit code %d, stderr %q", code, stderr)
+ }
+}
+
+func TestConnectionZones(t *testing.T) {
+ t.Parallel()
+ h := cloudflareHarness(t)
+ if stdout := h.mustRun(t, "connection", "zones", "tobile"); stdout != "example.com\nshop.ch\n" {
+ t.Errorf("stdout %q", stdout)
+ }
+ if _, stderr, code := h.run(t, "connection", "zones", "other"); code == 0 ||
+ !strings.Contains(stderr, "no Cloudflare connection other") {
+ t.Errorf("missing connection: exit code %d, stderr %q", code, stderr)
+ }
+}
+
+func TestAppTags(t *testing.T) {
+ t.Parallel()
+ h := newHarness(t)
+ h.app = appWithSecrets("greeter")
+ h.defineRegistry(t, "ghcr", "o", "ghcr-secret-token")
+ h.defineRegistry(t, "other", "someone", "ghcr-secret-token")
+ h.mustRun(t, "app", "add", "greeter", greeterArtifact, "--registry", "ghcr")
+ h.mustRun(t, "app", "add", "plain", greeterArtifact)
+ h.mustRun(t, "app", "add", "foreign", greeterArtifact, "--registry", "other")
+
+ stdout := h.mustRun(t, "app", "tags", "greeter")
+ want := "* main 2026-09-03 08:00\n" +
+ " sha-333 2026-09-03 08:00\n" +
+ " sha-111 2026-09-01 08:00\n"
+ if stdout != want {
+ t.Errorf("stdout:\n%s\nwant:\n%s", stdout, want)
+ }
+
+ if _, stderr, code := h.run(t, "app", "tags", "plain"); code == 0 ||
+ !strings.Contains(stderr, "pulls without a registry connection") {
+ t.Errorf("app without a connection: exit code %d, stderr %q", code, stderr)
+ }
+ if _, stderr, code := h.run(t, "app", "tags", "foreign"); code == 0 ||
+ !strings.Contains(stderr, "belongs to o, and the connection lists the packages of someone only") {
+ t.Errorf("artifact of another user: exit code %d, stderr %q", code, stderr)
+ }
+ if _, stderr, code := h.run(t, "app", "tags", "nothing"); code == 0 || !strings.Contains(stderr, "app nothing does not exist") {
+ t.Errorf("missing app: exit code %d, stderr %q", code, stderr)
+ }
+}
diff --git a/internal/cli/connection.go b/internal/cli/connection.go
index af7730b..f8ee335 100644
--- a/internal/cli/connection.go
+++ b/internal/cli/connection.go
@@ -35,7 +35,8 @@ and never goes into the cluster, so only this machine can expose apps through it
}
add := &cobra.Command{Use: "add", Short: "Define a connection, or give one a new token"}
add.AddCommand(newConnectionAddRegistryCmd(o), newConnectionAddCloudflareCmd(o))
- cmd.AddCommand(add, newConnectionListCmd(o), newConnectionRmCmd(o))
+ cmd.AddCommand(add, newConnectionListCmd(o), newConnectionRmCmd(o),
+ newConnectionPackagesCmd(o), newConnectionZonesCmd(o))
return cmd
}
diff --git a/internal/cli/harness_test.go b/internal/cli/harness_test.go
index 81a8b4c..dcddf11 100644
--- a/internal/cli/harness_test.go
+++ b/internal/cli/harness_test.go
@@ -183,6 +183,7 @@ type harness struct {
cluster *fakeCluster
api *fakeCloudflare
+ gh *fakeGitHub
// app is what the registry serves as the deploy artifact.
app *schema.App
@@ -208,6 +209,7 @@ func newHarness(t *testing.T) *harness {
version: "v0.0.0-test",
cluster: &fakeCluster{},
api: &fakeCloudflare{accounts: []string{"acc-1"}},
+ gh: &fakeGitHub{},
}
}
@@ -234,6 +236,10 @@ func (h *harness) options() Options {
Cluster: h.cluster,
Fetch: h.fetch,
NewCloudflare: func(string) ops.CloudflareAPI { return h.api },
+ NewGitHub: func(token string) ops.GitHubAPI {
+ h.gh.token = token
+ return h.gh
+ },
}
},
}
diff --git a/internal/cloudflare/cloudflare.go b/internal/cloudflare/cloudflare.go
index 53ab003..61f1d3b 100644
--- a/internal/cloudflare/cloudflare.go
+++ b/internal/cloudflare/cloudflare.go
@@ -62,6 +62,11 @@ type response struct {
Success bool `json:"success"`
Errors []apiError `json:"errors"`
Result json.RawMessage `json:"result"`
+ // ResultInfo is set on the replies of list calls.
+ ResultInfo *struct {
+ Page int `json:"page"`
+ TotalPages int `json:"total_pages"`
+ } `json:"result_info"`
}
type apiError struct {
@@ -73,11 +78,18 @@ func (e apiError) String() string { return fmt.Sprintf("%s (code %d)", e.Message
// do sends a request and unmarshals result, or returns what Cloudflare complained about.
func (c *Client) do(ctx context.Context, method, path string, body, result any) error {
+ _, err := c.call(ctx, method, path, body, result)
+ return err
+}
+
+// call is do that also returns the number of pages a list call has, 1 when the reply does not
+// say.
+func (c *Client) call(ctx context.Context, method, path string, body, result any) (int, error) {
var payload io.Reader
if body != nil {
data, err := json.Marshal(body)
if err != nil {
- return err
+ return 0, err
}
payload = bytes.NewReader(data)
}
@@ -87,7 +99,7 @@ func (c *Client) do(ctx context.Context, method, path string, body, result any)
}
req, err := http.NewRequestWithContext(ctx, method, base+path, payload)
if err != nil {
- return err
+ return 0, err
}
req.Header.Set("Authorization", "Bearer "+c.Token)
req.Header.Set("Content-Type", "application/json")
@@ -97,16 +109,16 @@ func (c *Client) do(ctx context.Context, method, path string, body, result any)
}
resp, err := client.Do(req)
if err != nil {
- return fmt.Errorf("%s %s: %w", method, path, err)
+ return 0, fmt.Errorf("%s %s: %w", method, path, err)
}
defer resp.Body.Close()
data, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
if err != nil {
- return err
+ return 0, err
}
var env response
if err := json.Unmarshal(data, &env); err != nil {
- return fmt.Errorf("%s %s: unexpected reply (HTTP %d)", method, path, resp.StatusCode)
+ return 0, fmt.Errorf("%s %s: unexpected reply (HTTP %d)", method, path, resp.StatusCode)
}
if !env.Success {
var msgs []string
@@ -116,12 +128,16 @@ func (c *Client) do(ctx context.Context, method, path string, body, result any)
if len(msgs) == 0 {
msgs = []string{fmt.Sprintf("HTTP %d", resp.StatusCode)}
}
- return fmt.Errorf("%s %s: %s", method, path, strings.Join(msgs, "; "))
+ return 0, fmt.Errorf("%s %s: %s", method, path, strings.Join(msgs, "; "))
+ }
+ pages := 1
+ if env.ResultInfo != nil && env.ResultInfo.TotalPages > 1 {
+ pages = env.ResultInfo.TotalPages
}
if result == nil {
- return nil
+ return pages, nil
}
- return json.Unmarshal(env.Result, result)
+ return pages, json.Unmarshal(env.Result, result)
}
// VerifyToken checks that the token itself is valid, which tells a wrong kind of credential
diff --git a/internal/cloudflare/cloudflare_test.go b/internal/cloudflare/cloudflare_test.go
index bba19f3..069beca 100644
--- a/internal/cloudflare/cloudflare_test.go
+++ b/internal/cloudflare/cloudflare_test.go
@@ -298,12 +298,34 @@ func TestDeleteTunnel(t *testing.T) {
}
func TestZones(t *testing.T) {
- api := &fakeAPI{zones: []Zone{{ID: "z-1", Name: "example.com"}, {ID: "z-2", Name: "shop.ch"}}}
- c := newTestClient(t, api)
- zones, err := c.Zones(context.Background())
+ // Two pages of one zone each, so that the client has to follow the paging.
+ pages := [][]Zone{{{ID: "z-1", Name: "example.com"}}, {{ID: "z-2", Name: "shop.ch"}}}
+ var queries []string
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ queries = append(queries, r.URL.Query().Get("account.id")+" "+r.URL.Query().Get("page"))
+ page := 1
+ if r.URL.Query().Get("page") == "2" {
+ page = 2
+ }
+ data, _ := json.Marshal(pages[page-1])
+ env := response{Success: true, Result: data}
+ env.ResultInfo = &struct {
+ Page int `json:"page"`
+ TotalPages int `json:"total_pages"`
+ }{page, len(pages)}
+ if err := json.NewEncoder(w).Encode(env); err != nil {
+ t.Error(err)
+ }
+ }))
+ defer srv.Close()
+ c := &Client{Token: "test-token", BaseURL: srv.URL, HTTP: srv.Client()}
+ zones, err := c.Zones(context.Background(), "acc-1")
if err != nil || len(zones) != 2 || zones[1].Name != "shop.ch" {
t.Fatalf("zones %+v, %v", zones, err)
}
+ if want := []string{"acc-1 1", "acc-1 2"}; !slices.Equal(queries, want) {
+ t.Errorf("queries %v, want %v", queries, want)
+ }
}
func TestZoneFor(t *testing.T) {
diff --git a/internal/cloudflare/dns.go b/internal/cloudflare/dns.go
index 275f758..b9cdc48 100644
--- a/internal/cloudflare/dns.go
+++ b/internal/cloudflare/dns.go
@@ -5,6 +5,7 @@ import (
"fmt"
"net/http"
"net/url"
+ "strconv"
"strings"
)
@@ -35,13 +36,25 @@ const (
Unchanged Action = "unchanged"
)
-// Zones returns the zones the token can see, for offering them as the domain of an app.
-func (c *Client) Zones(ctx context.Context) ([]Zone, error) {
+// Zones returns the zones of an account the token can see, for offering them as the domain of
+// an app. An empty account means every account the token reaches.
+func (c *Client) Zones(ctx context.Context, account string) ([]Zone, error) {
var zones []Zone
- if err := c.do(ctx, http.MethodGet, "/zones?per_page=50", nil, &zones); err != nil {
- return nil, err
+ for page := 1; ; page++ {
+ query := url.Values{"per_page": {"50"}, "page": {strconv.Itoa(page)}}
+ if account != "" {
+ query.Set("account.id", account)
+ }
+ var batch []Zone
+ pages, err := c.call(ctx, http.MethodGet, "/zones?"+query.Encode(), nil, &batch)
+ if err != nil {
+ return nil, err
+ }
+ zones = append(zones, batch...)
+ if page >= pages || len(batch) == 0 {
+ return zones, nil
+ }
}
- return zones, nil
}
// ZoneFor returns the zone that holds name: the zone of the name itself, or of one of its parent
diff --git a/internal/github/github.go b/internal/github/github.go
new file mode 100644
index 0000000..e6ed4c2
--- /dev/null
+++ b/internal/github/github.go
@@ -0,0 +1,169 @@
+// Package github reads the container packages of a GitHub user and their tags, so that the admin
+// UI can offer them as a choice. It is a convenience of the host service: nothing that deploys an
+// app depends on it, the registry stays the only interface between build and platform.
+package github
+
+import (
+ "cmp"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "regexp"
+ "slices"
+ "strings"
+ "time"
+)
+
+// DefaultBaseURL is the GitHub REST API.
+const DefaultBaseURL = "https://api.github.com"
+
+// maxPages bounds how far a list follows the paging. A package that is pushed on every commit
+// collects versions without end; the newest few hundred are what anyone picks from.
+const maxPages = 5
+
+// Client calls the GitHub API with a token. A classic personal access token with read:packages,
+// the one a registry connection holds for pulling from GHCR, is enough.
+type Client struct {
+ Token string
+ BaseURL string
+ HTTP *http.Client
+}
+
+// New returns a client for the given token.
+func New(token string) *Client {
+ return &Client{
+ Token: strings.TrimSpace(token),
+ BaseURL: DefaultBaseURL,
+ HTTP: &http.Client{Timeout: 30 * time.Second},
+ }
+}
+
+// Package is a container package.
+type Package struct {
+ Name string `json:"name"`
+ Owner string `json:"owner"`
+ Updated time.Time `json:"updated"`
+}
+
+// Tag is a tag of a package version.
+type Tag struct {
+ Name string `json:"name"`
+ Created time.Time `json:"created"`
+}
+
+// Packages returns the container packages of the token's user.
+func (c *Client) Packages(ctx context.Context) ([]Package, error) {
+ var raw []struct {
+ Name string `json:"name"`
+ Owner struct {
+ Login string `json:"login"`
+ } `json:"owner"`
+ UpdatedAt time.Time `json:"updated_at"`
+ }
+ if err := c.list(ctx, "/user/packages?package_type=container&per_page=100", &raw); err != nil {
+ return nil, err
+ }
+ out := make([]Package, 0, len(raw))
+ for _, p := range raw {
+ out = append(out, Package{Name: p.Name, Owner: p.Owner.Login, Updated: p.UpdatedAt})
+ }
+ return out, nil
+}
+
+// Tags returns the tags of a container package of the token's user, newest first. A version
+// without a tag is left out; a version with several tags gives one entry for each.
+func (c *Client) Tags(ctx context.Context, pkg string) ([]Tag, error) {
+ var raw []struct {
+ CreatedAt time.Time `json:"created_at"`
+ Metadata struct {
+ Container struct {
+ Tags []string `json:"tags"`
+ } `json:"container"`
+ } `json:"metadata"`
+ }
+ path := "/user/packages/container/" + url.PathEscape(pkg) + "/versions?per_page=100"
+ if err := c.list(ctx, path, &raw); err != nil {
+ return nil, err
+ }
+ var out []Tag
+ for _, v := range raw {
+ for _, t := range v.Metadata.Container.Tags {
+ out = append(out, Tag{Name: t, Created: v.CreatedAt})
+ }
+ }
+ slices.SortStableFunc(out, func(a, b Tag) int { return b.Created.Compare(a.Created) })
+ return out, nil
+}
+
+// next finds the URL of the next page in a Link header.
+var next = regexp.MustCompile(`<([^>]+)>;\s*rel="next"`)
+
+// list gets every page of a list, up to maxPages, and appends the items to result, which points
+// at a slice.
+func (c *Client) list(ctx context.Context, path string, result any) error {
+ base := cmp.Or(c.BaseURL, DefaultBaseURL)
+ target := base + path
+ var all []json.RawMessage
+ for range maxPages {
+ var page []json.RawMessage
+ link, err := c.get(ctx, target, &page)
+ if err != nil {
+ return err
+ }
+ all = append(all, page...)
+ m := next.FindStringSubmatch(link)
+ // The token goes only to the API it was sent to: a next page elsewhere is not followed.
+ if m == nil || !strings.HasPrefix(m[1], base+"/") {
+ break
+ }
+ target = m[1]
+ }
+ data, err := json.Marshal(all)
+ if err != nil {
+ return err
+ }
+ return json.Unmarshal(data, result)
+}
+
+// get sends a GET request, unmarshals the reply into result and returns its Link header, or
+// returns what GitHub complained about.
+func (c *Client) get(ctx context.Context, target string, result any) (string, error) {
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
+ if err != nil {
+ return "", err
+ }
+ req.Header.Set("Authorization", "Bearer "+c.Token)
+ req.Header.Set("Accept", "application/vnd.github+json")
+ req.Header.Set("X-GitHub-Api-Version", "2022-11-28")
+ client := c.HTTP
+ if client == nil {
+ client = http.DefaultClient
+ }
+ shown := req.URL.Path
+ resp, err := client.Do(req)
+ if err != nil {
+ return "", fmt.Errorf("GET %s: %w", shown, err)
+ }
+ defer resp.Body.Close()
+ data, err := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+ if err != nil {
+ return "", err
+ }
+ if resp.StatusCode != http.StatusOK {
+ var reply struct {
+ Message string `json:"message"`
+ }
+ msg := fmt.Sprintf("HTTP %d", resp.StatusCode)
+ if json.Unmarshal(data, &reply) == nil && reply.Message != "" {
+ msg = fmt.Sprintf("%s (HTTP %d)", reply.Message, resp.StatusCode)
+ }
+ return "", fmt.Errorf("GET %s: %s", shown, msg)
+ }
+ if err := json.Unmarshal(data, result); err != nil {
+ return "", fmt.Errorf("GET %s: unexpected reply", shown)
+ }
+ return resp.Header.Get("Link"), nil
+}
diff --git a/internal/github/github_test.go b/internal/github/github_test.go
new file mode 100644
index 0000000..5327967
--- /dev/null
+++ b/internal/github/github_test.go
@@ -0,0 +1,121 @@
+package github
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "slices"
+ "strings"
+ "testing"
+)
+
+// fakeAPI answers like the GitHub packages API, with the replies given by the raw path.
+type fakeAPI struct {
+ t *testing.T
+ replies map[string]string
+ // links is the Link header a path answers with.
+ links map[string]string
+ requests []string
+}
+
+func (f *fakeAPI) server() *httptest.Server {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ path := r.URL.EscapedPath() + "?" + r.URL.RawQuery
+ f.requests = append(f.requests, path)
+ if got := r.Header.Get("Authorization"); got != "Bearer test-token" {
+ w.WriteHeader(http.StatusUnauthorized)
+ fmt.Fprint(w, `{"message":"Bad credentials"}`)
+ return
+ }
+ reply, ok := f.replies[path]
+ if !ok {
+ w.WriteHeader(http.StatusNotFound)
+ fmt.Fprint(w, `{"message":"Not Found"}`)
+ return
+ }
+ if link, ok := f.links[path]; ok {
+ w.Header().Set("Link", strings.ReplaceAll(link, "BASE", "http://"+r.Host))
+ }
+ fmt.Fprint(w, reply)
+ }))
+ f.t.Cleanup(srv.Close)
+ return srv
+}
+
+func newTestClient(t *testing.T, api *fakeAPI, token string) *Client {
+ t.Helper()
+ api.t = t
+ srv := api.server()
+ return &Client{Token: token, BaseURL: srv.URL, HTTP: srv.Client()}
+}
+
+func TestPackagesFollowsPaging(t *testing.T) {
+ const first = "/user/packages?package_type=container&per_page=100"
+ api := &fakeAPI{
+ replies: map[string]string{
+ first: `[{"name":"greeter","owner":{"login":"alice"},"updated_at":"2026-09-01T10:00:00Z"}]`,
+ "/user/packages?package_type=container&per_page=100&page=2": `[{"name":"greeter/web","owner":{"login":"alice"}}]`,
+ },
+ links: map[string]string{
+ first: `; rel="next", ; rel="last"`,
+ },
+ }
+ c := newTestClient(t, api, "test-token")
+ got, err := c.Packages(context.Background())
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(got) != 2 || got[0].Name != "greeter" || got[0].Owner != "alice" || got[0].Updated.IsZero() ||
+ got[1].Name != "greeter/web" {
+ t.Errorf("packages %+v", got)
+ }
+}
+
+func TestPagingStaysOnTheAPI(t *testing.T) {
+ const first = "/user/packages?package_type=container&per_page=100"
+ api := &fakeAPI{
+ replies: map[string]string{first: `[]`},
+ links: map[string]string{first: `; rel="next"`},
+ }
+ c := newTestClient(t, api, "test-token")
+ if _, err := c.Packages(context.Background()); err != nil {
+ t.Fatal(err)
+ }
+ if len(api.requests) != 1 {
+ t.Errorf("requests %v: the token must not follow a link to another host", api.requests)
+ }
+}
+
+func TestTagsNewestFirst(t *testing.T) {
+ api := &fakeAPI{replies: map[string]string{
+ "/user/packages/container/greeter%2Fweb/versions?per_page=100": `[
+ {"created_at":"2026-09-01T10:00:00Z","metadata":{"container":{"tags":["sha-111"]}}},
+ {"created_at":"2026-09-03T10:00:00Z","metadata":{"container":{"tags":["main","sha-333"]}}},
+ {"created_at":"2026-09-02T10:00:00Z","metadata":{"container":{"tags":[]}}}
+ ]`,
+ }}
+ c := newTestClient(t, api, "test-token")
+ got, err := c.Tags(context.Background(), "greeter/web")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var names []string
+ for _, tag := range got {
+ names = append(names, tag.Name)
+ }
+ if want := []string{"main", "sha-333", "sha-111"}; !slices.Equal(names, want) {
+ t.Errorf("tags %v, want %v", names, want)
+ }
+}
+
+func TestErrorsNameWhatGitHubSaid(t *testing.T) {
+ c := newTestClient(t, &fakeAPI{}, "not-a-real-token")
+ _, err := c.Packages(context.Background())
+ if err == nil || !strings.Contains(err.Error(), "Bad credentials (HTTP 401)") {
+ t.Fatalf("error %v", err)
+ }
+ if strings.Contains(err.Error(), "not-a-real-token") {
+ t.Errorf("the error shows the token: %v", err)
+ }
+}
diff --git a/internal/ops/connections.go b/internal/ops/connections.go
index 441cd3d..0e53d8d 100644
--- a/internal/ops/connections.go
+++ b/internal/ops/connections.go
@@ -230,23 +230,24 @@ func pronoun(n int) string {
return "them"
}
-// Zones returns the zones the Cloudflare connections of this machine can see, for offering them
-// as the domain of an app. A connection whose token is refused is left out rather than failing
-// the list: it is a suggestion, and the add itself checks the domain.
-func (o *Ops) Zones(ctx context.Context) []string {
- conns, err := o.Env.Connections.CloudflareConnections()
+// Zones returns the zones in the account of a Cloudflare connection, for offering them as the
+// domain of an app.
+func (o *Ops) Zones(ctx context.Context, name string) ([]string, error) {
+ conn, err := o.Env.Connections.Cloudflare(name)
if err != nil {
- return nil
+ return nil, err
}
- seen := map[string]bool{}
- for _, c := range conns {
- zones, err := o.NewCloudflare(c.Token).Zones(ctx)
- if err != nil {
- continue
- }
- for _, z := range zones {
- seen[z.Name] = true
- }
+ if conn == nil {
+ return nil, missingCloudflare(name)
+ }
+ zones, err := o.NewCloudflare(conn.Token).Zones(ctx, conn.Account)
+ if err != nil {
+ return nil, err
+ }
+ names := make([]string, 0, len(zones))
+ for _, z := range zones {
+ names = append(names, z.Name)
}
- return slices.Sorted(maps.Keys(seen))
+ slices.Sort(names)
+ return slices.Compact(names), nil
}
diff --git a/internal/ops/ops.go b/internal/ops/ops.go
index 9e87ecf..57077ac 100644
--- a/internal/ops/ops.go
+++ b/internal/ops/ops.go
@@ -177,6 +177,7 @@ type Ops struct {
Cluster Cluster
Fetch FetchFunc
NewCloudflare func(token string) CloudflareAPI
+ NewGitHub func(token string) GitHubAPI
}
// New returns the operations against a cluster, talking to the real world.
@@ -187,6 +188,7 @@ func New(t Target, env Env) *Ops {
Cluster: liveCluster{},
Fetch: deploy.Fetch,
NewCloudflare: liveCloudflare,
+ NewGitHub: liveGitHub,
}
}
diff --git a/internal/ops/packages.go b/internal/ops/packages.go
new file mode 100644
index 0000000..8a9525b
--- /dev/null
+++ b/internal/ops/packages.go
@@ -0,0 +1,148 @@
+package ops
+
+import (
+ "cmp"
+ "context"
+ "fmt"
+ "slices"
+ "strings"
+ "time"
+
+ "github.com/tweinmann/shelf/internal/cluster"
+ "github.com/tweinmann/shelf/internal/github"
+)
+
+// GitHubAPI is the part of the GitHub API shelf uses: listing what a registry connection could
+// pull, so that a form can offer it. Nothing that deploys an app calls it.
+type GitHubAPI interface {
+ Packages(ctx context.Context) ([]github.Package, error)
+ Tags(ctx context.Context, pkg string) ([]github.Tag, error)
+}
+
+func liveGitHub(token string) GitHubAPI { return github.New(token) }
+
+// Package is a deploy artifact a registry connection can pull, without a tag.
+type Package struct {
+ Name string `json:"name"`
+ // Artifact is oci://ghcr.io//; a tag makes it what `shelf app add` takes.
+ Artifact string `json:"artifact"`
+ Updated time.Time `json:"updated"`
+}
+
+// Tag is a tag of a deploy artifact.
+type Tag struct {
+ Name string `json:"name"`
+ Created time.Time `json:"created"`
+}
+
+// registryLogin reads the login of a registry connection.
+func (o *Ops) registryLogin(ctx context.Context, registry string) (*cluster.RegistryAuth, error) {
+ if registry == "" {
+ return nil, fmt.Errorf("without a registry connection, shelf cannot list packages; enter the artifact instead")
+ }
+ login, err := o.Cluster.RegistryConnection(ctx, o.config(), registry)
+ if err != nil {
+ return nil, err
+ }
+ if login == nil {
+ return nil, missingRegistry(registry)
+ }
+ return login, nil
+}
+
+// Packages returns the deploy artifacts of the user of a registry connection, by name. The
+// images the workflow builds, /, are left out: an app is added from its deploy
+// artifact.
+func (o *Ops) Packages(ctx context.Context, registry string) ([]Package, error) {
+ login, err := o.registryLogin(ctx, registry)
+ if err != nil {
+ return nil, err
+ }
+ pkgs, err := o.NewGitHub(login.Token).Packages(ctx)
+ if err != nil {
+ return nil, err
+ }
+ out := []Package{}
+ for _, p := range pkgs {
+ if strings.Contains(p.Name, "/") {
+ continue
+ }
+ owner := strings.ToLower(cmp.Or(p.Owner, login.Username))
+ out = append(out, Package{
+ Name: p.Name,
+ Artifact: "oci://" + cluster.RegistryHost + "/" + owner + "/" + p.Name,
+ Updated: p.Updated,
+ })
+ }
+ slices.SortFunc(out, func(a, b Package) int { return strings.Compare(a.Name, b.Name) })
+ return out, nil
+}
+
+// Tags returns the tags of a deploy artifact, newest first. artifact is oci://ghcr.io//,
+// with or without a tag; it has to belong to the user of the registry connection, since that is
+// whose packages the connection can list.
+func (o *Ops) Tags(ctx context.Context, registry, artifact string) ([]Tag, error) {
+ login, err := o.registryLogin(ctx, registry)
+ if err != nil {
+ return nil, err
+ }
+ pkg, err := ownPackage(artifact, login.Username)
+ if err != nil {
+ return nil, err
+ }
+ tags, err := o.NewGitHub(login.Token).Tags(ctx, pkg)
+ if err != nil {
+ return nil, err
+ }
+ out := []Tag{}
+ seen := map[string]bool{}
+ for _, t := range tags {
+ // A signature or attestation is stored as a tag too, but nobody deploys one.
+ if seen[t.Name] || strings.HasPrefix(t.Name, "sha256-") {
+ continue
+ }
+ seen[t.Name] = true
+ out = append(out, Tag{Name: t.Name, Created: t.Created})
+ }
+ return out, nil
+}
+
+// AppTags returns the tags of the deploy artifact an app runs, newest first, read with the app's
+// registry connection.
+func (o *Ops) AppTags(ctx context.Context, name string) ([]Tag, error) {
+ apps, err := o.Apps(ctx)
+ if err != nil {
+ return nil, err
+ }
+ for _, a := range apps {
+ if a.Name != name {
+ continue
+ }
+ if a.Registry == "" {
+ return nil, fmt.Errorf("%s pulls without a registry connection, so shelf cannot list its tags", name)
+ }
+ return o.Tags(ctx, a.Registry, a.Artifact.URL)
+ }
+ return nil, fmt.Errorf("app %s does not exist", name)
+}
+
+// ownPackage returns the name of a package oci://ghcr.io//[:tag] and checks that
+// owner is user.
+func ownPackage(artifact, user string) (string, error) {
+ rest, ok := strings.CutPrefix(artifact, "oci://")
+ if !ok {
+ return "", fmt.Errorf("%q must start with oci://", artifact)
+ }
+ host, path, _ := strings.Cut(rest, "/")
+ if i := strings.LastIndex(path, ":"); i >= 0 {
+ path = path[:i]
+ }
+ owner, pkg, _ := strings.Cut(path, "/")
+ if host != cluster.RegistryHost || owner == "" || pkg == "" {
+ return "", fmt.Errorf("%s is not a package on %s; shelf lists tags there only", artifact, cluster.RegistryHost)
+ }
+ if !strings.EqualFold(owner, user) {
+ return "", fmt.Errorf("%s belongs to %s, and the connection lists the packages of %s only", artifact, owner, user)
+ }
+ return pkg, nil
+}
diff --git a/internal/ops/tunnel.go b/internal/ops/tunnel.go
index bd54211..15a6bbc 100644
--- a/internal/ops/tunnel.go
+++ b/internal/ops/tunnel.go
@@ -15,7 +15,7 @@ import (
// CloudflareAPI is the part of the Cloudflare API shelf uses.
type CloudflareAPI interface {
VerifyToken(ctx context.Context) error
- Zones(ctx context.Context) ([]cloudflare.Zone, error)
+ Zones(ctx context.Context, account string) ([]cloudflare.Zone, error)
ZoneFor(ctx context.Context, name string) (*cloudflare.Zone, error)
EnsureRecord(ctx context.Context, zone, name, target string) (cloudflare.Action, error)
DeleteRecord(ctx context.Context, zone, name string) (bool, error)
diff --git a/internal/server/actions.go b/internal/server/actions.go
index 3b0561d..6a5a095 100644
--- a/internal/server/actions.go
+++ b/internal/server/actions.go
@@ -47,12 +47,10 @@ func (s *Server) newAppForm(w http.ResponseWriter, r *http.Request) {
ctx, cancel := withTimeout(r)
defer cancel()
status := s.platform.Status(ctx)
- conns, zones := s.choices(ctx)
s.render(w, "new.html", http.StatusOK, newAppView{
base: s.base(r, "Add an app"),
Status: status,
- Connections: conns,
- Zones: zones,
+ Connections: s.connections(ctx),
Insecure: status.Settings.InsecureRegistry,
})
}
@@ -111,19 +109,20 @@ func (s *Server) failedForm(w http.ResponseWriter, r *http.Request, form newAppV
defer cancel()
form.base = s.base(r, "Add an app")
form.Status = s.platform.Status(ctx)
- form.Connections, form.Zones = s.choices(ctx)
+ form.Connections = s.connections(ctx)
form.Error = err.Error()
s.render(w, "new.html", http.StatusBadRequest, form)
}
-// choices are the connections and zones a form offers. A cluster that cannot list them leaves
-// the lists empty; the operation itself says what is wrong.
-func (s *Server) choices(ctx context.Context) (ops.Connections, []string) {
+// connections are what a form offers to choose from. A cluster that cannot list them leaves
+// the lists empty; the operation itself says what is wrong. What each connection offers in turn
+// — packages, tags, zones — the page fetches from the api routes below once one is chosen.
+func (s *Server) connections(ctx context.Context) ops.Connections {
conns, err := s.platform.Connections(ctx)
if err != nil {
- return ops.Connections{}, nil
+ return ops.Connections{}
}
- return conns, s.platform.Zones(ctx)
+ return conns
}
// setAccess changes an app's domain and connections, and deploys it again from the artifact it
diff --git a/internal/server/pages.go b/internal/server/pages.go
index e421c0a..8bc17aa 100644
--- a/internal/server/pages.go
+++ b/internal/server/pages.go
@@ -86,7 +86,7 @@ func (s *Server) showApp(w http.ResponseWriter, r *http.Request, name string,
return
}
view.SecretNames = slices.Sorted(maps.Keys(stored))
- view.Connections, view.Zones = s.choices(ctx)
+ view.Connections = s.connections(ctx)
status := http.StatusOK
if secretError != "" {
status = http.StatusUnauthorized
@@ -117,6 +117,45 @@ func (s *Server) apiStatus(w http.ResponseWriter, r *http.Request) {
_ = enc.Encode(body)
}
+// apiPackages, apiTags and apiZones fill the choices of a form once a connection is chosen. A
+// list that cannot be read answers with the reason, and the form falls back to a text field.
+// They exist for the pages of the admin UI and are not a stable interface.
+func (s *Server) apiPackages(w http.ResponseWriter, r *http.Request) {
+ ctx, cancel := withTimeout(r)
+ defer cancel()
+ pkgs, err := s.platform.Packages(ctx, r.PathValue("name"))
+ writeChoices(w, pkgs, err)
+}
+
+func (s *Server) apiTags(w http.ResponseWriter, r *http.Request) {
+ ctx, cancel := withTimeout(r)
+ defer cancel()
+ tags, err := s.platform.Tags(ctx, r.PathValue("name"), r.URL.Query().Get("artifact"))
+ writeChoices(w, tags, err)
+}
+
+func (s *Server) apiZones(w http.ResponseWriter, r *http.Request) {
+ ctx, cancel := withTimeout(r)
+ defer cancel()
+ zones, err := s.platform.Zones(ctx, r.PathValue("name"))
+ writeChoices(w, zones, err)
+}
+
+func writeChoices[T any](w http.ResponseWriter, items []T, err error) {
+ body := struct {
+ Items []T `json:"items"`
+ Error string `json:"error,omitempty"`
+ }{Items: items}
+ w.Header().Set("Content-Type", "application/json; charset=utf-8")
+ if err != nil {
+ body.Items, body.Error = []T{}, err.Error()
+ w.WriteHeader(http.StatusBadGateway)
+ } else if body.Items == nil {
+ body.Items = []T{}
+ }
+ _ = json.NewEncoder(w).Encode(body)
+}
+
// setupForm is the page a fresh instance shows, and the only one it shows.
func (s *Server) setupForm(w http.ResponseWriter, r *http.Request) {
if s.admin.claimed() {
diff --git a/internal/server/render.go b/internal/server/render.go
index 01df410..1200e9b 100644
--- a/internal/server/render.go
+++ b/internal/server/render.go
@@ -166,9 +166,8 @@ type appView struct {
Secrets map[string]string
// SecretError is why the values are not shown.
SecretError string
- // Connections and Zones are what the access form offers.
+ // Connections are what the access form offers.
Connections ops.Connections
- Zones []string
Running *Job
}
@@ -178,15 +177,13 @@ type newAppView struct {
base
Status ops.Status
Connections ops.Connections
- // Zones are the domains the Cloudflare connections can serve, as suggestions.
- Zones []string
- Name string
- Artifact string
- Insecure bool
- Domain string
- Registry string
- Cloudflare string
- Error string
+ Name string
+ Artifact string
+ Insecure bool
+ Domain string
+ Registry string
+ Cloudflare string
+ Error string
}
// jobView is the page that watches one change.
diff --git a/internal/server/server.go b/internal/server/server.go
index 2cd90ac..8a02c42 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -38,7 +38,10 @@ type Platform interface {
Diagnose(ctx context.Context, name string) (cluster.Diagnosis, error)
Secrets(ctx context.Context, name string) (map[string]string, error)
Connections(ctx context.Context) (ops.Connections, error)
- Zones(ctx context.Context) []string
+ // Packages, Tags and Zones are what a connection offers to choose from in a form.
+ Packages(ctx context.Context, registry string) ([]ops.Package, error)
+ Tags(ctx context.Context, registry, artifact string) ([]ops.Tag, error)
+ Zones(ctx context.Context, cloudflare string) ([]string, error)
AddApp(ctx context.Context, o ops.AddOptions, rep progress.Reporter) error
SetAccess(ctx context.Context, name string, access ops.Access, timeout time.Duration, rep progress.Reporter) error
@@ -152,6 +155,9 @@ func (s *Server) Handler() http.Handler {
mux.Handle("GET /jobs/{id}", s.guard(http.HandlerFunc(s.jobPage)))
mux.Handle("GET /api/jobs/{id}/events", s.guard(http.HandlerFunc(s.jobEvents)))
mux.Handle("GET /api/status", s.guard(http.HandlerFunc(s.apiStatus)))
+ mux.Handle("GET /api/connections/registry/{name}/packages", s.guard(http.HandlerFunc(s.apiPackages)))
+ mux.Handle("GET /api/connections/registry/{name}/tags", s.guard(http.HandlerFunc(s.apiTags)))
+ mux.Handle("GET /api/connections/cloudflare/{name}/zones", s.guard(http.HandlerFunc(s.apiZones)))
// Cross-origin protection refuses a state-changing request that a different site sent, by
// looking at Sec-Fetch-Site and Origin. It is the outermost layer, so it also covers a
diff --git a/internal/server/server_test.go b/internal/server/server_test.go
index 52684d6..0c7fd29 100644
--- a/internal/server/server_test.go
+++ b/internal/server/server_test.go
@@ -53,7 +53,28 @@ func (f *fakePlatform) Connections(context.Context) (ops.Connections, error) {
return f.connections, nil
}
-func (f *fakePlatform) Zones(context.Context) []string { return []string{"example.com", "shop.ch"} }
+// Zones, Packages and Tags answer for the connections "cf" and "ghcr"; any other name is one
+// whose list cannot be read.
+func (f *fakePlatform) Zones(_ context.Context, name string) ([]string, error) {
+ if name != "cf" {
+ return nil, errors.New("this machine holds no Cloudflare connection " + name)
+ }
+ return []string{"example.com", "shop.ch"}, nil
+}
+
+func (f *fakePlatform) Packages(_ context.Context, name string) ([]ops.Package, error) {
+ if name != "ghcr" {
+ return nil, errors.New("Bad credentials (HTTP 401)")
+ }
+ return []ops.Package{{Name: "greeter", Artifact: "oci://ghcr.io/owner/greeter", Updated: now}}, nil
+}
+
+func (f *fakePlatform) Tags(_ context.Context, name, artifact string) ([]ops.Tag, error) {
+ if name != "ghcr" || artifact != "oci://ghcr.io/owner/greeter" {
+ return nil, errors.New("no tags for " + artifact)
+ }
+ return []ops.Tag{{Name: "main", Created: now}, {Name: "sha-905acce", Created: now.Add(-time.Hour)}}, nil
+}
func (f *fakePlatform) SaveRegistryConnection(_ context.Context, name string, auth cluster.RegistryAuth,
rep progress.Reporter) error {
@@ -724,6 +745,41 @@ func TestAPIStatus(t *testing.T) {
}
}
+// TestChoicesAPI checks the lists a form fetches once a connection is chosen: the items, or the
+// reason they cannot be read, and never without a session.
+func TestChoicesAPI(t *testing.T) {
+ t.Parallel()
+ h, cookie := claimed(t, runningPlatform())
+ tests := []struct {
+ path string
+ code int
+ want string
+ }{
+ {"/api/connections/registry/ghcr/packages", http.StatusOK,
+ `{"items":[{"name":"greeter","artifact":"oci://ghcr.io/owner/greeter","updated":"2026-09-20T12:00:00Z"}]}`},
+ {"/api/connections/registry/other/packages", http.StatusBadGateway,
+ `{"items":[],"error":"Bad credentials (HTTP 401)"}`},
+ {"/api/connections/registry/ghcr/tags?artifact=" + url.QueryEscape("oci://ghcr.io/owner/greeter"), http.StatusOK,
+ `{"items":[{"name":"main","created":"2026-09-20T12:00:00Z"},{"name":"sha-905acce","created":"2026-09-20T11:00:00Z"}]}`},
+ {"/api/connections/registry/ghcr/tags", http.StatusBadGateway, `{"items":[],"error":"no tags for "}`},
+ {"/api/connections/cloudflare/cf/zones", http.StatusOK, `{"items":["example.com","shop.ch"]}`},
+ {"/api/connections/cloudflare/gone/zones", http.StatusBadGateway,
+ `{"items":[],"error":"this machine holds no Cloudflare connection gone"}`},
+ }
+ for _, tt := range tests {
+ rec := get(h, tt.path, cookie)
+ if rec.Code != tt.code || strings.TrimSpace(rec.Body.String()) != tt.want {
+ t.Errorf("%s: %d %s\nwant %d %s", tt.path, rec.Code, rec.Body, tt.code, tt.want)
+ }
+ if got := rec.Header().Get("Content-Type"); !strings.HasPrefix(got, "application/json") {
+ t.Errorf("%s: content type %q", tt.path, got)
+ }
+ if rec := get(h, tt.path, nil); rec.Code != http.StatusUnauthorized {
+ t.Errorf("%s without a session: %d", tt.path, rec.Code)
+ }
+ }
+}
+
// TestCrossOriginPost checks that a form on another site cannot act as the logged-in user.
func TestCrossOriginPost(t *testing.T) {
t.Parallel()
diff --git a/internal/server/testdata/app-failed.html b/internal/server/testdata/app-failed.html
index 0a0fee7..9929442 100644
--- a/internal/server/testdata/app-failed.html
+++ b/internal/server/testdata/app-failed.html
@@ -111,8 +111,7 @@
+here. With a registry connection, the form offers the deploy artifacts and tags of its user.
+With a Cloudflare connection, the app gets a tunnel of its own in that account and a DNS record
+in its zone.
+
{{end}}
diff --git a/internal/server/ui/static/form.js b/internal/server/ui/static/form.js
new file mode 100644
index 0000000..a0dd5b1
--- /dev/null
+++ b/internal/server/ui/static/form.js
@@ -0,0 +1,243 @@
+// Turns the artifact and domain fields of a form into choices: the deploy artifacts and tags the
+// chosen registry connection can pull, and the zones of the chosen Cloudflare connection. The
+// text field stays what the form sends; a choice only fills it in. Without JavaScript, without a
+// connection, or when a list cannot be read, the text field is simply shown, as it always was.
+(function () {
+ const OTHER = "\u0000other";
+
+ function option(value, text) {
+ const o = document.createElement("option");
+ o.value = value;
+ o.textContent = text;
+ return o;
+ }
+
+ function fill(select, options, wanted) {
+ select.replaceChildren(...options);
+ select.value = wanted;
+ if (select.value !== wanted) select.selectedIndex = 0;
+ }
+
+ // list fetches the choices behind an api route: {items} or, when they cannot be read,
+ // {error}. A reply that is not JSON, such as the login page after the session ran out, counts
+ // as an error too.
+ async function list(url) {
+ try {
+ const resp = await fetch(url, { headers: { Accept: "application/json" } });
+ const body = await resp.json();
+ return resp.ok ? { items: body.items || [] } : { error: body.error || "HTTP " + resp.status };
+ } catch (e) {
+ return { error: "the list could not be read" };
+ }
+ }
+
+ function day(stamp) {
+ return stamp && !stamp.startsWith("0001") ? stamp.slice(0, 10) : "";
+ }
+
+ // latest makes sure only the answer to the newest request is used when the choice changes
+ // faster than the lists arrive.
+ function latest() {
+ let n = 0;
+ return function (promise) {
+ const mine = ++n;
+ return promise.then((v) => (mine === n ? v : null));
+ };
+ }
+
+ // splitArtifact cuts oci://host/owner/name:tag into the artifact and the tag.
+ function splitArtifact(value) {
+ const colon = value.lastIndexOf(":");
+ if (colon > value.lastIndexOf("/") && colon > "oci:".length) {
+ return { base: value.slice(0, colon), tag: value.slice(colon + 1) };
+ }
+ return { base: value, tag: "" };
+ }
+
+ function artifactPicker(input) {
+ const source = document.getElementById(input.dataset.registryFrom || "");
+ const tagOnly = "tagOnly" in input.dataset;
+ const label = document.querySelector('label[for="' + input.id + '"]');
+ const box = document.createElement("div");
+ box.className = "picker";
+ box.hidden = true;
+ const pkg = document.createElement("select");
+ pkg.id = input.id + "-package";
+ pkg.setAttribute("aria-label", "Package");
+ const tag = document.createElement("select");
+ tag.id = input.id + "-tag";
+ tag.setAttribute("aria-label", "Tag");
+ if (!tagOnly) box.append(pkg);
+ box.append(tag);
+ const hint = document.createElement("p");
+ hint.className = "muted";
+ hint.hidden = true;
+ input.before(box);
+ input.after(hint);
+ const packages = latest();
+ const tags = latest();
+ let wanted = splitArtifact(input.value);
+
+ function registry() {
+ return source ? source.value : input.dataset.registry || "";
+ }
+
+ function manual(reason) {
+ box.hidden = true;
+ input.hidden = false;
+ hint.textContent = reason ? "Enter the artifact: " + reason : "";
+ hint.hidden = !reason;
+ if (label) label.htmlFor = input.id;
+ }
+
+ function chosen(select) {
+ box.hidden = false;
+ hint.hidden = true;
+ if (label) label.htmlFor = select.id;
+ }
+
+ function compose() {
+ const base = tagOnly ? wanted.base : pkg.value;
+ if (!tagOnly && base === OTHER) {
+ tag.hidden = true;
+ input.hidden = false;
+ return;
+ }
+ tag.hidden = false;
+ if (tag.value === OTHER) {
+ input.hidden = false;
+ if (!input.value.startsWith(base + ":")) input.value = base + ":";
+ return;
+ }
+ input.hidden = true;
+ input.value = base + ":" + tag.value;
+ wanted = splitArtifact(input.value);
+ }
+
+ async function loadTags(base) {
+ const url =
+ "/api/connections/registry/" + encodeURIComponent(registry()) +
+ "/tags?artifact=" + encodeURIComponent(base);
+ const reply = await tags(list(url));
+ if (!reply) return;
+ if (reply.error) {
+ if (tagOnly) return manual(reply.error);
+ fill(tag, [option(OTHER, "other tag…")], OTHER);
+ hint.textContent = "The tags could not be read: " + reply.error;
+ hint.hidden = false;
+ return compose();
+ }
+ const options = reply.items.map((t) => {
+ const when = day(t.created);
+ return option(t.name, when ? t.name + " (" + when + ")" : t.name);
+ });
+ options.push(option(OTHER, "other tag…"));
+ hint.hidden = true;
+ const current = base === wanted.base ? wanted.tag : "";
+ fill(tag, options, current || (reply.items.length ? reply.items[0].name : OTHER));
+ if (current && tag.value !== current) {
+ // A tag the list does not know, such as one pushed a moment ago: keep what is there.
+ tag.value = OTHER;
+ }
+ if (tagOnly) chosen(tag);
+ compose();
+ }
+
+ async function loadPackages() {
+ const name = registry();
+ if (!name) {
+ // Drop the answers still on their way for the connection that was chosen before.
+ packages(Promise.resolve(null));
+ tags(Promise.resolve(null));
+ return manual("");
+ }
+ if (tagOnly) return loadTags(wanted.base);
+ const reply = await packages(list("/api/connections/registry/" + encodeURIComponent(name) + "/packages"));
+ if (!reply) return;
+ if (reply.error) return manual(reply.error);
+ const options = reply.items.map((p) => option(p.artifact, p.name));
+ options.push(option(OTHER, "other artifact…"));
+ const pick = wanted.base || (reply.items.length ? reply.items[0].artifact : OTHER);
+ fill(pkg, options, pick);
+ if (pkg.value !== pick) pkg.value = OTHER;
+ chosen(pkg);
+ await onPackage();
+ }
+
+ async function onPackage() {
+ if (pkg.value === OTHER) {
+ tags(Promise.resolve(null));
+ return compose();
+ }
+ tag.replaceChildren();
+ await loadTags(pkg.value);
+ }
+
+ pkg.addEventListener("change", onPackage);
+ tag.addEventListener("change", compose);
+ input.addEventListener("input", () => {
+ wanted = splitArtifact(input.value);
+ });
+ if (source) source.addEventListener("change", loadPackages);
+ loadPackages();
+ }
+
+ function domainPicker(input) {
+ const source = document.getElementById(input.dataset.cloudflareFrom || "");
+ if (!source) return;
+ const label = document.querySelector('label[for="' + input.id + '"]');
+ const select = document.createElement("select");
+ select.id = input.id + "-zone";
+ select.hidden = true;
+ const hint = document.createElement("p");
+ hint.className = "muted";
+ hint.hidden = true;
+ input.before(select);
+ input.after(hint);
+ const zones = latest();
+
+ function manual(reason) {
+ select.hidden = true;
+ input.hidden = false;
+ hint.textContent = reason ? "Enter the domain: " + reason : "";
+ hint.hidden = !reason;
+ if (label) label.htmlFor = input.id;
+ }
+
+ function apply() {
+ if (select.value === OTHER) {
+ input.hidden = false;
+ return;
+ }
+ input.hidden = true;
+ input.value = select.value;
+ }
+
+ async function load() {
+ if (!source.value) {
+ zones(Promise.resolve(null));
+ return manual("");
+ }
+ const reply = await zones(list("/api/connections/cloudflare/" + encodeURIComponent(source.value) + "/zones"));
+ if (!reply) return;
+ if (reply.error) return manual(reply.error);
+ const options = [option("", input.dataset.emptyLabel || "the cluster's domain")];
+ reply.items.forEach((z) => options.push(option(z, z)));
+ options.push(option(OTHER, "other domain…"));
+ const current = input.value.trim();
+ fill(select, options, current);
+ if (select.value !== current) select.value = OTHER;
+ select.hidden = false;
+ hint.hidden = true;
+ if (label) label.htmlFor = select.id;
+ apply();
+ }
+
+ select.addEventListener("change", apply);
+ source.addEventListener("change", load);
+ load();
+ }
+
+ document.querySelectorAll("input[data-registry-from], input[data-registry]").forEach(artifactPicker);
+ document.querySelectorAll("input[data-cloudflare-from]").forEach(domainPicker);
+})();
diff --git a/internal/server/ui/static/style.css b/internal/server/ui/static/style.css
index b1d4251..6970035 100644
--- a/internal/server/ui/static/style.css
+++ b/internal/server/ui/static/style.css
@@ -167,6 +167,10 @@ button.link {
.inline label { margin: 0; flex-basis: 100%; }
.inline input { flex: 1 1 16rem; }
.inline button { margin-top: 0; }
+/* The choices form.js puts in front of an artifact or domain field. */
+[hidden] { display: none !important; }
+.picker { display: flex; flex: 1 1 16rem; gap: 0.6rem; }
+.picker select { flex: 1 1 0; min-width: 0; }
.check { display: flex; align-items: center; gap: 0.5rem; margin-top: 1rem; }
.check input { width: auto; }
From 3beab34595cd5caf4d104b33513f341b6bf22e4a Mon Sep 17 00:00:00 2001
From: tweinmann
Date: Tue, 29 Sep 2026 14:19:29 +0000
Subject: [PATCH 2/5] Enhance quick tunnel functionality and documentation
- Updated app-failed.html and app-ready.html to clarify quick tunnel usage and its temporary nature.
- Modified dashboard-list-error.html and dashboard-reserved-domain.html to include quick tunnel information.
- Adjusted dashboard.html and new.html to reflect changes in quick tunnel descriptions.
- Enhanced app.html and dashboard.html to display quick tunnel status and address changes.
- Added quick tunnel handling in form.js for connection validation.
- Introduced smoke tests for quick tunnel functionality in quick.sh.
- Updated resourceset.yaml to support quick tunnel configurations.
- Created new test cases in tunnel_test.go for quick tunnel parsing and identification.
- Added new HTML templates for quick tunnel status display in app-quick.html and dashboard-quick.html.
---
CLAUDE.md | 13 +-
docs/plan.md | 68 ++++++-
go.mod | 5 +-
hack/smoke/apps.sh | 8 +-
hack/smoke/expose.sh | 2 +-
hack/smoke/quick.sh | 127 ++++++++++++
hack/smoke/tenant.sh | 2 +-
internal/cli/access_test.go | 70 ++++++-
internal/cli/app.go | 37 ++--
internal/cli/harness_test.go | 4 +-
internal/cli/status.go | 6 +-
internal/cluster/apps.go | 23 ++-
internal/cluster/client.go | 3 +-
internal/cluster/cluster_test.go | 3 +-
internal/cluster/install.go | 8 +-
internal/cluster/state.go | 17 +-
internal/cluster/testdata/objects.yaml | 22 +++
internal/cluster/tunnel.go | 117 ++++++++++-
internal/cluster/tunnel_test.go | 64 +++++++
internal/ops/apps.go | 54 ++++--
internal/ops/status.go | 10 +-
internal/ops/status_test.go | 50 +++++
internal/server/actions.go | 24 ++-
internal/server/server_test.go | 65 ++++++-
internal/server/testdata/app-failed.html | 6 +-
internal/server/testdata/app-quick.html | 181 ++++++++++++++++++
internal/server/testdata/app-ready.html | 6 +-
.../server/testdata/dashboard-list-error.html | 3 +-
internal/server/testdata/dashboard-quick.html | 107 +++++++++++
.../testdata/dashboard-reserved-domain.html | 3 +-
internal/server/testdata/dashboard.html | 3 +-
internal/server/testdata/new.html | 6 +-
internal/server/ui/app.html | 14 +-
internal/server/ui/dashboard.html | 11 +-
internal/server/ui/new.html | 6 +-
internal/server/ui/static/form.js | 3 +-
justfile | 4 +
platform/apps/resourceset.yaml | 31 ++-
38 files changed, 1088 insertions(+), 98 deletions(-)
create mode 100755 hack/smoke/quick.sh
create mode 100644 internal/cluster/tunnel_test.go
create mode 100644 internal/server/testdata/app-quick.html
create mode 100644 internal/server/testdata/dashboard-quick.html
diff --git a/CLAUDE.md b/CLAUDE.md
index ff331ac..f999481 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -56,6 +56,11 @@ Also in 8b (2026-09-29): the forms offer the deploy artifacts and tags of the re
(GitHub API, `internal/github`) and the zones of the Cloudflare connection as selects, with free
text as the fallback; `shelf connection packages|zones` and `shelf app tags` list the same. Level 1
green; `form.js` untested against real connections.
+Phase 8d in progress (2026-09-29): an app without a Cloudflare connection gets a quick tunnel
+(random `*.trycloudflare.com` name, changes when cloudflared restarts) unless it is `--private`;
+cloudflared rewrites the Host header to the app's own host, and shelf reads the name from
+`/quicktunnel` through the pod proxy. Apps from before stay private. LAN access (proxy + mDNS)
+was considered and rejected. Level 1 green; `just smoke-quick` not run yet.
Next: Phase 9 (Mac mini: host setup, Colima, `shelf doctor`, `shelf destroy`).
## Working agreements
@@ -110,6 +115,7 @@ Mac. Tool versions are pinned in `.devcontainer/Dockerfile`.
| `just smoke-apps` | devcontainer | Phase 4: `shelf app add`/`rm`, rollout by polling, tampered artifact refused, restore from backup (needs network) |
| `just smoke-tenant ` | devcontainer | Phase 4 acceptance with a real tenant repo and GHCR; asks for the GHCR login, waits for a push |
| `just smoke-expose ` | devcontainer | Phase 8b acceptance: the app gets the Cloudflare connection `smoke`, its own tunnel, DNS record and HTTPS, then is taken off again; asks for the Cloudflare API token; needs a cluster with a host suffix |
+| `just smoke-quick [app]` | devcontainer | Phase 8d acceptance: `examples/hello` as `hello-quick` without a connection gets a quick tunnel, answers with its own Host, gets a new name after a restart, `--private`/`--quick`, rm; keeps the cluster's domain; opens a public trycloudflare.com tunnel for a few minutes |
| `hack/nuke.sh` | host Mac terminal (refuses to run in a container) | remove every Docker object shelf created (only needs `docker`) |
## Safety rules
@@ -140,6 +146,8 @@ Mac. Tool versions are pinned in `.devcontainer/Dockerfile`.
record by anything but its exact name, and never one without the `-dev` suffix.
- `shelf app rm` deletes an app's volumes; never run it against an app you did not create in
this session.
+- A quick tunnel puts an app on the internet without any account. Smoke tests other than
+ `smoke-quick` add apps with `--private`; never give an app you did not create a quick tunnel.
- `shelf init cluster` with a different `--host-suffix` moves every app to another host name, a
different `--domain` every app without a domain of its own, and strands their DNS records. It
refuses to do that while such apps exist unless `--move-hosts` is passed. The smoke tests install `dev.local` and refuse to run against a
@@ -159,8 +167,9 @@ Mac. Tool versions are pinned in `.devcontainer/Dockerfile`.
registry it is for (`ghcr.io`); `ops.Env.Pull` overrides it, the Docker keychain is the last
resort. A machine running shelf as a service has no Docker config
- Per app in `shelf-system`, all labelled `shelf.dev/app`: the provider `` (inputs `name`,
- `url`, `tag`, `insecure`, `domain`, `tunnel`, `registry`, `cloudflare` — the last two are
- connection names), `app-` (secret values), `tunnel-`. Registry connections are
+ `url`, `tag`, `insecure`, `domain`, `tunnel`, `quick`, `registry`, `cloudflare` — the last two
+ are connection names; `tunnel` and `quick` never both), `app-` (secret values),
+ `tunnel-` (named tunnels only). Registry connections are
`connection-registry-` (label `shelf.dev/connection=registry`), and `registry-anonymous`
is what an app without one gets. An app's tunnel is `shelf-`, its host
`.`
diff --git a/docs/plan.md b/docs/plan.md
index 8834cc7..a517a60 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -170,7 +170,7 @@ connections the apps choose:
| Question | Decision |
|---|---|
-| Scope | **No platform-wide credentials.** The shared PAT, `shelf init expose` and the shared tunnel are gone. Registry logins and Cloudflare tokens are **connections**: defined once, by name, and chosen per app. An app without a registry connection reads its registry anonymously (public packages, the dev registry); an app without a Cloudflare connection runs inside the cluster only. The first cut (2026-09-28) gave every app its own token directly; the maintainer asked the next day for connections, so that a token is typed once, a new one reaches every app that uses it, and the UI offers a choice instead of password fields. |
+| Scope | **No platform-wide credentials.** The shared PAT, `shelf init expose` and the shared tunnel are gone. Registry logins and Cloudflare tokens are **connections**: defined once, by name, and chosen per app. An app without a registry connection reads its registry anonymously (public packages, the dev registry); an app without a Cloudflare connection runs inside the cluster only (since Phase 8d: behind a quick tunnel, unless private). The first cut (2026-09-28) gave every app its own token directly; the maintainer asked the next day for connections, so that a token is typed once, a new one reaches every app that uses it, and the UI offers a choice instead of password fields. |
| Isolation | **Apps share only what the user assigns to several of them: a connection.** Namespace, secret values, tunnel and cloudflared stay every app's own. The shared login and tunnel before this phase were shared by the platform, without anyone choosing it — one tenant's token pulled every tenant's packages. |
| Registry connection | **In the cluster, `shelf-system/connection-registry-`** (dockerconfigjson, label `shelf.dev/connection=registry`). The ResourceSet copies it into the namespace of every app that chooses it, and an app without one gets `shelf-system/registry-anonymous`, which holds no login, so the copy always has a source. The cluster pulls with it anyway, and a new login reaches every app at once through the watch label. shelf reads the artifact with the same login, so the machine running shelf needs no Docker config. |
| Cloudflare connection | **Token and account, in `~/.shelf/connections/cloudflare/.yaml`** (0600 in a 0700 directory, through `internal/hostcfg`), never in the cluster. The Phase 5 rule holds: nothing in the cluster needs the token, and a pod that escapes into the VM does not reach it. The price is that only the machine holding the file can expose, move or withdraw apps through it — in practice the mini. Without the file nothing fails silently: shelf leaves record and tunnel as they are and says so, and `shelf connection add cloudflare ` defines it again. A Secret in `shelf-system` was considered and rejected: anyone who can read that namespace would own the zones of all apps. |
@@ -203,6 +203,22 @@ from the app's name in shelf:
| `shelf build-plan` | **Prints `{package, builds}`** instead of `{app, builds}`, and the workflow reads `.package`. The fix to `release.yml` switches workflow and binary together. |
| Phase | No phase of its own: a change to Phase 8b's conventions, released as v0.5.0. |
+Decided on 2026-09-29 (Phase 8d), when the maintainer asked how apps could be reached without a
+Cloudflare account of their own:
+
+| Question | Decision |
+|---|---|
+| LAN access | **Not built.** Considered: the host service proxies port 80 on the LAN to a NodePort of Traefik, and answers mDNS for `.shelf.local`. It would have needed a second port on the LAN, an mDNS responder, a second host name per Ingress, and it cannot be tested beyond the devcontainer, because Docker Desktop does not pass multicast to the real network. Rejected in favour of keeping tunnels the only way in. |
+| An app without a Cloudflare connection | **Gets a quick tunnel by default**: cloudflared without an account asks trycloudflare.com for a random `https://.trycloudflare.com` name. No token, no zone, no DNS record, no port on the mini, and it works on a reserved domain such as `dev.local`. `--private` (UI: "none: inside the cluster only") keeps an app inside the cluster. |
+| Its limits | Written into the help texts and the UI rather than hidden: the name is random and **changes whenever cloudflared restarts**; the app is public to anyone who has the name; Cloudflare offers quick tunnels for trying things out, with no uptime guarantee, a limit of concurrent requests and no server-sent events. A stable name needs a domain and a Cloudflare connection, as before. |
+| Routing | cloudflared rewrites the Host header to the app's own `.` (`--http-host-header`), so Traefik routes as it does for a named tunnel and the chart stays unchanged. The app sees its own host name, not the trycloudflare one. |
+| Where the name comes from | cloudflared reports it on its metrics port at `/quicktunnel` (`{"hostname": …}`, checked against `cloudflare/cloudflared:2026.9.1`). shelf reads it through the API server's pod proxy, so `internal/cluster` still talks to the API server only; nothing stores the name, every status reads it anew. `shelf app add` prints it as the detail of the wait for the tunnel. |
+| Apps registered before | **Stay inside the cluster.** `init cluster` gives their providers `quick: false`, and the ResourceSet reads the input with `index inputs "quick"`, which is empty for a provider without it, where `inputs.quick` would fail the whole ResourceSet under `missingkey=error` — in the dev cluster Flux can pick up a pushed platform before `init cluster` migrates. An upgrade never puts an app on the internet. Only a new app gets the quick tunnel by default. |
+| Old platform, new shelf | **Refused before anything is written.** A shelf that adds a quick tunnel to a cluster whose ResourceSet does not know the input would wait for a cloudflared that never comes; `cluster.AddApp` checks the ResourceSet first and says to run `shelf init cluster` (or `--private`). Found in the first manual run: the job hung at "waiting for the tunnel" until its timeout. |
+| Flags | `shelf app add` takes `--private`; `shelf app credentials` takes `--quick` and `--private`, and `--no-cloudflare` now means `--quick`. A Cloudflare connection, a quick tunnel and private exclude each other. |
+| Smoke tests | `apps.sh`, `tenant.sh` and `expose.sh` pass `--private`, so they open no public tunnel; only `just smoke-quick` does. |
+| Phase | **8d**, before the Mac mini. (8c is the name the reverted change of the same day had.) |
+
## Validated assumptions
These close three of the four original spikes:
@@ -545,7 +561,7 @@ an encrypted volume.
| App rendering | Helm chart `shelf-app`, rendered by helm-controller |
| App registration | Flux Operator `ResourceSet` + `ResourceSetInputProvider` |
| Ingress | Traefik (Helm, ClusterIP — no LoadBalancer) |
-| Exposure | `cloudflared` in-cluster, one catch-all rule pointing at Traefik |
+| Exposure | `cloudflared` in the app namespace, one catch-all rule pointing at Traefik: a named tunnel with a Cloudflare connection, otherwise a quick tunnel with the Host header rewritten |
| DNS | one proxied CNAME per app, written by the CLI through the Cloudflare API |
Platform components are installed by Flux from an OCI artifact of the shelf release: the
@@ -1663,6 +1679,54 @@ Results so far (2026-09-29):
shared tunnel of Phase 5; the migration switches that off, and exposing the app again needs the
Cloudflare token. That is the maintainer's call, not a side effect of a test.
+### Phase 8d – Quick tunnels
+An app without a Cloudflare connection used to be reachable from inside the cluster only. It now
+gets a quick tunnel at a random trycloudflare.com name, unless it is private. The decisions are in
+the table "Decided on 2026-09-29 (Phase 8d)" above.
+
+Design:
+
+- **Provider input `quick`** (bool) next to `tunnel`; at most one of them is set.
+ `cluster.AppOptions`, `AppConfig` and `AppState` carry it, `AppState.QuickURL` the current name.
+- **Platform**: `resourcesTemplate` renders the Secret and the ConfigMap only for a named tunnel,
+ and the cloudflared Deployment for either; for a quick tunnel it runs
+ `tunnel --no-autoupdate --metrics 0.0.0.0:2000 --url http://traefik… --http-host-header `.
+- **`internal/cluster`**: `waitForTunnel` waits for a cloudflared that runs a quick tunnel
+ (`--url` in its arguments, so the one of a named tunnel does not pass), then for the rollout,
+ then for a name at `/quicktunnel`, read through the pod proxy from a ready pod that is not being
+ deleted. `AppStates` asks each app with a quick tunnel; one that cannot answer has no address.
+- **`ops`**: `Access` has `Quick` and `Private` instead of `RemoveCloudflare`. A new app with no
+ choice gets a quick tunnel; an existing one keeps what it has. Leaving a Cloudflare connection
+ reuses the Phase 8b cleanup (record and tunnel deleted after cloudflared moved). `app()` links
+ the quick name, on any domain, and the components' links follow it.
+- **Admin UI**: the Cloudflare select starts with "none: a quick tunnel …" and
+ "none: inside the cluster only" (`@private`, which no connection name can be); the pages say
+ that the address is temporary, or that the tunnel has none yet.
+
+**Acceptance:** an app added without a connection answers at the trycloudflare name shelf
+printed, with its own host name in the Host header; `shelf app status` and the UI show the new
+name after cloudflared restarts; `--private` stops cloudflared, `--quick` starts it again; apps
+from before stay private; the smoke tests of earlier phases open no public tunnel.
+
+Results so far (2026-09-29):
+
+- Level 1 is green (`just test`). New tests: the quick default, `--private` and a private app
+ that stays private on the next deploy, the moves from a named tunnel to a quick one and to
+ private (record and tunnel deleted), the exclusive flags, the addresses in `app()` and its
+ components, `/quicktunnel` parsing, telling the two cloudflared apart, the form choices, and the
+ golden pages `dashboard-quick` and `app-quick`.
+- The ResourceSet template was rendered offline for a named tunnel, a quick tunnel on the
+ cluster's domain and on one of its own, and a private app; every document is valid YAML.
+- cloudflared 2026.9.1 was run once in the devcontainer against a dead origin: `/quicktunnel`
+ answered with the name before `/ready` turned 200, which is why the wait checks both.
+- `just smoke-quick` keeps the cluster's domain and host suffix, since a quick tunnel needs
+ neither, and re-installs the platform with them. Not run yet.
+- Manual level 2 in the dev cluster (`tobile.ch`, suffix `-dev`): the app `honk`, added from the
+ admin UI, first hung at the tunnel because the cluster still ran the old platform (see "Old
+ platform, new shelf"). After `platform-push` and `init cluster` with the cluster's settings, the
+ provider of `vermiet` got `quick: false` and kept its named tunnel, `honk` got cloudflared, and
+ `https://.trycloudflare.com/` answered with the app within seconds.
+
### Phase 9 – Mac mini: host, Colima, doctor, destroy
The old Phase 6, without the installer. `shelf init host`: preflight (Apple Silicon, RAM, disk,
macOS version, Rosetta, Homebrew, tool versions, existing profile, energy settings), tool
diff --git a/go.mod b/go.mod
index 3cccb2a..753b47b 100644
--- a/go.mod
+++ b/go.mod
@@ -7,10 +7,12 @@ require (
github.com/invopop/jsonschema v0.14.0
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
github.com/spf13/cobra v1.10.2
+ github.com/spf13/pflag v1.0.10
go.yaml.in/yaml/v3 v3.0.5
k8s.io/apimachinery v0.36.4
k8s.io/client-go v0.36.4
sigs.k8s.io/cli-utils v0.37.2
+ sigs.k8s.io/yaml v1.6.0
)
require (
@@ -39,7 +41,6 @@ require (
github.com/opencontainers/image-spec v1.1.1 // indirect
github.com/pb33f/ordered-map/v2 v2.3.1 // indirect
github.com/sirupsen/logrus v1.9.4 // indirect
- github.com/spf13/pflag v1.0.10 // indirect
github.com/x448/float16 v0.8.4 // indirect
go.yaml.in/yaml/v2 v2.4.3 // indirect
go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect
@@ -51,6 +52,7 @@ require (
golang.org/x/text v0.39.0 // indirect
golang.org/x/time v0.14.0 // indirect
google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af // indirect
+ gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
gopkg.in/inf.v0 v0.9.1 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
gotest.tools/v3 v3.5.2 // indirect
@@ -61,5 +63,4 @@ require (
sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
sigs.k8s.io/randfill v1.0.0 // indirect
sigs.k8s.io/structured-merge-diff/v6 v6.3.3 // indirect
- sigs.k8s.io/yaml v1.6.0 // indirect
)
diff --git a/hack/smoke/apps.sh b/hack/smoke/apps.sh
index 04a2d41..62e0eb9 100755
--- a/hack/smoke/apps.sh
+++ b/hack/smoke/apps.sh
@@ -84,7 +84,7 @@ digest="$(publish "$work/v1")"
step "shelf app add"
start=$SECONDS
-shelf app add "$app" "$artifact:main" --insecure-registry | tee "$work/add1.txt"
+shelf app add "$app" "$artifact:main" --insecure-registry --private | tee "$work/add1.txt"
echo "add: $((SECONDS - start)) s"
grep -q '^secret db-password: generated$' "$work/add1.txt" || die "the secret was not generated"
password="$(sed -n 's/^ *db-password: //p' "$SHELF_HOME/apps/$app/secrets.yaml")"
@@ -109,7 +109,7 @@ routed() { curl -sS -H "Host: $app.dev.local" http://127.0.0.1:18082/ | grep -q
retry 30 routed || die "$app.dev.local does not reach web"
step "the same artifact as a second app, with a host and a secret of its own"
-shelf app add "$copy" "$artifact:main" --insecure-registry >"$work/copy.txt"
+shelf app add "$copy" "$artifact:main" --insecure-registry --private >"$work/copy.txt"
copy_password="$(sed -n 's/^ *db-password: //p' "$SHELF_HOME/apps/$copy/secrets.yaml")"
[[ ${#copy_password} -ge 26 ]] || die "no password in the backup of $copy"
[[ "$copy_password" != "$password" ]] || die "$copy got the secret value of $app"
@@ -135,7 +135,7 @@ retry 240 three_replicas || die "web was not scaled to 3 within 4 minutes"
echo "rolled out after $((SECONDS - start)) s"
step "shelf app add again changes nothing and keeps the secret"
-shelf app add "$app" "$artifact:main" --insecure-registry | tee "$work/add2.txt"
+shelf app add "$app" "$artifact:main" --insecure-registry --private | tee "$work/add2.txt"
grep -q '^secret db-password: kept$' "$work/add2.txt" || die "the secret was not kept"
grep -q "^ResourceSetInputProvider shelf-system/$app: unchanged$" "$work/add2.txt" \
|| die "the provider changed"
@@ -180,7 +180,7 @@ kubectl -n shelf-system get resourcesetinputprovider "$app" >/dev/null 2>&1 && d
shelf app rm "$app" --yes >/dev/null 2>&1 && die "removing a missing app must fail"
step "shelf app add restores the secret from the backup"
-shelf app add "$app" "$artifact:main" --insecure-registry | tee "$work/add3.txt"
+shelf app add "$app" "$artifact:main" --insecure-registry --private | tee "$work/add3.txt"
grep -q '^secret db-password: restored from the backup$' "$work/add3.txt" || die "the secret was not restored"
url="$(kubectl -n "$app" exec deploy/check -- printenv DATABASE_URL)"
[[ "$url" == "postgres://app:$password@db:5432/hello" ]] || die "the restored password differs"
diff --git a/hack/smoke/expose.sh b/hack/smoke/expose.sh
index 57dfc6f..7de4a25 100755
--- a/hack/smoke/expose.sh
+++ b/hack/smoke/expose.sh
@@ -130,7 +130,7 @@ cf "/zones/$zone/dns_records/$(jq -r '.id' <<<"$rec")" -X PATCH -H 'Content-Type
[[ "$(record | jq -r '.content')" == "$target" ]] || die "the record still points somewhere else"
step "off the internet again: record, tunnel and cloudflared are gone"
-"$work/shelf" app credentials "$app" --no-cloudflare | tee "$work/off.txt"
+"$work/shelf" app credentials "$app" --private | tee "$work/off.txt"
[[ -z "$(record)" ]] || die "the record of $host is still there"
[[ -z "$(find_tunnel "$tunnel_name")" ]] || die "tunnel $tunnel_name is still there"
kubectl -n "$app" get deploy cloudflared >/dev/null 2>&1 && die "cloudflared still runs"
diff --git a/hack/smoke/quick.sh b/hack/smoke/quick.sh
new file mode 100755
index 0000000..6bf314a
--- /dev/null
+++ b/hack/smoke/quick.sh
@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Checks the Phase 8c acceptance: an app added without a Cloudflare connection is exposed through
+# a quick tunnel. shelf reports its trycloudflare.com address, the address reaches the app with
+# the app's own host name in the Host header, a restarted cloudflared gets a new address that
+# `shelf app status` shows, and --private takes the app off the internet again.
+#
+# Usage: hack/smoke/quick.sh [app] (default hello-quick; deploys examples/hello under that name)
+# Installs or updates the platform first (idempotent), keeping the cluster's domain and host
+# suffix: a quick tunnel does not depend on either, so this runs on any dev cluster. Needs network
+# access for images and for trycloudflare.com; no Cloudflare account or token.
+set -euo pipefail
+source "$(dirname "$0")/../lib.sh"
+require_devcontainer
+
+repo="$(cd "$(dirname "$0")/../.." && pwd)"
+work="$(mktemp -d)"
+app="${1:-hello-quick}"
+artifact="oci://$SHELF_REGISTRY_HOST/smoke/hello-deploy"
+export SHELF_HOME="$work/home"
+setting() { kubectl -n flux-system get configmap shelf-config -o jsonpath="{.data.$1}" 2>/dev/null || true; }
+domain="$(setting SHELF_DOMAIN)"
+domain="${domain:-$SHELF_DEV_DOMAIN}"
+suffix="$(setting SHELF_HOST_SUFFIX)"
+host="$app$suffix.$domain"
+
+shelf() { "$work/shelf" "$@"; }
+
+cleanup() {
+ if [[ "${KEEP:-}" == 1 ]]; then
+ echo "KEEP=1: leaving app $app in place; its secret backup is in $SHELF_HOME"
+ return
+ fi
+ shelf app rm "$app" --yes >/dev/null 2>&1 || true
+ rm -rf "$work"
+}
+
+step() { echo "--- $*"; }
+
+# Waits up to $1 seconds for a command to succeed.
+retry() {
+ local seconds="$1"
+ shift
+ for _ in $(seq "$seconds"); do
+ "$@" >/dev/null 2>&1 && return 0
+ sleep 1
+ done
+ return 1
+}
+
+for leftover in "namespace/$app" "-n shelf-system resourcesetinputprovider/$app"; do
+ # shellcheck disable=SC2086
+ kubectl get $leftover >/dev/null 2>&1 \
+ && die "$leftover already exists; remove it first (shelf app rm $app)"
+done
+trap cleanup EXIT
+
+step "build shelf, push platform and chart, init cluster"
+(cd "$repo" && go build -o "$work/shelf" ./cmd/shelf)
+"$repo/hack/platform-push.sh" >/dev/null 2>&1
+"$repo/hack/chart-push.sh" >/dev/null 2>&1
+shelf init cluster --yes --domain "$domain" --host-suffix "$suffix" --insecure-registry \
+ --platform "oci://$SHELF_REGISTRY_HOST/shelf/platform:dev" \
+ --chart "oci://$SHELF_REGISTRY_HOST/shelf/charts/shelf-app:0.0.0-dev" >/dev/null
+
+step "publish examples/hello"
+mkdir -p "$work/v1"
+(cd "$repo" && go run ./cmd/shelf render examples/hello/app.yaml) >"$work/v1/configmap.yaml" 2>/dev/null
+flux push artifact "$artifact:main" --path "$work/v1" --source local \
+ --revision "main@sha1:$(head -c 20 /dev/urandom | od -An -tx1 | tr -d ' \n')" \
+ --insecure-registry >/dev/null 2>&1 || die "push failed"
+
+step "shelf app add without a connection gives the app a quick tunnel"
+start=$SECONDS
+shelf app add "$app" "$artifact:main" --insecure-registry | tee "$work/add.txt"
+echo "add: $((SECONDS - start)) s"
+grep -q '^internet: a quick tunnel' "$work/add.txt" || die "the app did not get a quick tunnel"
+url="$(grep -o 'https://[a-z0-9-]*\.trycloudflare\.com/' "$work/add.txt" | tail -1)"
+[[ -n "$url" ]] || die "shelf did not report the address of the quick tunnel"
+echo "address: $url"
+kubectl -n shelf-system get secret "tunnel-$app" >/dev/null 2>&1 && die "a quick tunnel needs no credentials"
+
+# reaches : the app answers there, and sees its own host name rather than trycloudflare's.
+# Resolve through Cloudflare's DoH endpoint: the container's resolver may have cached the name
+# as missing before the tunnel registered it.
+reaches() {
+ curl -fsS --max-time 10 --doh-url https://cloudflare-dns.com/dns-query "$1" >"$work/answer.txt" &&
+ grep -q '^Hostname: web-' "$work/answer.txt" &&
+ grep -qi "^Host: $host" "$work/answer.txt"
+}
+
+step "the address reaches the app with its own host name"
+start=$SECONDS
+retry 120 reaches "$url" || { cat "$work/answer.txt" 2>/dev/null; die "$url did not reach $app within 2 minutes"; }
+echo "reachable after $((SECONDS - start)) s"
+shelf app status "$app" | tee "$work/status1.txt"
+grep -qF "address $url" "$work/status1.txt" || die "shelf app status does not show $url"
+
+step "a restarted cloudflared gets a new address, and status follows it"
+kubectl -n "$app" rollout restart deploy/cloudflared >/dev/null
+kubectl -n "$app" rollout status deploy/cloudflared --timeout=120s >/dev/null
+moved() {
+ shelf app status "$app" >"$work/status2.txt" &&
+ new="$(grep -o 'https://[a-z0-9-]*\.trycloudflare\.com/' "$work/status2.txt")" &&
+ [[ -n "$new" && "$new" != "$url" ]]
+}
+retry 60 moved || die "shelf app status still shows the old address"
+new="$(grep -o 'https://[a-z0-9-]*\.trycloudflare\.com/' "$work/status2.txt")"
+echo "new address: $new"
+retry 120 reaches "$new" || die "$new did not reach $app within 2 minutes"
+
+step "--private takes the app off the internet"
+shelf app credentials "$app" --private | tee "$work/private.txt"
+kubectl -n "$app" get deploy cloudflared >/dev/null 2>&1 && die "cloudflared still runs"
+shelf app status "$app" | grep -q trycloudflare && die "status still shows a quick tunnel"
+
+step "--quick puts it back"
+shelf app credentials "$app" --quick | tee "$work/quick.txt"
+back="$(grep -o 'https://[a-z0-9-]*\.trycloudflare\.com/' "$work/quick.txt" | tail -1)"
+[[ -n "$back" ]] || die "shelf did not report the address of the quick tunnel"
+retry 120 reaches "$back" || die "$back did not reach $app within 2 minutes"
+
+step "shelf app rm"
+shelf app rm "$app" --yes >/dev/null
+kubectl get namespace "$app" >/dev/null 2>&1 && die "namespace $app is still there"
+
+echo "PASS: quick tunnel by default, address reported, Host rewritten to $host," \
+ "new address after a restart, --private and --quick, app rm"
diff --git a/hack/smoke/tenant.sh b/hack/smoke/tenant.sh
index 511917c..2edaf23 100755
--- a/hack/smoke/tenant.sh
+++ b/hack/smoke/tenant.sh
@@ -57,7 +57,7 @@ mkdir -p "$DOCKER_CONFIG"
step "shelf connection add registry tenant, then shelf app add --registry tenant"
shelf connection add registry tenant | tee "$work/connection.txt"
-shelf app add "$app" "$artifact" --registry tenant | tee "$work/add.txt"
+shelf app add "$app" "$artifact" --registry tenant --private | tee "$work/add.txt"
grep -q "^registry connection: tenant$" "$work/add.txt" || die "the app did not get the connection"
grep -qF "$GHCR_TOKEN" "$work/connection.txt" "$work/add.txt" && die "the token appears in the output"
kubectl -n shelf-system get secret connection-registry-tenant >/dev/null || die "the connection is not in the cluster"
diff --git a/internal/cli/access_test.go b/internal/cli/access_test.go
index 5cae83c..4ad160a 100644
--- a/internal/cli/access_test.go
+++ b/internal/cli/access_test.go
@@ -305,6 +305,41 @@ func TestAppAddWithCloudflare(t *testing.T) {
}
}
+// TestAppAddQuickByDefault covers an app without a Cloudflare connection: it goes on the internet
+// through a quick tunnel, which needs neither Cloudflare nor a public domain, unless it is private.
+func TestAppAddQuickByDefault(t *testing.T) {
+ t.Parallel()
+ h := cloudflareHarness(t)
+ h.cluster.settings = cluster.Settings{Domain: "dev.local", HostSuffix: "-dev"}
+
+ stdout := h.mustRun(t, "app", "add", "greeter", greeterArtifact)
+ if added := h.lastAdded(t); !added.Quick || added.TunnelID != "" || added.Cloudflare != "" {
+ t.Errorf("quick %t, tunnel %q, connection %q; a new app gets a quick tunnel", added.Quick, added.TunnelID, added.Cloudflare)
+ }
+ if !strings.Contains(stdout, "internet: a quick tunnel, as there is no Cloudflare connection") {
+ t.Errorf("stdout:\n%s", stdout)
+ }
+ if len(h.api.created)+len(h.api.records)+len(h.api.zoneFor) != 0 {
+ t.Error("a quick tunnel needs nothing from the Cloudflare API")
+ }
+
+ // The next deploy keeps it.
+ h.mustRun(t, "app", "add", "greeter", greeterArtifact)
+ if added := h.lastAdded(t); !added.Quick {
+ t.Error("a deploy without flags keeps the quick tunnel")
+ }
+
+ // A private app stays private, and so does an app registered before quick tunnels existed.
+ h.mustRun(t, "app", "add", "notes", greeterArtifact, "--private")
+ if added := h.lastAdded(t); added.Quick || added.TunnelID != "" {
+ t.Errorf("quick %t, tunnel %q; --private keeps the app inside the cluster", added.Quick, added.TunnelID)
+ }
+ h.mustRun(t, "app", "add", "notes", greeterArtifact)
+ if added := h.lastAdded(t); added.Quick {
+ t.Error("a deploy without flags keeps a private app private")
+ }
+}
+
func TestAppAddWithADomainOfItsOwn(t *testing.T) {
t.Parallel()
h := cloudflareHarness(t)
@@ -338,6 +373,7 @@ func TestAppCredentialsMovesTheApp(t *testing.T) {
wantRecords []string
wantGone []string
wantTunnel string
+ wantQuick bool
}{
{
name: "another domain in the same account",
@@ -356,10 +392,24 @@ func TestAppCredentialsMovesTheApp(t *testing.T) {
wantTunnel: "tunnel-2",
},
{
- name: "off the internet",
+ name: "to a quick tunnel",
+ args: []string{"--quick"},
+ wantDeleted: []string{"tunnel-1"},
+ wantGone: []string{"greeter-dev.example.com in zone-example.com"},
+ wantQuick: true,
+ },
+ {
+ name: "without a connection, which is a quick tunnel",
args: []string{"--no-cloudflare"},
wantDeleted: []string{"tunnel-1"},
wantGone: []string{"greeter-dev.example.com in zone-example.com"},
+ wantQuick: true,
+ },
+ {
+ name: "off the internet",
+ args: []string{"--private"},
+ wantDeleted: []string{"tunnel-1"},
+ wantGone: []string{"greeter-dev.example.com in zone-example.com"},
},
}
for _, tt := range tests {
@@ -384,8 +434,8 @@ func TestAppCredentialsMovesTheApp(t *testing.T) {
t.Errorf("deleted records %v, want %v", h.api.deletedRecords, tt.wantGone)
}
added := h.lastAdded(t)
- if added.TunnelID != tt.wantTunnel || added.Artifact.String() != greeterArtifact {
- t.Errorf("the cluster got tunnel %q and artifact %s", added.TunnelID, added.Artifact)
+ if added.TunnelID != tt.wantTunnel || added.Quick != tt.wantQuick || added.Artifact.String() != greeterArtifact {
+ t.Errorf("the cluster got tunnel %q, quick %t and artifact %s", added.TunnelID, added.Quick, added.Artifact)
}
if stored, _ := h.conns.Cloudflare("tobile"); stored == nil {
t.Error("a connection belongs to no app; it stays when an app leaves it")
@@ -505,9 +555,19 @@ func TestAccessErrors(t *testing.T) {
wantErr: "nothing to change",
},
{
- name: "given and removed",
+ name: "a connection and a quick tunnel",
args: []string{"app", "credentials", "greeter", "--cloudflare", "tobile", "--no-cloudflare"},
- wantErr: "given and removed at once",
+ wantErr: "or not at all; choose one",
+ },
+ {
+ name: "a quick tunnel and private",
+ args: []string{"app", "credentials", "greeter", "--quick", "--private"},
+ wantErr: "or not at all; choose one",
+ },
+ {
+ name: "private with a connection",
+ args: []string{"app", "add", "greeter", greeterArtifact, "--cloudflare", "tobile", "--private"},
+ wantErr: "or not at all; choose one",
},
{
name: "unknown app",
diff --git a/internal/cli/app.go b/internal/cli/app.go
index 87059e7..c2bce4d 100644
--- a/internal/cli/app.go
+++ b/internal/cli/app.go
@@ -27,7 +27,12 @@ func newAppCmd(o Options) *cobra.Command {
const accessHelp = `--registry names the registry connection the app pulls its deploy artifact and its images
with; without one, it reads the registry anonymously. --cloudflare names the Cloudflare
connection it is exposed through: it gets a tunnel of its own in that connection's account, and
-its domain has to be a zone of that account. Connections are defined with ` + "`shelf connection add`" + `.`
+its domain has to be a zone of that account. Connections are defined with ` + "`shelf connection add`" + `.
+
+Without a Cloudflare connection, an app is exposed through a quick tunnel: Cloudflare gives it a
+random https://.trycloudflare.com address, which needs no account and no domain, but
+changes whenever the tunnel restarts, and is meant for trying things out. ` + "`shelf app status`" + `
+shows the current one. --private keeps the app inside the cluster instead.`
// accessFlags choose what an app reaches its registry and the internet with.
type accessFlags struct {
@@ -36,6 +41,8 @@ type accessFlags struct {
noRegistry bool
cloudflare string
noCloudflare bool
+ quick bool
+ private bool
}
// register adds the flags; removable adds the ones that take a connection away again.
@@ -44,25 +51,30 @@ func (f *accessFlags) register(fs *pflag.FlagSet, removable bool) {
"a domain of the app's own: it answers at . (default: the cluster's)")
fs.StringVar(&f.registry, "registry", "", "the registry connection the app pulls with")
fs.StringVar(&f.cloudflare, "cloudflare", "", "the Cloudflare connection the app is exposed through")
+ fs.BoolVar(&f.private, "private", false,
+ "keep the app off the internet, even without a Cloudflare connection; a tunnel it had is deleted")
if removable {
fs.BoolVar(&f.noRegistry, "no-registry", false, "pull without a login")
- fs.BoolVar(&f.noCloudflare, "no-cloudflare", false,
- "take the app off the internet: delete its record and its tunnel")
+ fs.BoolVar(&f.quick, "quick", false,
+ "expose the app through a quick tunnel; a tunnel and a record it had are deleted")
+ fs.BoolVar(&f.noCloudflare, "no-cloudflare", false, "the same as --quick")
}
}
// changes reports whether any flag asks for a change.
func (f *accessFlags) changes() bool {
- return f.domain != "" || f.registry != "" || f.noRegistry || f.cloudflare != "" || f.noCloudflare
+ return f.domain != "" || f.registry != "" || f.noRegistry || f.cloudflare != "" || f.noCloudflare ||
+ f.quick || f.private
}
func (f *accessFlags) access() (ops.Access, error) {
a := ops.Access{
- Domain: f.domain,
- Registry: f.registry,
- RemoveRegistry: f.noRegistry,
- Cloudflare: f.cloudflare,
- RemoveCloudflare: f.noCloudflare,
+ Domain: f.domain,
+ Registry: f.registry,
+ RemoveRegistry: f.noRegistry,
+ Cloudflare: f.cloudflare,
+ Quick: f.quick || f.noCloudflare,
+ Private: f.private,
}
return a, a.Check()
}
@@ -135,7 +147,8 @@ func newAppCredentialsCmd(o Options) *cobra.Command {
deployed again from the artifact it is registered with. What is not given stays as it is.
Moving the app to another domain or another Cloudflare connection deletes its record, and its
-tunnel if the account changes; --no-cloudflare takes it off the internet.
+tunnel if the account changes; --quick moves it to a quick tunnel, and --private takes it off
+the internet.
` + accessHelp,
Args: cobra.ExactArgs(1),
@@ -146,7 +159,7 @@ tunnel if the account changes; --no-cloudflare takes it off the internet.
}
if !access.changes() {
return fmt.Errorf("nothing to change; pass --domain, --registry, --cloudflare, " +
- "--no-registry or --no-cloudflare")
+ "--no-registry, --quick or --private")
}
given, err := access.access()
if err != nil {
@@ -173,7 +186,7 @@ func newAppRmCmd(o Options) *cobra.Command {
Use: "rm ",
Short: "Remove an app with all its data",
Long: `Remove an app: its namespace with all objects and volumes, its secrets in the cluster,
-and, if it is exposed, its DNS record and its Cloudflare tunnel. The secret backup on this
+and, if it is exposed through a Cloudflare connection, its DNS record and its Cloudflare tunnel. The secret backup on this
machine is kept.`,
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/cli/harness_test.go b/internal/cli/harness_test.go
index dcddf11..b8be98d 100644
--- a/internal/cli/harness_test.go
+++ b/internal/cli/harness_test.go
@@ -82,7 +82,7 @@ func (f *fakeCluster) AddApp(_ context.Context, _ *rest.Config, o cluster.AppOpt
}
config := &cluster.AppConfig{
Artifact: o.Artifact, Insecure: o.Insecure, Domain: o.Domain, Registry: o.Registry,
- Cloudflare: o.Cloudflare, TunnelID: o.TunnelID, TunnelCredentials: o.TunnelCredentials,
+ Cloudflare: o.Cloudflare, TunnelID: o.TunnelID, TunnelCredentials: o.TunnelCredentials, Quick: o.Quick,
}
if previous := f.configs[o.Name]; previous != nil && o.TunnelCredentials == nil && o.TunnelID != "" {
config.TunnelCredentials = previous.TunnelCredentials
@@ -91,7 +91,7 @@ func (f *fakeCluster) AddApp(_ context.Context, _ *rest.Config, o cluster.AppOpt
// The states follow what is registered, as they do in a cluster.
f.states = slices.DeleteFunc(f.states, func(s cluster.AppState) bool { return s.Name == o.Name })
f.states = append(f.states, cluster.AppState{
- Name: o.Name, Artifact: o.Artifact, Domain: o.Domain, Tunnel: o.TunnelID,
+ Name: o.Name, Artifact: o.Artifact, Domain: o.Domain, Tunnel: o.TunnelID, Quick: o.Quick,
Registry: o.Registry, Cloudflare: o.Cloudflare,
})
return nil
diff --git a/internal/cli/status.go b/internal/cli/status.go
index 51fba8c..4fe7880 100644
--- a/internal/cli/status.go
+++ b/internal/cli/status.go
@@ -46,7 +46,7 @@ This is what the admin UI shows on its pages, in text.`,
return err
}
printApp(out, app)
- printComponents(out, app.Components, app.Public)
+ printComponents(out, app.Components, app.Public || app.Quick)
printChain(out, diagnosis)
return nil
},
@@ -91,6 +91,10 @@ func printApp(out io.Writer, app ops.App) {
fmt.Fprintf(out, " exposed through connection %s, which this machine does not hold\n", app.Cloudflare)
case app.Cloudflare != "":
fmt.Fprintf(out, " exposed through connection %s, account %s\n", app.Cloudflare, app.CloudflareAccount)
+ case app.Quick && app.URL == "":
+ fmt.Fprintln(out, " exposed through a quick tunnel, which has no address yet")
+ case app.Quick:
+ fmt.Fprintln(out, " exposed through a quick tunnel; the address changes when it restarts")
}
if app.Revision != "" {
fmt.Fprintf(out, " running %s\n", app.Revision)
diff --git a/internal/cluster/apps.go b/internal/cluster/apps.go
index ba37df9..58195b9 100644
--- a/internal/cluster/apps.go
+++ b/internal/cluster/apps.go
@@ -56,11 +56,14 @@ type AppOptions struct {
// Cloudflare is the Cloudflare connection the app is exposed through. The cluster only keeps
// its name; the token stays on the machine that runs shelf.
Cloudflare string
- // TunnelID is the app's Cloudflare tunnel; empty means the app is not exposed, and the
- // platform stops its cloudflared.
+ // TunnelID is the app's Cloudflare tunnel; empty means the app has no tunnel of its own.
TunnelID string
// TunnelCredentials is the credentials.json of that tunnel, or nil to keep the stored one.
TunnelCredentials []byte
+ // Quick gives an app without a tunnel of its own a quick tunnel at a random
+ // trycloudflare.com name. Without either, the app is not exposed, and the platform stops its
+ // cloudflared.
+ Quick bool
// Secrets are all secret values of the app; they replace the stored ones.
Secrets map[string]string
Timeout time.Duration
@@ -109,6 +112,7 @@ func AppProvider(o AppOptions) *unstructured.Unstructured {
"insecure": o.Insecure,
"domain": o.Domain,
"tunnel": o.TunnelID,
+ "quick": o.Quick,
"registry": o.Registry,
"cloudflare": o.Cloudflare,
},
@@ -143,7 +147,8 @@ func AppSecrets(ctx context.Context, cfg *rest.Config, app string) (map[string]s
// AddApp stores the app's secrets, its tunnel and its provider, then waits
// until Flux has deployed the current artifact and the HelmRelease is ready, and until the app's
-// cloudflared runs — or, for an app that is no longer exposed, until it is gone. Running it again
+// cloudflared runs — or, for an app that is no longer exposed, until it is gone. For a quick
+// tunnel, the wait ends with its address. Running it again
// updates all of it and waits again.
func AddApp(ctx context.Context, cfg *rest.Config, o AppOptions) error {
ctx, cancel := context.WithTimeout(ctx, o.Timeout)
@@ -153,6 +158,11 @@ func AddApp(ctx context.Context, cfg *rest.Config, o AppOptions) error {
return err
}
rep := progress.OrDiscard(o.Report)
+ if o.Quick {
+ if err := c.checkQuickTunnels(ctx); err != nil {
+ return err
+ }
+ }
objs := []*unstructured.Unstructured{AppSecret(o.Name, o.Secrets)}
if o.TunnelCredentials != nil {
@@ -174,7 +184,7 @@ func AddApp(ctx context.Context, cfg *rest.Config, o AppOptions) error {
if err := c.rollOut(ctx, rep, o.Name, o.Artifact); err != nil {
return err
}
- return c.waitForTunnel(ctx, rep, o.Name, o.TunnelID)
+ return c.waitForTunnel(ctx, rep, o.Name, o.TunnelID, o.Quick)
}
// AppConfig is how an app is registered: what `shelf app add` stored, read back.
@@ -187,10 +197,12 @@ type AppConfig struct {
Registry string
// Cloudflare is the app's Cloudflare connection, empty when it is not exposed.
Cloudflare string
- // TunnelID is the app's Cloudflare tunnel, empty when it is not exposed.
+ // TunnelID is the app's Cloudflare tunnel, empty when it has none of its own.
TunnelID string
// TunnelCredentials is the credentials.json the cluster holds for that tunnel.
TunnelCredentials []byte
+ // Quick means the app is exposed through a quick tunnel.
+ Quick bool
}
// ReadAppConfig returns how an app is registered, or nil when there is no such app.
@@ -210,6 +222,7 @@ func ReadAppConfig(ctx context.Context, cfg *rest.Config, app string) (*AppConfi
config.Insecure, _ = values["insecure"].(bool)
config.Domain, _ = values["domain"].(string)
config.TunnelID, _ = values["tunnel"].(string)
+ config.Quick, _ = values["quick"].(bool)
config.Registry, _ = values["registry"].(string)
config.Cloudflare, _ = values["cloudflare"].(string)
diff --git a/internal/cluster/client.go b/internal/cluster/client.go
index e72378d..f1b7bf7 100644
--- a/internal/cluster/client.go
+++ b/internal/cluster/client.go
@@ -48,6 +48,7 @@ func classify(before, after string) Action {
var pollInterval = 2 * time.Second
type client struct {
+ cfg *rest.Config
dyn dynamic.Interface
mapper *restmapper.DeferredDiscoveryRESTMapper
}
@@ -61,7 +62,7 @@ func newClient(cfg *rest.Config) (*client, error) {
if err != nil {
return nil, err
}
- return &client{dyn: dyn, mapper: restmapper.NewDeferredDiscoveryRESTMapper(memory.NewMemCacheClient(disc))}, nil
+ return &client{cfg: cfg, dyn: dyn, mapper: restmapper.NewDeferredDiscoveryRESTMapper(memory.NewMemCacheClient(disc))}, nil
}
func (c *client) resource(gvk schema.GroupVersionKind, namespace string) (dynamic.ResourceInterface, error) {
diff --git a/internal/cluster/cluster_test.go b/internal/cluster/cluster_test.go
index 579f8e1..f77ead6 100644
--- a/internal/cluster/cluster_test.go
+++ b/internal/cluster/cluster_test.go
@@ -225,7 +225,8 @@ func TestPlatformObjects(t *testing.T) {
TunnelSecret("hello", []byte(`{"TunnelID":"t-1","TunnelSecret":"not-a-real-secret"}`)),
AppProvider(AppOptions{Name: "hello", Artifact: app, Domain: "example.com", TunnelID: "t-1",
Registry: "ghcr", Cloudflare: "tobile"}),
- AppProvider(AppOptions{Name: "empty", Artifact: app}))
+ AppProvider(AppOptions{Name: "empty", Artifact: app}),
+ AppProvider(AppOptions{Name: "quick", Artifact: app, Quick: true}))
var out []byte
for _, obj := range objs {
diff --git a/internal/cluster/install.go b/internal/cluster/install.go
index 5969558..db083de 100644
--- a/internal/cluster/install.go
+++ b/internal/cluster/install.go
@@ -174,10 +174,11 @@ func (c *client) migrateSharedCredentials(ctx context.Context, rep progress.Repo
}
for _, p := range providers {
// The platform refers to every input, so an app registered before the inputs existed
- // gets them: the shared login as its connection, the cluster's domain and no tunnel.
+ // gets them: the shared login as its connection, the cluster's domain and no tunnel —
+ // not even a quick one, so that an upgrade never puts an app on the internet.
values, _, _ := unstructured.NestedMap(p.Object, "spec", "defaultValues")
missing := false
- for _, key := range []string{"domain", "tunnel", "registry", "cloudflare"} {
+ for _, key := range []string{"domain", "tunnel", "quick", "registry", "cloudflare"} {
if _, ok := values[key]; !ok {
missing = true
}
@@ -192,7 +193,8 @@ func (c *client) migrateSharedCredentials(ctx context.Context, rep progress.Repo
}
if err := c.applyReport(ctx, rep, AppProvider(AppOptions{
Name: state.Name, Artifact: state.Artifact, Insecure: state.Insecure,
- Domain: state.Domain, TunnelID: state.Tunnel, Registry: registry, Cloudflare: state.Cloudflare,
+ Domain: state.Domain, TunnelID: state.Tunnel, Quick: state.Quick, Registry: registry,
+ Cloudflare: state.Cloudflare,
})); err != nil {
return err
}
diff --git a/internal/cluster/state.go b/internal/cluster/state.go
index 94cb25a..38d3c80 100644
--- a/internal/cluster/state.go
+++ b/internal/cluster/state.go
@@ -79,8 +79,12 @@ type AppState struct {
Insecure bool `json:"insecure,omitempty"`
// Domain is the app's own domain, empty when it answers under the cluster's.
Domain string `json:"domain,omitempty"`
- // Tunnel is the app's Cloudflare tunnel, empty when the app is not exposed.
+ // Tunnel is the app's Cloudflare tunnel, empty when the app has none of its own.
Tunnel string `json:"tunnel,omitempty"`
+ // Quick means the app is exposed through a quick tunnel.
+ Quick bool `json:"quick,omitempty"`
+ // QuickURL is the current address of that quick tunnel, empty while cloudflared has none.
+ QuickURL string `json:"quickURL,omitempty"`
// Registry is the app's registry connection, empty when it pulls without a login.
Registry string `json:"registry,omitempty"`
// Cloudflare is the app's Cloudflare connection, empty when it is not exposed.
@@ -107,7 +111,7 @@ type appObjects struct {
}
// AppStates returns every registered app with its current state. It reads the whole cluster in
-// five list calls, however many apps there are.
+// five list calls, however many apps there are, plus two for each app with a quick tunnel.
func AppStates(ctx context.Context, cfg *rest.Config) ([]AppState, error) {
c, err := newClient(cfg)
if err != nil {
@@ -119,7 +123,13 @@ func AppStates(ctx context.Context, cfg *rest.Config) ([]AppState, error) {
}
states := make([]AppState, 0, len(apps))
for _, name := range slices.Sorted(maps.Keys(apps)) {
- states = append(states, appState(name, apps[name]))
+ state := appState(name, apps[name])
+ if state.Quick {
+ // A quick tunnel's name exists only in its cloudflared. One that cannot be asked
+ // yet has no address, which the page says; it is not a reason to fail the list.
+ state.QuickURL, _ = c.quickURL(ctx, name)
+ }
+ states = append(states, state)
}
return states, nil
}
@@ -229,6 +239,7 @@ func providerState(provider *unstructured.Unstructured) AppState {
state.Insecure, _ = values["insecure"].(bool)
state.Domain, _ = values["domain"].(string)
state.Tunnel, _ = values["tunnel"].(string)
+ state.Quick, _ = values["quick"].(bool)
state.Registry, _ = values["registry"].(string)
state.Cloudflare, _ = values["cloudflare"].(string)
return state
diff --git a/internal/cluster/testdata/objects.yaml b/internal/cluster/testdata/objects.yaml
index 1666ed9..ceedce4 100644
--- a/internal/cluster/testdata/objects.yaml
+++ b/internal/cluster/testdata/objects.yaml
@@ -89,6 +89,7 @@ spec:
domain: example.com
insecure: false
name: hello
+ quick: false
registry: ghcr
tag: main
tunnel: t-1
@@ -108,6 +109,27 @@ spec:
domain: ""
insecure: false
name: empty
+ quick: false
+ registry: ""
+ tag: main
+ tunnel: ""
+ url: oci://ghcr.io/tweinmann/hello-deploy
+ type: Static
+---
+apiVersion: fluxcd.controlplane.io/v1
+kind: ResourceSetInputProvider
+metadata:
+ labels:
+ shelf.dev/app: quick
+ name: quick
+ namespace: shelf-system
+spec:
+ defaultValues:
+ cloudflare: ""
+ domain: ""
+ insecure: false
+ name: quick
+ quick: true
registry: ""
tag: main
tunnel: ""
diff --git a/internal/cluster/tunnel.go b/internal/cluster/tunnel.go
index b59212b..73b29ff 100644
--- a/internal/cluster/tunnel.go
+++ b/internal/cluster/tunnel.go
@@ -3,6 +3,8 @@ package cluster
import (
"context"
"encoding/base64"
+ "encoding/json"
+ "errors"
"fmt"
"slices"
"strings"
@@ -11,6 +13,7 @@ import (
"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
"k8s.io/apimachinery/pkg/runtime/schema"
"k8s.io/apimachinery/pkg/util/wait"
+ corev1client "k8s.io/client-go/kubernetes/typed/core/v1"
"k8s.io/client-go/rest"
"github.com/tweinmann/shelf/internal/progress"
@@ -64,11 +67,32 @@ func tunnelCredentials(obj *unstructured.Unstructured) ([]byte, error) {
return credentials, nil
}
-// waitForTunnel waits until cloudflared in the app namespace runs for the given tunnel, or,
-// without one, until it is gone. Closing matters as much as opening: Cloudflare refuses to delete
-// a tunnel that still has connections, and shelf deletes the old tunnel right after this.
-func (c *client) waitForTunnel(ctx context.Context, rep progress.Reporter, app, tunnel string) error {
+// waitForTunnel waits until cloudflared in the app namespace runs for the given tunnel, or for
+// a quick tunnel and has its address, or, without either, until it is gone. Closing matters as
+// much as opening: Cloudflare refuses to delete a tunnel that still has connections, and shelf
+// deletes the old tunnel right after this.
+func (c *client) waitForTunnel(ctx context.Context, rep progress.Reporter, app, tunnel string, quick bool) error {
deployment := ref{gvk: deploymentGVK, namespace: app, name: CloudflaredName}
+ if tunnel == "" && quick {
+ return c.step(ctx, rep, "the tunnel", func(ctx context.Context) (string, error) {
+ // A cloudflared that still runs a named tunnel must not pass.
+ err := c.waitFor(ctx, deployment, func(obj *unstructured.Unstructured) (bool, string, error) {
+ return isQuick(obj), "waiting for the platform to configure cloudflared", nil
+ })
+ if err != nil {
+ return "", err
+ }
+ if err := c.waitFor(ctx, deployment, current); err != nil {
+ return "", err
+ }
+ var url string
+ err = wait.PollUntilContextCancel(ctx, pollInterval, true, func(ctx context.Context) (bool, error) {
+ url, _ = c.quickURL(ctx, app)
+ return url != "", nil
+ })
+ return url, err
+ })
+ }
if tunnel == "" {
obj, err := c.get(ctx, deployment)
if err != nil || obj == nil {
@@ -140,3 +164,88 @@ func (c *client) applyReport(ctx context.Context, rep progress.Reporter, obj *un
rep.Report(progress.Applied(describe(obj), string(action), ""))
return nil
}
+
+var resourceSetGVK = schema.GroupVersionKind{Group: "fluxcd.controlplane.io", Version: "v1", Kind: "ResourceSet"}
+
+// appsResourceSet is the ResourceSet of the platform that deploys every app.
+const appsResourceSet = "apps"
+
+// quickInput is how the platform refers to the input of a quick tunnel.
+const quickInput = `"quick"`
+
+// checkQuickTunnels fails when the platform in the cluster is older than quick tunnels: it would
+// never start cloudflared for one, and a wait for it would only end at the timeout.
+func (c *client) checkQuickTunnels(ctx context.Context) error {
+ obj, err := c.get(ctx, ref{gvk: resourceSetGVK, namespace: SystemNamespace, name: appsResourceSet})
+ if err != nil {
+ return err
+ }
+ template := ""
+ if obj != nil {
+ template, _, _ = unstructured.NestedString(obj.Object, "spec", "resourcesTemplate")
+ }
+ if !strings.Contains(template, quickInput) {
+ return errors.New("the platform in this cluster does not run quick tunnels yet; " +
+ "install the platform of this shelf with `shelf init cluster` first, or add the app with --private")
+ }
+ return nil
+}
+
+// quickArg is what tells the cloudflared of a quick tunnel from that of a named one.
+const quickArg = "--url"
+
+// isQuick reports whether a cloudflared Deployment runs a quick tunnel.
+func isQuick(deployment *unstructured.Unstructured) bool {
+ containers, _, _ := unstructured.NestedSlice(deployment.Object, "spec", "template", "spec", "containers")
+ for _, c := range containers {
+ container, _ := c.(map[string]any)
+ args, _, _ := unstructured.NestedStringSlice(container, "args")
+ if slices.Contains(args, quickArg) {
+ return true
+ }
+ }
+ return false
+}
+
+// metricsPort is where cloudflared answers /ready and, for a quick tunnel, /quicktunnel.
+const metricsPort = "2000"
+
+// quickURL asks the running cloudflared of an app for the name of its quick tunnel, through the
+// API server's proxy to the pod. It is empty while no cloudflared is ready to answer.
+func (c *client) quickURL(ctx context.Context, app string) (string, error) {
+ core, err := corev1client.NewForConfig(c.cfg)
+ if err != nil {
+ return "", err
+ }
+ pods, err := c.list(ctx, podGVK, app, "app.kubernetes.io/name="+CloudflaredName)
+ if err != nil {
+ return "", err
+ }
+ for _, pod := range pods {
+ // A pod on its way out still answers, with the name that is about to go away.
+ if ready := condition(pod, "Ready"); pod.GetDeletionTimestamp() != nil || ready == nil || ready["status"] != "True" {
+ continue
+ }
+ body, err := core.Pods(app).ProxyGet("http", pod.GetName(), metricsPort, "quicktunnel", nil).DoRaw(ctx)
+ if err != nil {
+ return "", err
+ }
+ return parseQuickTunnel(body)
+ }
+ return "", nil
+}
+
+// parseQuickTunnel reads the answer of cloudflared's /quicktunnel, such as
+// {"hostname":"some-words.trycloudflare.com"}, into a URL.
+func parseQuickTunnel(body []byte) (string, error) {
+ var answer struct {
+ Hostname string `json:"hostname"`
+ }
+ if err := json.Unmarshal(body, &answer); err != nil {
+ return "", fmt.Errorf("reading the quick tunnel of cloudflared: %w", err)
+ }
+ if answer.Hostname == "" {
+ return "", nil
+ }
+ return "https://" + answer.Hostname + "/", nil
+}
diff --git a/internal/cluster/tunnel_test.go b/internal/cluster/tunnel_test.go
new file mode 100644
index 0000000..c620ff4
--- /dev/null
+++ b/internal/cluster/tunnel_test.go
@@ -0,0 +1,64 @@
+package cluster
+
+import (
+ "os"
+ "strings"
+ "testing"
+
+ "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+)
+
+func TestParseQuickTunnel(t *testing.T) {
+ t.Parallel()
+ tests := map[string]struct {
+ body string
+ want string
+ wantErr bool
+ }{
+ "address": {body: `{"hostname":"some-words.trycloudflare.com"}`, want: "https://some-words.trycloudflare.com/"},
+ "none yet": {body: `{"hostname":""}`},
+ "not json": {body: `404 page not found`, wantErr: true},
+ "extra keys": {body: `{"hostname":"a.trycloudflare.com","other":1}`, want: "https://a.trycloudflare.com/"},
+ }
+ for name, tt := range tests {
+ t.Run(name, func(t *testing.T) {
+ t.Parallel()
+ got, err := parseQuickTunnel([]byte(tt.body))
+ if (err != nil) != tt.wantErr || got != tt.want {
+ t.Errorf("got %q, %v; want %q, error %t", got, err, tt.want, tt.wantErr)
+ }
+ })
+ }
+}
+
+// TestIsQuick tells the cloudflared of a quick tunnel from that of a named one, which is what
+// the wait after a change from one to the other depends on.
+func TestIsQuick(t *testing.T) {
+ t.Parallel()
+ deployment := func(args ...any) *unstructured.Unstructured {
+ return &unstructured.Unstructured{Object: map[string]any{
+ "spec": map[string]any{"template": map[string]any{"spec": map[string]any{
+ "containers": []any{map[string]any{"name": "cloudflared", "args": args}},
+ }}},
+ }}
+ }
+ if !isQuick(deployment("tunnel", "--no-autoupdate", "--url", "http://traefik")) {
+ t.Error("a quick tunnel is not recognised")
+ }
+ if isQuick(deployment("tunnel", "--config", "/etc/cloudflared/config/config.yaml", "run")) {
+ t.Error("a named tunnel is taken for a quick one")
+ }
+}
+
+// TestPlatformRunsQuickTunnels keeps checkQuickTunnels and the platform in step: the check looks
+// for the input in the ResourceSet that ships with this shelf.
+func TestPlatformRunsQuickTunnels(t *testing.T) {
+ t.Parallel()
+ data, err := os.ReadFile("../../platform/apps/resourceset.yaml")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(data), quickInput) {
+ t.Errorf("platform/apps/resourceset.yaml does not refer to %s", quickInput)
+ }
+}
diff --git a/internal/ops/apps.go b/internal/ops/apps.go
index 89ea9ac..7ddfe46 100644
--- a/internal/ops/apps.go
+++ b/internal/ops/apps.go
@@ -43,8 +43,24 @@ type Access struct {
// Cloudflare is the Cloudflare connection the app is exposed through, with a tunnel of its
// own in that connection's account.
Cloudflare string
- // RemoveCloudflare takes the app off the internet: its record and its tunnel are deleted.
- RemoveCloudflare bool
+ // Quick exposes the app through a quick tunnel at a random trycloudflare.com name instead:
+ // no Cloudflare connection, no domain of its own needed. A tunnel and a record the app had
+ // through a connection are deleted. A new app without a connection gets one unless Private.
+ Quick bool
+ // Private takes the app off the internet: it answers inside the cluster only, and a tunnel
+ // and a record it had are deleted.
+ Private bool
+}
+
+// exposures counts how many ways to reach the internet an Access asks for at once.
+func (a Access) exposures() int {
+ n := 0
+ for _, set := range []bool{a.Cloudflare != "", a.Quick, a.Private} {
+ if set {
+ n++
+ }
+ }
+ return n
}
// Check rejects access that contradicts itself. The messages carry no field name, so a caller
@@ -63,10 +79,10 @@ func (a Access) Check() error {
return err
}
}
+ if a.exposures() > 1 {
+ return errors.New("an app is exposed through a Cloudflare connection, through a quick tunnel, or not at all; choose one")
+ }
if a.Cloudflare != "" {
- if a.RemoveCloudflare {
- return errors.New("a Cloudflare connection cannot be given and removed at once")
- }
if err := CheckConnectionName(a.Cloudflare); err != nil {
return err
}
@@ -87,9 +103,10 @@ type AddOptions struct {
// AddApp registers an app and waits until it runs: it reads the deploy artifact, works out the
// app's secret values, writes them to the backup and to the cluster, and exposes the app through
-// its own tunnel if it has a Cloudflare connection. Running it again updates the artifact reference,
-// keeps every value that exists, generates the ones that were added to app.yaml since, and
-// keeps the app's access except where it is changed.
+// its own tunnel if it has a Cloudflare connection, or else, unless it is private, through a
+// quick tunnel. Running it again updates the artifact reference, keeps every value that exists,
+// generates the ones that were added to app.yaml since, and keeps the app's access except where
+// it is changed.
func (o *Ops) AddApp(ctx context.Context, opts AddOptions, report progress.Reporter) error {
rep := progress.OrDiscard(report)
if err := opts.Access.Check(); err != nil {
@@ -100,9 +117,14 @@ func (o *Ops) AddApp(ctx context.Context, opts AddOptions, report progress.Repor
return err
}
if current == nil {
- current = &cluster.AppConfig{}
+ // A new app goes on the internet the way that needs nothing set up, unless it is told
+ // otherwise.
+ current = &cluster.AppConfig{Quick: opts.Access.exposures() == 0}
+ if current.Quick {
+ rep.Report(progress.Info("internet: a quick tunnel, as there is no Cloudflare connection"))
+ }
}
- registry, cloudflare := current.Registry, current.Cloudflare
+ registry, cloudflare, quick := current.Registry, current.Cloudflare, current.Quick
switch {
case opts.Access.RemoveRegistry:
registry = ""
@@ -112,11 +134,14 @@ func (o *Ops) AddApp(ctx context.Context, opts AddOptions, report progress.Repor
rep.Report(progress.Info("registry connection: %s", registry))
}
switch {
- case opts.Access.RemoveCloudflare:
- cloudflare = ""
- rep.Report(progress.Info("Cloudflare connection: none"))
+ case opts.Access.Private:
+ cloudflare, quick = "", false
+ rep.Report(progress.Info("internet: none, inside the cluster only"))
+ case opts.Access.Quick:
+ cloudflare, quick = "", true
+ rep.Report(progress.Info("internet: a quick tunnel"))
case opts.Access.Cloudflare != "":
- cloudflare = opts.Access.Cloudflare
+ cloudflare, quick = opts.Access.Cloudflare, false
rep.Report(progress.Info("Cloudflare connection: %s", cloudflare))
}
if opts.Access.Cloudflare != "" && opts.Access.Cloudflare != current.Cloudflare {
@@ -183,6 +208,7 @@ func (o *Ops) AddApp(ctx context.Context, opts AddOptions, report progress.Repor
Cloudflare: cloudflare,
TunnelID: exposure.tunnelID(),
TunnelCredentials: exposure.credentials,
+ Quick: quick,
Secrets: values,
Timeout: opts.Timeout,
Report: rep,
diff --git a/internal/ops/status.go b/internal/ops/status.go
index 8825372..0532200 100644
--- a/internal/ops/status.go
+++ b/internal/ops/status.go
@@ -13,7 +13,7 @@ import (
type App struct {
cluster.AppState
// Host is the name the app answers under, empty when neither the app nor the cluster has a
- // domain.
+ // domain. For an app with a quick tunnel that has its address, it is the tunnel's random name.
Host string `json:"host,omitempty"`
// Public is false when the app's domain cannot exist on the internet, as dev.local cannot.
// The app then answers inside the cluster only, whatever else is set up.
@@ -150,9 +150,15 @@ func app(state cluster.AppState, settings cluster.Settings) App {
}
a.Host = AppHost(state.Name, settings.HostSuffix, domain)
a.Public = PublicDomain(domain)
+ switch {
+ // A quick tunnel does not need the domain to exist: the app answers under the random name
+ // cloudflared was given, as long as it has one.
+ case state.Quick && state.QuickURL != "":
+ a.URL = state.QuickURL
+ a.Host = strings.TrimSuffix(strings.TrimPrefix(state.QuickURL, "https://"), "/")
// Only a name that exists on the internet and a tunnel that carries it make a link that
// works; otherwise the host name is a fact about the cluster, not an address.
- if state.Tunnel != "" && a.Public {
+ case state.Tunnel != "" && a.Public:
a.URL = "https://" + a.Host + "/"
}
return a
diff --git a/internal/ops/status_test.go b/internal/ops/status_test.go
index 077c5d4..f69ef95 100644
--- a/internal/ops/status_test.go
+++ b/internal/ops/status_test.go
@@ -1,6 +1,7 @@
package ops
import (
+ "strings"
"testing"
"github.com/tweinmann/shelf/internal/cluster"
@@ -100,3 +101,52 @@ func TestSiblingAddress(t *testing.T) {
})
}
}
+
+// TestAppAddress covers where an app is said to answer: a named tunnel links the app's own host
+// name, but only on a public domain; a quick tunnel links whatever name cloudflared was given,
+// on any domain, once it has one.
+func TestAppAddress(t *testing.T) {
+ t.Parallel()
+ settings := cluster.Settings{Domain: "dev.local", HostSuffix: "-dev"}
+ tests := map[string]struct {
+ state cluster.AppState
+ wantHost string
+ wantURL string
+ }{
+ "not exposed": {
+ state: cluster.AppState{Name: "hello"},
+ wantHost: "hello-dev.dev.local",
+ },
+ "named tunnel on a reserved domain": {
+ state: cluster.AppState{Name: "hello", Tunnel: "t-1"},
+ wantHost: "hello-dev.dev.local",
+ },
+ "named tunnel on a public domain": {
+ state: cluster.AppState{Name: "hello", Tunnel: "t-1", Domain: "example.com"},
+ wantHost: "hello-dev.example.com",
+ wantURL: "https://hello-dev.example.com/",
+ },
+ "quick tunnel without an address yet": {
+ state: cluster.AppState{Name: "hello", Quick: true},
+ wantHost: "hello-dev.dev.local",
+ },
+ "quick tunnel": {
+ state: cluster.AppState{Name: "hello", Quick: true, QuickURL: "https://some-words.trycloudflare.com/"},
+ wantHost: "some-words.trycloudflare.com",
+ wantURL: "https://some-words.trycloudflare.com/",
+ },
+ }
+ for name, tt := range tests {
+ t.Run(name, func(t *testing.T) {
+ t.Parallel()
+ a := app(tt.state, settings)
+ if a.Host != tt.wantHost || a.URL != tt.wantURL {
+ t.Errorf("host %q, URL %q; want %q, %q", a.Host, a.URL, tt.wantHost, tt.wantURL)
+ }
+ comps := components([]cluster.Component{{Name: "web", Path: "/app"}}, a.Host, a.URL != "")
+ if want := strings.TrimSuffix(tt.wantURL, "/") + "/app"; tt.wantURL != "" && comps[0].URL != want {
+ t.Errorf("component URL %q, want %q", comps[0].URL, want)
+ }
+ })
+ }
+}
diff --git a/internal/server/actions.go b/internal/server/actions.go
index 6a5a095..71ad735 100644
--- a/internal/server/actions.go
+++ b/internal/server/actions.go
@@ -90,16 +90,28 @@ func (s *Server) addApp(w http.ResponseWriter, r *http.Request) {
})
}
+// privateChoice is the value of the Cloudflare choice that keeps an app off the internet. It
+// cannot be the name of a connection, which is a DNS label.
+const privateChoice = "@private"
+
// accessFromForm reads what a form chooses for an app: a domain, and a connection of each kind.
-// The choice of a connection is the whole of it, so "none" takes one away. An empty domain keeps
-// the one the app has.
+// The choice of a connection is the whole of it, so "none" takes one away: without a Cloudflare
+// connection the app gets a quick tunnel, unless it is kept private. An empty domain keeps the
+// one the app has.
func accessFromForm(r *http.Request) (ops.Access, error) {
a := ops.Access{
- Domain: strings.TrimSpace(r.PostFormValue("domain")),
- Registry: r.PostFormValue("registry"),
- Cloudflare: r.PostFormValue("cloudflare"),
+ Domain: strings.TrimSpace(r.PostFormValue("domain")),
+ Registry: r.PostFormValue("registry"),
+ }
+ a.RemoveRegistry = a.Registry == ""
+ switch choice := r.PostFormValue("cloudflare"); choice {
+ case "":
+ a.Quick = true
+ case privateChoice:
+ a.Private = true
+ default:
+ a.Cloudflare = choice
}
- a.RemoveRegistry, a.RemoveCloudflare = a.Registry == "", a.Cloudflare == ""
return a, a.Check()
}
diff --git a/internal/server/server_test.go b/internal/server/server_test.go
index 0c7fd29..639902c 100644
--- a/internal/server/server_test.go
+++ b/internal/server/server_test.go
@@ -291,6 +291,47 @@ func runningPlatform() *fakePlatform {
}
}
+// quickPlatform adds two apps with quick tunnels to runningPlatform: one whose cloudflared
+// reported its address, and one whose tunnel has none yet.
+func quickPlatform() *fakePlatform {
+ p := runningPlatform()
+ p.apps = append(p.apps,
+ ops.App{
+ AppState: cluster.AppState{
+ Name: "notes",
+ Artifact: cluster.Artifact{URL: "oci://ghcr.io/tweinmann/notes", Tag: "main"},
+ Revision: "main@" + digest,
+ Deployed: now.Add(-5 * time.Minute),
+ Phase: cluster.PhaseReady,
+ Quick: true, QuickURL: "https://some-random-words.trycloudflare.com/",
+ },
+ Host: "some-random-words.trycloudflare.com",
+ Public: true,
+ URL: "https://some-random-words.trycloudflare.com/",
+ Components: []ops.Component{
+ {
+ Component: cluster.Component{Name: "web", Phase: cluster.PhaseReady,
+ Ports: []cluster.Port{{Name: "main", Number: 80}}, Path: "/"},
+ Address: "some-random-words.trycloudflare.com/",
+ URL: "https://some-random-words.trycloudflare.com/",
+ },
+ },
+ },
+ ops.App{
+ AppState: cluster.AppState{
+ Name: "draft",
+ Artifact: cluster.Artifact{URL: "oci://ghcr.io/tweinmann/draft", Tag: "main"},
+ Phase: cluster.PhaseWorking,
+ Quick: true,
+ },
+ Host: "draft-dev.example.com",
+ Public: true,
+ },
+ )
+ p.diagnoses["notes"] = p.diagnoses["greeter"]
+ return p
+}
+
// testServer builds a server with its own directory and a fixed clock.
func testServer(t *testing.T, platform server.Platform) (*server.Server, http.Handler) {
t.Helper()
@@ -428,6 +469,13 @@ func TestPages(t *testing.T) {
golden(t, "new", get(h, "/apps/new", cookie))
})
+ t.Run("quick tunnels", func(t *testing.T) {
+ t.Parallel()
+ h, cookie := claimed(t, quickPlatform())
+ golden(t, "dashboard-quick", get(h, "/", cookie))
+ golden(t, "app-quick", get(h, "/apps/notes", cookie))
+ })
+
t.Run("connections", func(t *testing.T) {
t.Parallel()
h, cookie := claimed(t, running)
@@ -878,12 +926,23 @@ func TestAccessForms(t *testing.T) {
name: "add without", path: "/apps",
form: url.Values{"name": {"greeter"}, "artifact": {"oci://ghcr.io/o/greeter:main"},
"registry": {""}, "cloudflare": {""}},
- want: ops.Access{RemoveRegistry: true, RemoveCloudflare: true},
+ want: ops.Access{RemoveRegistry: true, Quick: true},
},
{
- name: "take an app off the internet", path: "/apps/greeter/access",
+ name: "add a private app", path: "/apps",
+ form: url.Values{"name": {"greeter"}, "artifact": {"oci://ghcr.io/o/greeter:main"},
+ "registry": {""}, "cloudflare": {"@private"}},
+ want: ops.Access{RemoveRegistry: true, Private: true},
+ },
+ {
+ name: "move an app to a quick tunnel", path: "/apps/greeter/access",
form: url.Values{"registry": {"ghcr"}, "cloudflare": {""}},
- want: ops.Access{Registry: "ghcr", RemoveCloudflare: true},
+ want: ops.Access{Registry: "ghcr", Quick: true},
+ },
+ {
+ name: "take an app off the internet", path: "/apps/greeter/access",
+ form: url.Values{"registry": {"ghcr"}, "cloudflare": {"@private"}},
+ want: ops.Access{Registry: "ghcr", Private: true},
},
}
for _, tt := range tests {
diff --git a/internal/server/testdata/app-failed.html b/internal/server/testdata/app-failed.html
index 9929442..b8eb4d5 100644
--- a/internal/server/testdata/app-failed.html
+++ b/internal/server/testdata/app-failed.html
@@ -106,7 +106,8 @@
Access
@@ -116,7 +117,8 @@
Access
The connections themselves are defined on the connections
page. A new domain or a Cloudflare connection in another account moves the app's record, and
-its tunnel with it; the app is deployed again from the artifact above.
+its tunnel with it; the app is deployed again from the artifact above. Without a Cloudflare
+connection, a quick tunnel gives the app a random address that changes whenever it restarts.
diff --git a/internal/server/testdata/app-quick.html b/internal/server/testdata/app-quick.html
new file mode 100644
index 0000000..e5b1618
--- /dev/null
+++ b/internal/server/testdata/app-quick.html
@@ -0,0 +1,181 @@
+
+
+
+
+
+notes · shelf
+
+
+
+
+shelf
+
+
+
+
+
+
+
+
+
The app itself is described in the app.yaml of its repository. shelf deploys
+what the artifact above carries; to change ports, volumes or secrets, change that file and let your
+pipeline publish a new artifact.
A component answers from outside only where its app.yaml gives it a
+route. The others carry the app from within, and their address is how a component of this app
+reaches them.
+
+
+
+
+
+
+
Deploy
+
+
Point it at another tag to move the app there — a commit tag such as
+sha-905acce is how you go back to a version that worked, and the branch tag is how
+you come forward again.
+
+
Fetches the same tag once more, for when it was moved or something failed.
+
+
+
+
Access
+
+
Domain
example.com the cluster's
+
Registry
no connection, pulls without a login
+
Internet
a quick tunnel its address changes whenever the tunnel restarts
+
+
+
The connections themselves are defined on the connections
+page. A new domain or a Cloudflare connection in another account moves the app's record, and
+its tunnel with it; the app is deployed again from the artifact above. Without a Cloudflare
+connection, a quick tunnel gives the app a random address that changes whenever it restarts.
+
+
+
+
Secrets
+
+
This app declares no secrets.
+
+
+
+
How it gets here
+
+
+
+
the deploy artifactReady
+
stored artifact for digest 'main@sha256:00677bbefb02ca2056a9eb0741e12735e38067d6f155938034a4ccb612450db7'
The connections themselves are defined on the connections
page. A new domain or a Cloudflare connection in another account moves the app's record, and
-its tunnel with it; the app is deployed again from the artifact above.
+its tunnel with it; the app is deployed again from the artifact above. Without a Cloudflare
+connection, a quick tunnel gives the app a random address that changes whenever it restarts.
diff --git a/internal/server/testdata/dashboard-list-error.html b/internal/server/testdata/dashboard-list-error.html
index d3645f8..c9e7bc9 100644
--- a/internal/server/testdata/dashboard-list-error.html
+++ b/internal/server/testdata/dashboard-list-error.html
@@ -28,7 +28,8 @@
Cluster
k3d-shelf-dev https://127.0.0.1:6445
Apps answer at
<app>-dev.example.com unless they have a domain of their own
Internet
-
each app through its own Cloudflare tunnel, once it has a Cloudflare connection
+
each app through its own Cloudflare tunnel, once it has a Cloudflare connection;
+without one, through a quick tunnel at a temporary address
<app>.dev.local unless they have a domain of their own
Internet
dev.local is a reserved name, so no address can point here; an app
-reaches the internet only with a domain of its own and a Cloudflare connection
+reaches the internet through a quick tunnel at a temporary address, or with a domain of its own
+and a Cloudflare connection
diff --git a/internal/server/testdata/dashboard.html b/internal/server/testdata/dashboard.html
index f942920..0f4623f 100644
--- a/internal/server/testdata/dashboard.html
+++ b/internal/server/testdata/dashboard.html
@@ -28,7 +28,8 @@
Cluster
k3d-shelf-dev https://127.0.0.1:6445
Apps answer at
<app>-dev.example.com unless they have a domain of their own
Internet
-
each app through its own Cloudflare tunnel, once it has a Cloudflare connection
+
each app through its own Cloudflare tunnel, once it has a Cloudflare connection;
+without one, through a quick tunnel at a temporary address
Connections are defined once, on the connections page, and chosen
here. With a registry connection, the form offers the deploy artifacts and tags of its user.
With a Cloudflare connection, the app gets a tunnel of its own in that account and a DNS record
-in its zone.
+in its zone. Without one, it gets a quick tunnel: a random address that needs no account and no
+domain, but changes whenever the tunnel restarts, and is meant for trying things out.