feat(urd): den anden dør — /urd kan installeres som sin egen app
Én instans, én database, ét login — og to ting, der kan installeres.
Et styresystem installerer ikke en URL, det installerer et MANIFEST, og en
installeret apps identitet er manifestets `id`. To manifester på samme
origin med forskellige id'er er to apps; to adresser, der deler ét manifest,
er én app med et bogmærke. Det er hele mekanismen.
/ → verdande, ᚹ, /manifest.webmanifest, id "/"
/urd → urd, ð, /urd.webmanifest, id "/urd"
Skallen serveres per dør frem for at blive rettet af JavaScript bagefter,
fordi iOS læser sidens <head> ved "Føj til hjemmeskærm" — og Safari leder
efter apple-touch-icon VED NAVN og har historisk ignoreret manifestets
ikoner helt. Et <head> rettet efter indlæsning er et <head>, der måske ikke
er det, iOS læste.
urds manifest bygges AF verdandes frem for at stå ved siden af det, så de
felter, de faktisk deler — farverne, visningstilstanden, sproget — kommer ét
sted fra og ikke kan drive fra hinanden. Seks nøgler ændres: id, start_url,
scope, de to navne og ikonerne. Et ikon i det byggede manifest, som urd
ikke har en fil til, stopper serveren frem for at gå igennem: symptomet
ville ellers være, at urds installationsprompt stille viste verdandes mærke.
`scope` skrives ud, selvom "/" er hvad specifikationen ville udlede af en
start_url på "/urd". En app, hvis scope ikke dækkede hele origin, ville åbne
sine egne links i en browserfane, første gang nogen navigerede ud af /urd —
og det er en regel, ingen skal behøve at huske, mens de læser koden.
## Ansigtet er en præference, ikke en port
`urdFace` holdes skarpt adskilt fra `notesOnly`, og det er den vigtigste
linje i ændringen:
notesOnly — serveren HAR ingen opgaveruter. En vagt: hent dem ikke, de
svarer 404.
urdFace — vinduet kom ind ad urd-døren. En præference: ruterne er der,
dataene er personens egne, kun navnet er et andet.
Slås de sammen, begynder urd-ansigtet at skjule data frem for pynt — en
notesbog ville holde op med at vise sine opgaver, fordi nogen valgte en
anden indgang, og så er det den separate instans i forklædning. En prøve
påstår det modsatte direkte: urd-vinduet får stadig 200 på /api/v1/tasks.
Ansigtet ligger i sessionStorage og ikke localStorage, og det er dét, der
lader de to apps være to apps: de deler origin og dermed localStorage,
cookies og service worker. sessionStorage er per vindue, og en installeret
PWA er sit eget vindue. Det overlever en genindlæsning, hvilket det skal —
efter første navigation står adressen på /noter, og ingen går gennem /urd
igen.
## Undervejs
contentTypeFor slog op på det eksakte navn "manifest.webmanifest", så den
anden dørs manifest blev serveret som HTML i fire minutter. Intet ville have
meldt det: et manifest med forkert type ignoreres af browseren uden fejl, og
det eneste symptom er en installationsknap, der ikke dukker op. Læser nu
endelsen.
Og drift-kontrollen mod app.html dækkede kun udgavens to ankre, ikke dørens
fem — hvilket er grunden til, at dørens fikstur manglede to <link>-linjer,
den rigtige fil har. Fanget alene fordi applyRebrands nægter et anker, den
ikke kan finde. Kontrollen dækker nu begge sæt.
Plantet: et manifest uden `id` giver "the urd manifest has id = <nil>, want
/urd" — altså den værdi, hele designet hviler på.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
kristianwind
co-authored by
Claude Opus 5
Claude Opus 5
parent
ff988d26bb
commit
9199709aa5
@@ -86,6 +86,12 @@ type Server struct {
|
||||
// Icon paths this edition serves from another file. Empty in the full edition.
|
||||
assets map[string]string
|
||||
|
||||
// The second door: /urd and its own web manifest. Built on every instance,
|
||||
// whatever the edition, because it is how the notes face is installed as its
|
||||
// own app rather than a property of the instance. See shell.go.
|
||||
urdShell []byte
|
||||
urdManifest []byte
|
||||
|
||||
router chi.Router
|
||||
}
|
||||
|
||||
@@ -135,6 +141,18 @@ func New(cfg *config.Config, db *store.DB, log *slog.Logger, web fs.FS) *Server
|
||||
})
|
||||
}
|
||||
|
||||
// The second door, on every edition. A notes instance already calls itself urd
|
||||
// at the root; the door is still built there so the two addresses behave the
|
||||
// same, and so a single test does not have to know which edition it is in.
|
||||
if web != nil {
|
||||
urdShell, urdManifest, err := urdDoorAssets(web)
|
||||
if err != nil {
|
||||
log.Error("the urd door could not be built; /urd will not be its own app", "err", err)
|
||||
} else {
|
||||
s.urdShell, s.urdManifest = urdShell, urdManifest
|
||||
}
|
||||
}
|
||||
|
||||
if s.shell != nil {
|
||||
s.csp = contentSecurityPolicy(scriptHashesIn(s.shell))
|
||||
} else {
|
||||
@@ -797,6 +815,15 @@ func (s *Server) serveWeb(w http.ResponseWriter, r *http.Request) {
|
||||
name = "index.html"
|
||||
}
|
||||
|
||||
// The second door, before anything else touches the filesystem: /urd is not a
|
||||
// file, so the fallback below would hand back the other door's shell.
|
||||
if b := s.door(name); b != nil {
|
||||
w.Header().Set("Content-Type", contentTypeFor(name))
|
||||
w.Header().Set("Cache-Control", "no-cache")
|
||||
http.ServeContent(w, r, name, time.Time{}, bytes.NewReader(b))
|
||||
return
|
||||
}
|
||||
|
||||
// This edition's own icon, where it has one. Before the Open rather than after,
|
||||
// unlike the shell below: these are real files, so there is no fallback to get
|
||||
// in the way, and resolveNotesAssets has already checked each one exists.
|
||||
|
||||
+165
-1
@@ -2,8 +2,10 @@ package httpapi
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// The product name is in the built frontend as a literal in four places, because
|
||||
@@ -132,7 +134,12 @@ func (s *Server) renamed(name string) []byte {
|
||||
// is ignored by the browser without an error anywhere: the install prompt simply
|
||||
// does not appear.
|
||||
func contentTypeFor(name string) string {
|
||||
if name == "manifest.webmanifest" {
|
||||
// Any .webmanifest, not the one name — there are two of them now, and the
|
||||
// second one was served as HTML for about four minutes because this read
|
||||
// `name == "manifest.webmanifest"`. Nothing would have reported it: a manifest
|
||||
// with the wrong type is ignored silently, and the only symptom is an install
|
||||
// prompt that does not appear.
|
||||
if strings.HasSuffix(name, ".webmanifest") {
|
||||
return "application/manifest+json"
|
||||
}
|
||||
return "text/html; charset=utf-8"
|
||||
@@ -175,3 +182,160 @@ func resolveNotesAssets(web fs.FS, missing func(name, alias string)) map[string]
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// The second door.
|
||||
//
|
||||
// One instance, one database, one login — and two things you can install. urd is
|
||||
// reached at /urd, which serves the same single-page app under its own identity:
|
||||
// its own title, its own mark, and its own web manifest.
|
||||
//
|
||||
// The manifest is the part that matters and the part that is easy to get wrong.
|
||||
// An operating system does not install a URL, it installs a *manifest*, and the
|
||||
// identity of an installed app is the manifest's `id`. Two manifests on one origin
|
||||
// with different ids are two installable apps; two URLs sharing one manifest are
|
||||
// one app with a bookmark.
|
||||
//
|
||||
// And the shell has to be served per door rather than patched by JavaScript,
|
||||
// because iOS reads the page's <head> when somebody taps Add to Home Screen —
|
||||
// Safari looks for apple-touch-icon BY NAME and has historically ignored the
|
||||
// manifest's icons entirely. A head rewritten after load is a head that may or may
|
||||
// not be the one iOS read.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
// urdDoorPath is the entry point, and it is also the manifest's id. One constant,
|
||||
// because those two being the same string is the whole mechanism.
|
||||
const urdDoorPath = "/urd"
|
||||
|
||||
// urdShellRebrands rewrites the four things in the shell's <head> that decide what
|
||||
// this door is: what the tab says, what a crawler reads, which manifest the browser
|
||||
// fetches, and which icons it finds without the manifest.
|
||||
//
|
||||
// Note what is NOT in here, for the same reason as in shellRebrands above: the
|
||||
// three `verdande:` localStorage keys in the inline theme script. They are storage
|
||||
// rather than a name, the rest of the app reads them, and — now more than before —
|
||||
// the two doors share an origin and therefore share that storage. Renaming them
|
||||
// here would give the two apps different themes by accident and lose everybody's
|
||||
// setting on the way.
|
||||
func urdShellRebrands() []rebrand {
|
||||
return []rebrand{
|
||||
{"<title>verdande</title>", "<title>urd</title>"},
|
||||
{
|
||||
`<meta name="description" content="verdande — opgaver og projekter, delt." />`,
|
||||
`<meta name="description" content="` + notesShellDescription + `" />`,
|
||||
},
|
||||
{
|
||||
`<link rel="manifest" href="/manifest.webmanifest" />`,
|
||||
`<link rel="manifest" href="/urd.webmanifest" />`,
|
||||
},
|
||||
{
|
||||
`<link rel="icon" href="/icon.svg" type="image/svg+xml" />`,
|
||||
`<link rel="icon" href="/urd-icon.svg" type="image/svg+xml" />`,
|
||||
},
|
||||
{
|
||||
`<link rel="apple-touch-icon" href="/apple-touch-icon.png" />`,
|
||||
`<link rel="apple-touch-icon" href="/urd-apple-touch-icon.png" />`,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// urdManifest builds the second door's manifest from the one the frontend build
|
||||
// produced, rather than writing a second one by hand.
|
||||
//
|
||||
// Transformed as JSON rather than by string replacement, which the shell above
|
||||
// does: a manifest needs keys the built one does not have — `id` and `start_url`
|
||||
// — so there is nothing to anchor a replacement on, and a hand-written copy would
|
||||
// drift on the fields the two genuinely share (the colours, the display mode, the
|
||||
// language).
|
||||
//
|
||||
// `id` is what makes this a second app rather than a bookmark. `scope` is spelled
|
||||
// out even though "/" is what the spec would default to from a start_url of
|
||||
// "/urd": an app whose scope did not cover the whole origin would open its own
|
||||
// links in a browser tab the first time somebody navigated out of /urd, and that
|
||||
// is a rule nobody should have to remember while reading this.
|
||||
func urdManifest(raw []byte) ([]byte, error) {
|
||||
var m map[string]any
|
||||
if err := json.Unmarshal(raw, &m); err != nil {
|
||||
return nil, fmt.Errorf("the built manifest is not JSON: %w", err)
|
||||
}
|
||||
|
||||
m["id"] = urdDoorPath
|
||||
m["start_url"] = urdDoorPath
|
||||
m["scope"] = "/"
|
||||
m["name"] = "urd"
|
||||
m["short_name"] = "urd"
|
||||
m["description"] = notesManifestDescription
|
||||
|
||||
icons, ok := m["icons"].([]any)
|
||||
if !ok || len(icons) == 0 {
|
||||
return nil, fmt.Errorf("the built manifest has no icons to rewrite")
|
||||
}
|
||||
for i, entry := range icons {
|
||||
icon, ok := entry.(map[string]any)
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("icon %d is not an object", i)
|
||||
}
|
||||
src, _ := icon["src"].(string)
|
||||
// Every icon must be one this door has a file for. Refusing an unknown one
|
||||
// is the point: an icon added to the manifest and not to this map would
|
||||
// otherwise leave urd's install prompt showing Verdande's mark, which is
|
||||
// cosmetic enough that nobody files it.
|
||||
swapped, ok := map[string]string{
|
||||
"/icon.svg": "/urd-icon.svg",
|
||||
"/icon-192.png": "/urd-icon-192.png",
|
||||
"/icon-512.png": "/urd-icon-512.png",
|
||||
}[src]
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("icon %d is %q, which urd has no file for", i, src)
|
||||
}
|
||||
icon["src"] = swapped
|
||||
}
|
||||
|
||||
out, err := json.MarshalIndent(m, "", " ")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return append(out, '\n'), nil
|
||||
}
|
||||
|
||||
// urdDoorAssets builds the second door from the files the frontend build produced.
|
||||
//
|
||||
// Both or neither, and loudly: a door whose shell points at /urd.webmanifest while
|
||||
// that manifest is not being served is an install prompt that silently falls back
|
||||
// to the other app's identity.
|
||||
func urdDoorAssets(web fs.FS) (shell, manifest []byte, err error) {
|
||||
raw, err := fs.ReadFile(web, "index.html")
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("index.html: %w", err)
|
||||
}
|
||||
shell, err = applyRebrands(raw, urdShellRebrands())
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("index.html: %w", err)
|
||||
}
|
||||
|
||||
raw, err = fs.ReadFile(web, "manifest.webmanifest")
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("manifest.webmanifest: %w", err)
|
||||
}
|
||||
manifest, err = urdManifest(raw)
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("manifest.webmanifest: %w", err)
|
||||
}
|
||||
return shell, manifest, nil
|
||||
}
|
||||
|
||||
// door returns the bytes for the second door's two paths, or nil.
|
||||
//
|
||||
// Keyed on the requested path rather than on the resolved file, unlike `renamed`
|
||||
// below: /urd is not a file and never will be, so it has to be answered before the
|
||||
// fallback to index.html gets to it — which would serve the other door's shell
|
||||
// under this door's address, with no error anywhere.
|
||||
func (s *Server) door(name string) []byte {
|
||||
switch name {
|
||||
case "urd":
|
||||
return s.urdShell
|
||||
case "urd.webmanifest":
|
||||
return s.urdManifest
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"io/fs"
|
||||
"log/slog"
|
||||
@@ -45,6 +46,8 @@ const builtShell = `<!doctype html>
|
||||
<head>
|
||||
<meta name="description" content="verdande — opgaver og projekter, delt." />
|
||||
<link rel="manifest" href="/manifest.webmanifest" />
|
||||
<link rel="icon" href="/icon.svg" type="image/svg+xml" />
|
||||
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
|
||||
<title>verdande</title>
|
||||
<script>
|
||||
try {
|
||||
@@ -62,7 +65,17 @@ const builtManifest = `{
|
||||
"name": "verdande",
|
||||
"short_name": "verdande",
|
||||
"description": "Opgaver og projekter, delt.",
|
||||
"start_url": "/"
|
||||
"start_url": "/",
|
||||
"display": "standalone",
|
||||
"background_color": "#111312",
|
||||
"theme_color": "#111312",
|
||||
"lang": "da",
|
||||
"icons": [
|
||||
{ "src": "/icon.svg", "sizes": "any", "type": "image/svg+xml", "purpose": "any" },
|
||||
{ "src": "/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
|
||||
{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
|
||||
{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
|
||||
]
|
||||
}
|
||||
`
|
||||
|
||||
@@ -194,10 +207,19 @@ func TestAppHTMLStillCarriesTheAnchors(t *testing.T) {
|
||||
}
|
||||
src := string(raw)
|
||||
|
||||
for _, pair := range shellRebrands("urd", "d") {
|
||||
if n := strings.Count(src, pair.old); n != 1 {
|
||||
t.Errorf("web/src/app.html contains %d occurrences of the anchor %q, want exactly 1 — "+
|
||||
"the notes edition renames the shell by replacing it", n, pair.old)
|
||||
// Both sets: the edition's rename and the second door's. The door was added
|
||||
// after this test and its anchors were NOT covered, which is how its fixture
|
||||
// came to be missing two <link> lines the real file has — caught only because
|
||||
// applyRebrands refuses an anchor it cannot find.
|
||||
for what, pairs := range map[string][]rebrand{
|
||||
"the notes edition's rename": shellRebrands("urd", "d"),
|
||||
"the urd door": urdShellRebrands(),
|
||||
} {
|
||||
for _, pair := range pairs {
|
||||
if n := strings.Count(src, pair.old); n != 1 {
|
||||
t.Errorf("web/src/app.html contains %d occurrences of the anchor %q, want exactly 1 — %s replaces it",
|
||||
n, pair.old, what)
|
||||
}
|
||||
}
|
||||
}
|
||||
// And the keys the rename must not touch, asserted here too: app.html is where
|
||||
@@ -206,7 +228,8 @@ func TestAppHTMLStillCarriesTheAnchors(t *testing.T) {
|
||||
if !strings.Contains(src, `localStorage.getItem('verdande:theme')`) {
|
||||
t.Error("web/src/app.html no longer reads verdande:theme; check that the app reads the same key")
|
||||
}
|
||||
t.Logf("app.html: %d bytes, %d anchors found", len(raw), len(shellRebrands("urd", "d")))
|
||||
t.Logf("app.html: %d bytes, %d edition anchors, %d door anchors",
|
||||
len(raw), len(shellRebrands("urd", "d")), len(urdShellRebrands()))
|
||||
}
|
||||
|
||||
// TestTheFullEditionServesTheBuiltFilesUnchanged is the control. Everything above
|
||||
@@ -314,3 +337,106 @@ func TestAMissingMarkIsReportedAndFallsBack(t *testing.T) {
|
||||
t.Error("one missing icon took the other three with it")
|
||||
}
|
||||
}
|
||||
|
||||
// TestTheUrdDoorIsItsOwnApp.
|
||||
//
|
||||
// An operating system does not install a URL, it installs a manifest, and the
|
||||
// identity of an installed app is that manifest's `id`. So this asserts the two
|
||||
// things that decide whether /urd becomes a second icon on a home screen or just a
|
||||
// bookmark into the first one — and it asserts them as named values, because an
|
||||
// empty manifest, verdande's manifest and urd's all parse as JSON.
|
||||
func TestTheUrdDoorIsItsOwnApp(t *testing.T) {
|
||||
srv := serverWithWeb(t, "full", webWithIcons())
|
||||
|
||||
if srv.door("urd") == nil || srv.door("urd.webmanifest") == nil {
|
||||
t.Fatal("the full edition does not serve the urd door; it is a second face, not an edition")
|
||||
}
|
||||
|
||||
shell := string(srv.door("urd"))
|
||||
for _, want := range []string{
|
||||
"<title>urd</title>",
|
||||
`<link rel="manifest" href="/urd.webmanifest" />`,
|
||||
// iOS reads this one by name and has historically ignored the manifest's
|
||||
// icons entirely, which is why the shell is served per door rather than
|
||||
// patched by script after load.
|
||||
`<link rel="apple-touch-icon" href="/urd-apple-touch-icon.png" />`,
|
||||
`<link rel="icon" href="/urd-icon.svg" type="image/svg+xml" />`,
|
||||
} {
|
||||
if !strings.Contains(shell, want) {
|
||||
t.Errorf("the urd door's shell does not contain %q", want)
|
||||
}
|
||||
}
|
||||
// The same trap as the edition shell: the two doors share an origin and
|
||||
// therefore share localStorage, so renaming a storage key here would give the
|
||||
// two apps different themes by accident.
|
||||
if !strings.Contains(shell, `localStorage.getItem('verdande:theme')`) {
|
||||
t.Error("the urd door's shell lost a storage key; the two doors share one origin and one localStorage")
|
||||
}
|
||||
|
||||
var m map[string]any
|
||||
if err := json.Unmarshal(srv.door("urd.webmanifest"), &m); err != nil {
|
||||
t.Fatalf("the urd manifest is not JSON: %v", err)
|
||||
}
|
||||
for key, want := range map[string]any{
|
||||
// id is the install identity. Without it, two manifests on one origin are
|
||||
// one app with two start urls.
|
||||
"id": "/urd",
|
||||
"start_url": "/urd",
|
||||
"scope": "/",
|
||||
"name": "urd",
|
||||
"short_name": "urd",
|
||||
} {
|
||||
if m[key] != want {
|
||||
t.Errorf("the urd manifest has %s = %v, want %v", key, m[key], want)
|
||||
}
|
||||
}
|
||||
// And the shared half, to prove it was transformed rather than written out: a
|
||||
// hand-written copy would drift on exactly these.
|
||||
var built map[string]any
|
||||
raw, _ := fs.ReadFile(webWithIcons(), "manifest.webmanifest")
|
||||
_ = json.Unmarshal(raw, &built)
|
||||
for _, key := range []string{"display", "background_color", "theme_color", "lang"} {
|
||||
if _, ok := built[key]; ok && m[key] != built[key] {
|
||||
t.Errorf("the urd manifest lost the built one's %s: %v vs %v", key, m[key], built[key])
|
||||
}
|
||||
}
|
||||
|
||||
icons, _ := m["icons"].([]any)
|
||||
if len(icons) == 0 {
|
||||
t.Fatal("the urd manifest has no icons")
|
||||
}
|
||||
for i, entry := range icons {
|
||||
src, _ := entry.(map[string]any)["src"].(string)
|
||||
if !strings.HasPrefix(src, "/urd-") {
|
||||
t.Errorf("icon %d is %q — the urd manifest points at verdande's mark", i, src)
|
||||
}
|
||||
}
|
||||
t.Logf("urd door: shell %d bytes, manifest %d bytes, %d icons", len(srv.door("urd")), len(srv.door("urd.webmanifest")), len(icons))
|
||||
}
|
||||
|
||||
// TestAnUnknownIconStopsTheUrdManifest is the direction that matters: an icon
|
||||
// added to the built manifest and not to urd's map would otherwise leave urd's
|
||||
// install prompt showing Verdande's mark, which nobody reports.
|
||||
func TestAnUnknownIconStopsTheUrdManifest(t *testing.T) {
|
||||
raw := []byte(`{"name":"verdande","icons":[{"src":"/icon-1024.png","sizes":"1024x1024"}]}`)
|
||||
if _, err := urdManifest(raw); err == nil {
|
||||
t.Error("urdManifest accepted an icon it has no file for")
|
||||
} else if !strings.Contains(err.Error(), "/icon-1024.png") {
|
||||
t.Errorf("the error does not name the icon: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestTheWebmanifestTypeCoversBothDoors. A manifest served as text/html is ignored
|
||||
// by the browser with no error anywhere; the only symptom is that the install
|
||||
// prompt does not appear. This read `name == "manifest.webmanifest"` when the
|
||||
// second door was added.
|
||||
func TestTheWebmanifestTypeCoversBothDoors(t *testing.T) {
|
||||
for _, name := range []string{"manifest.webmanifest", "urd.webmanifest"} {
|
||||
if got := contentTypeFor(name); got != "application/manifest+json" {
|
||||
t.Errorf("%s is served as %q", name, got)
|
||||
}
|
||||
}
|
||||
if got := contentTypeFor("index.html"); got != "text/html; charset=utf-8" {
|
||||
t.Errorf("index.html is served as %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user