7.3.1.1. go-nc-exapp
go-nc-exapp ist die gemeinsame Go-Library für Nextcloud-ExApp, Glossar, öffnet in neuem Tab
-Services: AppAPI Credentials, Glossar, öffnet in neuem Tab
, authentifizierte OCS, Glossar, öffnet in neuem Tab
-Aufrufe, ExApp Preferences, Glossar, öffnet in neuem Tab
und Notifications, Glossar, öffnet in neuem Tab
pro User, Users and Groups, Glossar, öffnet in neuem Tab
-Reads, optionaler Required Groups, Glossar, öffnet in neuem Tab
-Access Gate, Glossar, öffnet in neuem Tab
, optionale App Navigation, Glossar, öffnet in neuem Tab
-Shell, Dialog, Glossar, öffnet in neuem Tab
und Phrases in der UI-Sprache der Seite.
Import-Pfad: gitea.neitzel.de/konrad/go-nc-exapp, Package-Name: gonexapp. Repo: gitea.neitzel.de/konrad/go-nc-exapp.
Diese Seite gehört zu 7.3.1. Nextcloud ExApps. Englische Fachbegriffe sind im Glossar erklärt.
go get gitea.neitzel.de/konrad/go-nc-exapp
Der Modulpfad ist die Library-Identität auf Gitea. Klonen und Fetch laufen über SSH auf Port 2222 (ssh://git@gitea.neitzel.de:2222/konrad/go-nc-exapp.git), nicht über den HTTPS-Pfad, den der Modulname nahelegt. Private Module brauchen GOPRIVATE=gitea.neitzel.de, damit go get nicht den öffentlichen Proxy trifft.
import gonexapp "gitea.neitzel.de/konrad/go-nc-exapp"
flowchart LR HaRP -->|"AUTHORIZATION-APP-API"| UserFromRequest UserFromRequest --> AccessGate AccessGate -->|"Allowed"| Handler Handler -->|"AuthHeaders / WithUser"| Nextcloud
Die Library deckt AppAPI, Glossar, öffnet in neuem Tab -seitige Aufrufe und ausgewählte UI-Bausteine ab. Bewusst außerhalb:
- Lifecycle-HTTP-Routen (
/heartbeat,/enabled,/init) – der Access Gate überspringt sie, implementiert sie aber nicht - HaRP, Glossar, öffnet in neuem Tab
-Listen,
serve()und Unix-Socket-Bootstrap - Registrierung von Top-Menu, Script und Iframe in Nextcloud
- WebDAV und Dateispeicher → 7.3.1.2. go-nc-files
- User Tokens, Glossar, öffnet in neuem Tab ExApp → Microservice, Glossar, öffnet in neuem Tab → 7.3.2. go-usertoken
- Fan-out-Notifications (
SendToGroup,SendToAdmins) - ein Library-Default-Admin für Directory-OCS (Aufrufer setzen den Admin mit
WithUser)
Credentials bündelt, was ein ExApp braucht, um Nextcloud als ein User anzusprechen: BaseURL, AppID, AppVersion, AAVersion, AppSecret, UserID. Die Werte kommen typischerweise aus der Deploy-Umgebung, die HaRP injiziert. Ein trailing Slash an BaseURL ist erlaubt; Aufrufer in der Library entfernen ihn beim URL-Bau. Leere Felder erzeugen keine Konstruktorfehler – die Nextcloud-Antwort scheitert später.
AuthHeaders setzt die AppAPI-Header für ausgehende Requests: AA-VERSION, EX-APP-ID, EX-APP-VERSION, AUTHORIZATION-APP-API, OCS-APIRequest. AUTHORIZATION-APP-API ist Base64 von UserID:AppSecret. OCSClient und go-nc-files rufen das intern; für eigene HTTP-Calls reicht req.Header = cred.AuthHeaders().
WithUser liefert eine Kopie mit anderem UserID. Das Original bleibt unverändert. Braucht ein Directory-Call einen Admin, setzt der Aufrufer WithUser am Call-Site – die Library wählt keinen Admin.
Auf eingehenden, von HaRP proxied Requests liest UserFromRequest den Requesting User, Glossar, öffnet in neuem Tab
aus AUTHORIZATION-APP-API. Fehlender Header, ungültiges Base64 oder fehlende User-Id vor dem Doppelpunkt → Fehler. Der Access Gate ruft das vor dem Gruppen-Check. Die Funktion vergleicht das Secret nicht; die ExApp muss den Secret-Check auf User-Routen selbst machen.
OCSClient macht AppAPI-authentifizierte OCS-Requests und verlangt JSON-Bodies. Jede URL bekommt format=json. URL baut die Adresse unter /ocs/v2.php/…; Call führt Methode, Pfad und optionalen Body aus und prüft nur, dass die Antwort gültiges JSON ist – kein festes OCS-Schema. nil Client → http.DefaultClient. Preferences, Notifications und Groups bauen darauf auf. Nicht-2xx und Transportfehler kommen als Fehler inkl. Status zurück.
NewAppAPIPreferences(cred, appID, key) liest und schreibt eine String-Preference für den Requesting User. App-Id und Key wählt der Aufrufer; die Library reserviert keine Produkt-Keys. Get liefert bei fehlendem Key leeren String und nil Fehler. Set speichert non-sensitive. Passt zu einem DefaultPathStore in go-nc-files, wenn der Saved-Default-Pfad in Preferences liegt.
NewAppAPINotifications(cred) erzeugt eine Bell-Notification für einen Recipient, Glossar, öffnet in neuem Tab
. Notification hat Pflichtfeld Subject; optional Message, Link, SubjectParams, MessageParams. Send geht an Cred.UserID, SendTo an einen anderen User (Auth über WithUser). Kein Fan-out an Gruppen oder Admins. AppAPI akzeptiert keine Actions und kein Custom-Icon.
NewGroups(cred) wrappt Provisioning-OCS ohne Suche und ohne Paging:
| Methode | Was | Auth |
|---|---|---|
UserGroups(userID) |
Gruppen-Ids eines Users | als userID |
GroupMembers(groupID) |
User-Ids in der Gruppe | als Cred-User (Admin/Subadmin) |
ListGroups() |
Gruppen-Ids der Instanz | als Cred-User (Admin/Subadmin) |
Distinct von Required Groups: das ist Directory, nicht ACL.
Der Access Gate lässt Requests nur durch, wenn der Requesting User in einer der Required Groups ist. Leere Gruppenliste → Gate aus. AppAPI erzwingt das nicht; die ExApp schon.
Deploy-Env:
REQUIRED_GROUPS(EnvRequiredGroups) – komma-separiert, any-ofREQUIRED_GROUPS_CACHE_SECONDS(EnvRequiredGroupsCacheSeconds) – Default 60;"0"schaltet den Cache aus
ResolveRequiredGroups: Variable unset → Code-Default; gesetzt (auch leer) ersetzt den Default. ParseCacheSeconds mappt die Cache-Env auf eine Duration.
AccessGate{Cred, Groups, CacheTTL}.Wrap(handler) prüft vor next. Ergebnisse von Check:
| Ergebnis | HTTP |
|---|---|
CheckAllowed |
weiter zu next |
CheckUnauthorized |
401 |
CheckUnavailable |
503 |
CheckDenied |
HTML mit 200 + frame-ancestors 'self' (Accept text/html), sonst 403 |
200 + CSP halten AppAPI davon ab, das Iframe zu blanken. Positive Membership wird für CacheTTL gecacht; Denials nicht. Skip-Pfade: /heartbeat, /enabled, /init, alles unter /js/, plus ExtraSkipPaths (Top-Menu-Scripts unter /js/ müssen für Nicht-Mitglieder ladbar bleiben).
TopMenuAdminRequired(env, default) liefert "0" oder "1" für AppAPI’s Top-Menu-Feld adminRequired (Top Menu Visibility, Glossar, öffnet in neuem Tab
). Env-Name: TOP_MENU_ADMIN_REQUIRED (EnvTopMenuAdminRequired), in info.xml deklarieren. Default der Library: DefaultTopMenuAdminRequired (true → nur Admins). Nur "0" und "1" gelten; alles andere inkl. leer → Default. Die Library registriert das Menü nicht. Unabhängig von access_level in info.xml und von Required Groups. Nach Env-Änderung: Container neu, dann ExApp disable/enable (oder Update), damit PUT /enabled?enabled=1 erneut läuft.
Optionale Files-artige Shell. AppNavigation braucht Items, Page, DefaultID; optional Header, MissingMessage, Title, SelectKey (Default item), DisableTheme. Handler() auf die Page-Route mounten ersetzt die eigene Page; ohne Mount bleibt die ExApp-Page unverändert.
Items liefert den Baum (Item: ID, Label, optionale Children, optionales Icon, optionale Phrase). Label bleibt die englische Quelle. Phrase, Cred, Phrases und MissingPhrase sind unter UI-Sprache und Phrases beschrieben. Page liefert HTML-Body und ob die Id bekannt ist. Fehlende Id → DefaultID, MissingMessage, korrigierte Query auf data-address. Andere Query-Parameter (z. B. Visit-Folder) bleiben erhalten. Unter 1024px bleibt der Baum zugeklappt, bis der User ihn öffnet. Zero-Value von DisableTheme lädt Nextcloud-Theme und Hintergrund; Dialog ist eingebaut; Response setzt frame-ancestors 'self'.
NextcloudIcons sind Pfade zu Core-SVGs unter /core/img/ (Folder, File, Home, Actions, …). Die Library liefert die Dateien nicht mit. Item.Icon setzt man auf einen same-origin Image-URL oder auf ein Feld von NextcloudIcons (z. B. NextcloudIcons.Folder). Dark Mode invertiert über Nextclouds --background-invert-if-dark.
Eine Seite erscheint in der UI-Sprache des Requesting Users. Die Dokumentsprache (<html lang>) ist de oder en. AppNavigation ermittelt die Sprache einmal pro Seite und reicht das Ergebnis an seine Callbacks und den Dialog weiter. Der Aufrufer übergibt App navigation und Dialog keine Sprache.
Credentials.UILanguage(r) liest das Provisioning-OCS-Feld language (cloud/users/…) und fragt dabei als Requesting User an. Der Accept-Language-Header des Seiten-Requests wird bei dieser Abfrage mitgeschickt. Das Feld locale wird ignoriert. Welche Sprache in language steht, entscheidet Nextcloud in dieser Reihenfolge: erzwungene Sprache, gespeicherte persönliche Sprache, Browsersprache aus dieser Abfrage, Instanz-Default, Englisch. Hat die Library eine Sprache für genau diesen Code, gilt sie. Sonst gilt der Teil vor _, falls die Library diese Sprache hat. Sonst gilt Englisch.
| Code | Sprache der Seite |
|---|---|
de, de_DE |
Deutsch (de) |
en, en_GB |
Englisch (en) |
| anderer Code | Englisch (en) |
Fehlt der User, ist BaseURL leer oder schlägt die Abfrage fehl, wird die Seite auf Englisch gerendert. App navigation fragt einmal ab, hängt das Ergebnis an den Request und reicht diesen an Items, Page und den Dialog weiter. Ein weiterer UILanguage-Aufruf mit diesem Request nutzt das gespeicherte Ergebnis. Bleibt Cred auf dem Zero-Value, bleibt die Seite englisch.
Die Phrases ihrer Seiten und Navigationspunkte gehören der ExApp. Das Default-Set besteht aus i18n/en.json und i18n/de.json im Projekt-Root; beide werden eingebettet und mit PhrasesFromFS geladen. Im eingebetteten FS müssen sie unter genau diesen Pfaden liegen. Jede Datei ist ein JSON-Objekt, das jeder Id einen Text zuordnet. Ein Modul kann ein eigenes i18n-Verzeichnis neben sich einbetten und mit Merge hinzufügen. Kommt eine Id mehrfach vor, gewinnt der Text aus dem später übergebenen Set. Merge kombiniert nur die Sets, die der Aufrufer übergibt; nichts durchsucht den Quellbaum. Englisch ist das vollständige Set. Jede Phrase hat einen Text pro Sprache, Pluralformen gibt es nicht. Eine Id, die nur auf Deutsch existiert, landet nicht in der Map des Scripts.
{
"nav.home": "Home",
"page.missing": "Zone {name} is missing."
}
Die deutsche Datei verwendet dieselben Ids und dieselben Platzhalter. Die Stellung im Satz darf abweichen:
{
"nav.home": "Start",
"page.missing": "{name} fehlt."
}
Ids sind stabile Namen mit Punkten, nicht der englische Satz. Eine unbekannte Id wird als Id angezeigt. Fehlt der deutsche Text oder ist er leer, erscheint der englische.
Ein Platzhalter hat die Form {name}. Ein Platzhalter ohne Wert bleibt als {name} sichtbar. Der Wert ist Klartext; enthält er selbst {…}, wird das nicht weiter ersetzt. Sentence liefert den fertigen Satz als Klartext. Wer ihn in HTML schreibt, muss ihn in Go escapen. Das Script setzt Textinhalt, placeholder, title und aria-label als reinen Text; Phrase-Texte und Platzhalterwerte werden nie als HTML geparst. Bei ungültigem JSON in data-phrase-holes bleiben die Platzhalter stehen.
Die Bedienelemente der Library (Chrome) haben ein eigenes Set: Dialog-Buttons, Navigation öffnen und schließen, Einklappen. Script enthält nur das Set der ExApp. exappPhrase("dialog.cancel") liefert deshalb nur die Id dialog.cancel, nicht „Abbrechen“.
| Chrome | Englisch | Deutsch |
|---|---|---|
OK (dialog.ok) |
OK | OK |
Cancel (dialog.cancel) |
Cancel | Abbrechen |
Navigation öffnen (nav.open) |
Open navigation | Navigation öffnen |
Navigation schließen (nav.close) |
Close navigation | Navigation schließen |
Einklappen (nav.fold) |
Fold {label} |
{label} einklappen |
Nach dem Laden bildet das Script das Label des Einklappen-Buttons aus dem sichtbaren Namen des Eintrags und dem Muster in data-fold. Ein umbenannter Agree-Button zeigt genau den Text, den der Aufrufer übergibt; die Library übersetzt ihn nicht. Eine Seite, die die ExApp selbst rendert, holt den Dialog in der UI-Sprache mit Credentials.DialogHTML(r). DialogHTML() bleibt englisch.
Phrases.Script(lang) definiert exappPhrase(id, holes) und gehört in den Head. FillScript() gehört ans Ende des Body und ersetzt nach dem Laden die englische Quelle, die im HTML stehen bleibt. App navigation fügt beides selbst ein: Phrases füllt die Map, Cred bestimmt lang. Ohne Phrases ist die Map leer. Ein Element mit Phrase-Id zeigt dann die Id, ein Element ohne Attribut behält die englische Quelle. Eine selbst gerenderte Seite fügt beides selbst ein und holt lang mit UILanguage(r).
| Attribut | Ersetzt |
|---|---|
data-phrase |
Textinhalt |
data-phrase-placeholder |
placeholder |
data-phrase-title |
title |
data-phrase-aria-label |
aria-label |
data-phrase-holes |
Platzhalterwerte als JSON |
Item.Phrase nennt die Phrase für das Navigationslabel. Label bleibt die englische Quelle; ist Phrase leer, bleibt Label stehen. MissingPhrase nennt die Phrase für MissingMessage. Einen Fehler, den die Seite anzeigt, liefert der Service als fertigen Satz aus Sentence(lang, id, holes), nicht als Id. Eine Logzeile, die die Seite nicht anzeigt, ist keine Phrase und bleibt englisch.
UILanguage gibt keinen Fehler zurück. PhrasesFromFS meldet Fehler beim Lesen der beiden Dateien. ParsePhrases meldet JSON-Syntaxfehler und Werte, die sich nicht als String-Map einlesen lassen, etwa Zahlen oder Arrays. Das erwartete Format bleibt ein JSON-Objekt mit String-Werten; der Parser prüft es aber nicht vollständig: Leere Eingaben, reine Leerzeichen und JSON null werden als leeres Set akzeptiert. Ein null als Wert einer Id wird als leerer Text behandelt.
Modal für Message, Confirm und Prompt. App navigation bindet ihn ein; eigene Pages fügen DialogHTML() einmal ein. Die Buttons folgen der UI-Sprache (siehe UI-Sprache und Phrases): OK bleibt OK, Cancel heißt auf Deutsch Abbrechen, ein umbenannter Agree-Button zeigt genau den übergebenen Text. DialogHTML() bleibt englisch; eine selbst gerenderte Seite nimmt Credentials.DialogHTML(r). Aufruf aus JS: exappDialog.message, .confirm, .prompt – Promise wartet auf die Wahl; kein Server-Roundtrip. Message: heading, text, severity (info/warning/error), kein Cancel. Confirm: optional agree, destructive → true/false. Prompt: optional value, agree → getrimmter String oder null; Agree bleibt disabled, solange das Feld leer ist. Aufrufe sind gequeued.
cred := gonexapp.Credentials{
BaseURL: "https://cloud.example",
AppID: "myexapp",
AppVersion: "0.1.0",
AAVersion: "1.0.0",
AppSecret: os.Getenv("APP_SECRET"),
UserID: "alice",
}
req.Header = cred.AuthHeaders()
userID, err := gonexapp.UserFromRequest(r)
if err != nil {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
cred.UserID = userID
ocs := gonexapp.OCSClient{Cred: cred}
raw, err := ocs.Call(http.MethodGet, "cloud/capabilities", nil)
if err != nil {
return err
}
_ = raw
prefs := gonexapp.NewAppAPIPreferences(cred, "myexapp", "savedDefault")
value, err := prefs.Get()
if err != nil {
return err
}
if err := prefs.Set("Zones"); err != nil {
return err
}
_ = value
err := gonexapp.NewAppAPINotifications(cred).Send(gonexapp.Notification{
Subject: "Job finished",
Message: "The zone was updated.",
})
asAdmin := cred.WithUser(adminID)
members, err := gonexapp.NewGroups(asAdmin).GroupMembers("ops")
if err != nil {
return err
}
_ = members
groupsEnv, groupsSet := os.LookupEnv(gonexapp.EnvRequiredGroups)
groups := gonexapp.ResolveRequiredGroups(groupsEnv, groupsSet, nil)
ttl := gonexapp.ParseCacheSeconds(
os.Getenv(gonexapp.EnvRequiredGroupsCacheSeconds),
gonexapp.DefaultCacheSeconds,
)
handler = gonexapp.AccessGate{Cred: cred, Groups: groups, CacheTTL: ttl}.Wrap(handler)
Leere AccessGate{} lässt alles durch (keine Required Groups):
h := gonexapp.AccessGate{}.Wrap(inner)
adminRequired := gonexapp.TopMenuAdminRequired(
os.Getenv(gonexapp.EnvTopMenuAdminRequired),
gonexapp.DefaultTopMenuAdminRequired,
)
nav := gonexapp.AppNavigation{
DefaultID: "home",
Items: func(*http.Request) []gonexapp.Item {
return []gonexapp.Item{{
ID: "home", Label: "Home", Icon: gonexapp.NextcloudIcons.Home,
}}
},
Page: func(_ *http.Request, id string) (string, bool) {
if id != "home" {
return "", false
}
return "<p>Home</p>", true
},
}
http.Handle("/page", nav.Handler())
//go:embed i18n
var i18nFS embed.FS
phrases, err := gonexapp.PhrasesFromFS(i18nFS)
if err != nil {
return err
}
phrases = gonexapp.Merge(phrases, modulePhrases)
nav := gonexapp.AppNavigation{
Cred: cred,
Phrases: phrases,
DefaultID: "home",
MissingMessage: "That item is missing.",
MissingPhrase: "nav.missing",
Items: func(*http.Request) []gonexapp.Item {
return []gonexapp.Item{{
ID: "home", Label: "Home", Phrase: "nav.home",
}}
},
Page: func(r *http.Request, id string) (string, bool) {
if id != "home" {
return "", false
}
msg := phrases.Sentence(cred.UILanguage(r), "page.missing", map[string]string{
"name": "example.com",
})
return "<p>" + html.EscapeString(msg) + "</p>", true
},
}
Eine selbst gerenderte Seite setzt Script in den Head und FillScript ans Ende des Body. Anders als AppNavigation speichert ein direkter UILanguage(r)-Aufruf das Ergebnis nicht im Request. Das folgende Beispiel kann deshalb zwei OCS-Abfragen auslösen: eine für UILanguage(r) und eine für DialogHTML(r). Schlägt nur eine davon fehl, können Phrases und Dialog unterschiedliche Sprachen verwenden. Für eine gemeinsame Sprachauflösung pro Seite ist das oben gezeigte AppNavigation-Muster mit dessen Page-Callback vorgesehen:
lang := cred.UILanguage(r)
fmt.Fprint(w, phrases.Script(lang))
fmt.Fprint(w, cred.DialogHTML(r))
fmt.Fprint(w, `<p data-phrase="page.missing" data-phrase-holes='{"name":"example.com"}'>Zone {name} is missing.</p>`)
fmt.Fprint(w, gonexapp.FillScript())
fmt.Fprint(w, gonexapp.DialogHTML())
<script>
const ok = await exappDialog.confirm({
heading: "Delete",
text: "Delete this file?",
agree: "Delete",
destructive: true,
});
const name = await exappDialog.prompt({
heading: "Name",
text: "Folder name",
value: "Zones",
});
</script>