13 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. App navigation includes it. A page the ExApp renders itself inserts the same fragment. The page then calls exappDialog.message, exappDialog.confirm, or exappDialog.prompt and waits for the user's choice.
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
}
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.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
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.
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
}
OCSClient performs AppAPI-authenticated OCS requests with format=json.
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.