16 KiB
API
Generated from the package comment and every exported declaration. Do not edit.
Regenerate with UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1.
Package gonexapp
Package gonexapp provides AppAPI credentials, OCS JSON calls, ExApp user preferences, Notifications, Users and Groups reads, an optional Required Groups Access Gate, an optional App navigation shell, and a Dialog for Nextcloud ExApp Services.
Constants
DefaultCacheSeconds
const DefaultCacheSeconds = 60
DefaultCacheSeconds is used when REQUIRED_GROUPS_CACHE_SECONDS is unset or invalid.
DefaultTopMenuAdminRequired
const DefaultTopMenuAdminRequired = true
DefaultTopMenuAdminRequired is used when TOP_MENU_ADMIN_REQUIRED is unset or invalid.
EnvRequiredGroups
const EnvRequiredGroups = "REQUIRED_GROUPS"
EnvRequiredGroups is the conventional deploy env name for Required Groups.
EnvRequiredGroupsCacheSeconds
const EnvRequiredGroupsCacheSeconds = "REQUIRED_GROUPS_CACHE_SECONDS"
EnvRequiredGroupsCacheSeconds is the conventional deploy env name for Access Gate cache TTL.
EnvTopMenuAdminRequired
const EnvTopMenuAdminRequired = "TOP_MENU_ADMIN_REQUIRED"
EnvTopMenuAdminRequired is the conventional deploy env name for Top Menu visibility. Declare it in the ExApp info.xml environment-variables section.
Variables
NextcloudIcons
var NextcloudIcons = nextcloudIcons{
Folder: "/core/img/filetypes/folder.svg",
FolderShared: "/core/img/filetypes/folder-shared.svg",
FolderPublic: "/core/img/filetypes/folder-public.svg",
FolderStarred: "/core/img/filetypes/folder-starred.svg",
FolderEncrypted: "/core/img/filetypes/folder-encrypted.svg",
File: "/core/img/filetypes/file.svg",
Text: "/core/img/filetypes/text.svg",
Image: "/core/img/filetypes/image.svg",
Audio: "/core/img/filetypes/audio.svg",
Video: "/core/img/filetypes/video.svg",
PDF: "/core/img/filetypes/application-pdf.svg",
Document: "/core/img/filetypes/x-office-document.svg",
Spreadsheet: "/core/img/filetypes/x-office-spreadsheet.svg",
Presentation: "/core/img/filetypes/x-office-presentation.svg",
Files: "/core/img/places/files.svg",
Home: "/core/img/places/home.svg",
Calendar: "/core/img/places/calendar.svg",
Contacts: "/core/img/places/contacts.svg",
Add: "/core/img/actions/add.svg",
Delete: "/core/img/actions/delete.svg",
Edit: "/core/img/actions/edit.svg",
Rename: "/core/img/actions/rename.svg",
Download: "/core/img/actions/download.svg",
Upload: "/core/img/actions/upload.svg",
Share: "/core/img/actions/share.svg",
Search: "/core/img/actions/search.svg",
Settings: "/core/img/actions/settings.svg",
Info: "/core/img/actions/info.svg",
History: "/core/img/actions/history.svg",
Password: "/core/img/actions/password.svg",
Confirm: "/core/img/actions/confirm.svg",
Close: "/core/img/actions/close.svg",
Star: "/core/img/actions/star.svg",
User: "/core/img/actions/user.svg",
Group: "/core/img/actions/group.svg",
Mail: "/core/img/actions/mail.svg",
Menu: "/core/img/actions/menu.svg",
External: "/core/img/actions/external.svg",
Filter: "/core/img/actions/filter.svg",
Recent: "/core/img/actions/recent.svg",
Tag: "/core/img/actions/tag.svg",
}
NextcloudIcons are SVG paths served by Nextcloud core under /core/img/. The library does not ship the files. Set Item.Icon to one of these. Dark mode inverts them with Nextcloud’s --background-invert-if-dark filter.
Functions
DialogHTML
func DialogHTML() template.HTML
DialogHTML is the Dialog markup and script for an ExApp page, in English. App navigation includes the same fragment in the UI language and does not take a language argument. A page the ExApp renders itself inserts this fragment, or Credentials.DialogHTML when that page has a request. The page then calls exappDialog.message, exappDialog.confirm, or exappDialog.prompt and waits for the user's choice.
FillScript
func FillScript() template.HTML
FillScript replaces English source after load and refreshes Fold from the visible item name. It does not parse Phrase text as HTML. App navigation includes it. A page the ExApp renders itself places Script in the head and FillScript at the end of the body.
ParseCacheSeconds
func ParseCacheSeconds(s string, defaultSec int) time.Duration
ParseCacheSeconds parses REQUIRED_GROUPS_CACHE_SECONDS. Unset or invalid → defaultSec seconds; "0" → no cache.
ParseRequiredGroups
func ParseRequiredGroups(s string) []string
ParseRequiredGroups splits a comma-separated Required Groups env value.
ResolveRequiredGroups
func ResolveRequiredGroups(envValue string, envSet bool, codeDefault []string) []string
ResolveRequiredGroups applies env override rules: unset uses codeDefault; set (including empty) replaces the default.
TopMenuAdminRequired
func TopMenuAdminRequired(envValue string, defaultAdminRequired bool) string
TopMenuAdminRequired returns "1" or "0" for the AppAPI top-menu OCS adminRequired field. Only "0" and "1" are accepted; any other value falls back to defaultAdminRequired. An empty envValue means unset and also uses defaultAdminRequired.
UserFromRequest
func UserFromRequest(r *http.Request) (string, error)
UserFromRequest reads the requesting user from AUTHORIZATION-APP-API on an inbound ExApp request. It returns an error when the header is missing, is not base64, or contains no user id before the colon.
Types
AccessGate
type AccessGate struct {
Cred Credentials
Groups []string
CacheTTL time.Duration // 0 disables cache
ExtraSkipPaths []string
Client *http.Client
OCS OCSClient
Now func() time.Time
// contains filtered or unexported fields
}
AccessGate enforces Required Groups for the Requesting user on ExApp HTTP traffic.
AccessGate.Check
func (g *AccessGate) Check(r *http.Request) CheckResult
Check reports whether r may proceed under Required Groups.
AccessGate.Wrap
func (g AccessGate) Wrap(next http.Handler) http.Handler
Wrap returns a handler that runs Check before next. CheckAllowed calls next. CheckUnauthorized writes 401. CheckUnavailable writes 503. CheckDenied writes English HTML with status 200 and frame-ancestors 'self' when the request accepts text/html, and 403 otherwise. An empty Groups list allows every request. Paths /heartbeat, /enabled, /init, and /js/ are skipped, plus ExtraSkipPaths.
AppAPINotifications
type AppAPINotifications struct {
Cred Credentials
Client *http.Client
OCS OCSClient
}
AppAPINotifications creates Notifications via AppAPI OCS.
NewAppAPINotifications
func NewAppAPINotifications(cred Credentials) AppAPINotifications
NewAppAPINotifications returns a sender using cred for AppAPI auth.
AppAPINotifications.Send
func (n AppAPINotifications) Send(notif Notification) error
Send creates a Notification for Cred.UserID. It returns an error when UserID or Subject is empty, or when the OCS call fails. AppAPI notification OCS accepts Subject, Message, Link, and rich-object parameters. It does not accept actions or a custom icon.
AppAPINotifications.SendTo
func (n AppAPINotifications) SendTo(userID string, notif Notification) error
SendTo creates a Notification for userID. The OCS call is authenticated as that user via WithUser. It returns an error when userID or Subject is empty, or when the OCS call fails.
AppAPIPreferences
type AppAPIPreferences struct {
Cred Credentials
AppID string
Key string
Client *http.Client
OCS OCSClient
}
AppAPIPreferences reads and writes one string ExApp preference for the requesting user.
NewAppAPIPreferences
func NewAppAPIPreferences(cred Credentials, appID, key string) AppAPIPreferences
NewAppAPIPreferences returns a preference store for appID and key using cred for auth.
AppAPIPreferences.Get
func (p AppAPIPreferences) Get() (string, error)
Get loads the configured preference key for the requesting user. A missing key returns an empty string and a nil error. It returns an error when the OCS call fails or the body cannot be decoded.
AppAPIPreferences.Set
func (p AppAPIPreferences) Set(value string) error
Set stores value for the configured preference key. The value is stored as non-sensitive. It returns an error when the OCS call fails.
AppNavigation
type AppNavigation struct {
Items func(*http.Request) []Item
Page func(*http.Request, string) (string, bool)
Header func(*http.Request) string
DefaultID string
MissingMessage string
SelectKey string
// Title is the document title. Empty means "App navigation".
Title string
// DisableTheme skips the Nextcloud theme stylesheets. The zero value
// loads the active theme.
DisableTheme bool
// Cred reads the UI language for this page from Nextcloud.
// The zero value leaves the page in English.
// The caller does not pass a language.
Cred Credentials
// Phrases is the ExApp's set. The page script receives it.
// Library chrome is not included. The zero value leaves the page in English.
Phrases Phrases
// MissingPhrase names the ExApp Phrase for MissingMessage.
MissingPhrase string
}
AppNavigation is the Files-style shell an ExApp mounts. Items, Page, and DefaultID are required. Header and MissingMessage are optional. SelectKey defaults to "item". Every other query parameter, including the Visit folder, is copied onto the corrected address. An ExApp that never calls Handler keeps its own page.
AppNavigation.Handler
func (n AppNavigation) Handler() http.Handler
Handler serves the shell. The selected item is the SelectKey query parameter. A missing item renders DefaultID, includes MissingMessage, and publishes the corrected query on data-address so the page can replace the address. Every parent starts expanded. Folding is client state for this document only.
CheckResult
type CheckResult int
CheckResult is the outcome of AccessGate.Check.
CheckAllowed
CheckDenied
CheckUnauthorized
CheckUnavailable
const (
// CheckAllowed means the request may proceed (or the gate is inactive / skipped).
CheckAllowed CheckResult = iota
// CheckDenied means the Requesting user is not in Required Groups.
CheckDenied
// CheckUnauthorized means no Requesting user could be read from the request.
CheckUnauthorized
// CheckUnavailable means group membership could not be determined (e.g. OCS error).
CheckUnavailable
)
Credentials
type Credentials struct {
BaseURL string
AppID string
AppVersion string
AAVersion string
AppSecret string
UserID string
}
Credentials are what an ExApp needs to call Nextcloud as one user. BaseURL is the Nextcloud instance URL. A trailing slash is tolerated by callers in this package and is removed when they build a URL. AppID, AppVersion, and AAVersion are sent as EX-APP-ID, EX-APP-VERSION, and AA-VERSION. AppSecret and UserID form the AUTHORIZATION-APP-API token.
Credentials.AuthHeaders
func (c Credentials) AuthHeaders() http.Header
AuthHeaders returns AppAPI headers for a request to Nextcloud. The set is AA-VERSION, EX-APP-ID, EX-APP-VERSION, AUTHORIZATION-APP-API, and OCS-APIRequest. AUTHORIZATION-APP-API is base64 of UserID, a colon, and AppSecret. The method does not return an error; empty fields are sent as empty.
Credentials.DialogHTML
func (c Credentials) DialogHTML(r *http.Request) template.HTML
DialogHTML is the Dialog fragment in the UI language of r. A missing Requesting user or a failed read uses English. The caller does not pass a language.
Credentials.UILanguage
func (c Credentials) UILanguage(r *http.Request) string
UILanguage is the language of the Phrases for this request, "en" or "de". It reads the Requesting user's language from the Provisioning OCS user record and forwards the request's Accept-Language on that read. The locale field is ignored. A more specific code uses the broader language when this Library provides that language. Any other code, a missing Requesting user, or a failed read is English, and the page still renders. A second call with the request returned from a page render reuses that result.
Credentials.WithUser
func (c Credentials) WithUser(userID string) Credentials
WithUser returns a copy whose UserID is userID. The receiver is not modified.
Groups
type Groups struct {
Cred Credentials
Client *http.Client
OCS OCSClient
}
Groups reads Users and Groups from Provisioning OCS.
NewGroups
func NewGroups(cred Credentials) Groups
NewGroups returns a directory reader using cred for AppAPI auth.
Groups.GroupMembers
func (g Groups) GroupMembers(groupID string) ([]string, error)
GroupMembers returns the user ids in groupID. The OCS call uses Cred as-is. Nextcloud requires that user to be an admin or a subadmin of the group. It returns an error when the OCS call fails or the body cannot be decoded. There is no search or paging.
Groups.ListGroups
func (g Groups) ListGroups() ([]string, error)
ListGroups returns instance group ids. The OCS call uses Cred as-is and needs an admin or subadmin. It returns an error when the OCS call fails or the body cannot be decoded. There is no search or paging.
Groups.UserGroups
func (g Groups) UserGroups(userID string) ([]string, error)
UserGroups returns the Nextcloud group ids of userID. The OCS call is authenticated as userID. It returns an error when the OCS call fails or the body cannot be decoded.
Item
type Item struct {
ID string
Label string
Icon string
Phrase string
Children []Item
}
Item is one App navigation entry. The ExApp chooses the ids and labels. Children may nest. The shell does not interpret the ids. Icon is an optional same-origin image URL. NextcloudIcons names the core SVGs. Phrase names the ExApp Phrase for Label. The English label stays in the page until the script replaces it. Empty leaves the label as written.
Notification
type Notification struct {
Subject string
Message string
Link string
SubjectParams map[string]any
MessageParams map[string]any
}
Notification is one Nextcloud bell for a single Recipient.
OCSClient
type OCSClient struct {
Cred Credentials
Client *http.Client
Header http.Header
}
OCSClient performs AppAPI-authenticated OCS requests with format=json. Header is copied onto the outbound request after the AppAPI auth headers. The UI language read uses it to forward Accept-Language.
OCSClient.Call
func (c OCSClient) Call(method, path string, body []byte) ([]byte, error)
Call performs method against path with an optional JSON body and returns the response body after verifying it is valid JSON. Non-2xx responses return an error including the status.
OCSClient.URL
func (c OCSClient) URL(path string) string
URL builds an OCS URL under /ocs/v2.php with format=json.
Phrases
type Phrases struct {
// contains filtered or unexported fields
}
Phrases is one ExApp's merged Phrase set. English is the complete set. A module set is merged with Merge; a repeated id uses the set added later. The page script receives this set. Library chrome is not included.
Merge
func Merge(sets ...Phrases) Phrases
Merge returns the sets combined in order. A repeated id uses the text from the set added later.
ParsePhrases
func ParsePhrases(en, de []byte) (Phrases, error)
ParsePhrases reads an English object and a German object.
PhrasesFromFS
func PhrasesFromFS(fsys fs.FS) (Phrases, error)
PhrasesFromFS reads i18n/en.json and i18n/de.json. Each file is one JSON object of id → text.
Phrases.Script
func (p Phrases) Script(lang string) template.HTML
Script defines exappPhrase for the page, from this set only.
Phrases.Sentence
func (p Phrases) Sentence(lang, id string, holes map[string]string) string
Sentence is the finished text for lang. A missing text for that language uses the English text. An id missing from English is the id. A hole with no value stays visible as {name}. The result is plain text; the caller escapes it when writing HTML.