Help us shape the future of Go! Take the 2026 Go Developer Survey

admin

package
v0.15.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 22, 2026 License: AGPL-3.0 Imports: 65 Imported by: 0

Documentation

Overview

Package admin serves the core admin screens: dashboard widgets, users, roles, general and mail settings, system health and jobs, API keys, the audit viewer and the global admin search. It also publishes the mailer service (mailer.ServiceName) and the REST operations for those resources.

Index

Constants

View Source 
const (
	SettingBackupScheduleHours  = "backup.schedule_hours"
	SettingBackupRetain         = "backup.retain"
	SettingBackupScheduleLast   = "backup.schedule.last"
	SettingBackupScheduleState  = "backup.schedule.state"
	SettingBackupLastSuccess    = "backup.local.last_success"
	SettingBackupRemoteSchedule = "backup.schedule.remote_destination"
)

Local backup schedule / retention settings (System → Backups).

View Source 
const (
	CheckOK   = "ok"
	CheckWarn = "warn"
	CheckFail = "fail"
)

Health check statuses.

View Source 
const (
	SettingRetainDoneDays  = "jobs.retain_done_days"
	SettingRetainDeadDays  = "jobs.retain_dead_days"
	SettingRetainKeyedDays = "jobs.retain_keyed_days"
)

Retention settings of the jobs.prune cron (whole days).

View Source 
const (
	PermUsers    = "users.manage"
	PermSettings = "settings.manage"
	PermHealth   = "system.health"
	PermAPIKeys  = "api_keys.manage"
	PermBackup   = "system.backup"
	PermUpdate   = "system.update"
)

Permissions used by the admin screens.

View Source 
const (
	AIProviderOpenAI    = "openai"
	AIProviderAnthropic = "anthropic"
)

AI writing providers (setting ai.provider; "" turns the helper off).

View Source 
const (
	SettingWorkspace = "site.workspace"
	WorkspaceSimple  = "simple"
	WorkspaceFull    = "full"
)

Site workspace mode: progressive disclosure for operators who want a plain CMS versus Agents + Commerce. Empty means unset (full nav until chosen; first-run surfaces a chooser).

View Source 
const HealthCheckFilter = "system.health.checks"

HealthCheckFilter is the hooks filter other modules use to contribute checks to System Health. The payload is *[]admin.HealthCheck; append to it and return it.

View Source 
const ModuleRequirementFilter = "system.capabilities.modules"

ModuleRequirementFilter is the hooks filter modules use to report their configuration state to GET /site/capabilities. The payload is *[]admin.ModuleRequirement; append one entry per module.

View Source 
const (
	PermCapabilityTest = "system.capability_test"
)

Capability evidence levels. A connectivity check (list models, discover tools, probe a bucket) proves reachability only. An operation test exercises the real operation with an isolated sample under an explicit permission: send one mail to the requesting operator, write/read/delete one probe object, request one tiny completion. MCP tool invocation would execute remote actions, so MCP has no operation test. Nothing here runs during a page load or a GET.

View Source 
const ServiceCanvasRead = "admin.canvases"

ServiceCanvasRead is the kernel service name for grant-scoped canvas reads.

Variables

This section is empty.

Functions

func AIConfig 

func AIConfig(provider, baseURL, model, apiKey string, keyStored bool, secretKey []byte) (map[string]any, map[string]string)

AIConfig validates an AI writing configuration exactly as Settings → AI does and returns the settings to store (the API key encrypted with secretKey; omitted when apiKey is blank) and field errors as i18n keys. keyStored says whether a key is already stored. The CLI uses it too.

func CompleteWorkAgent 

func CompleteWorkAgent(ctx context.Context, d *kernel.Deps, connectionID, model, system, input string) (string, error)

CompleteWorkAgent reuses the configured server-side provider and encrypted connection registry. It executes a text-only turn, never tool calls.

func FilterNavForWorkspace added in v0.4.0 

func FilterNavForWorkspace(mode string, items []kernel.NavItem) []kernel.NavItem

FilterNavForWorkspace drops Agents/Commerce surfaces in simple mode.

func PostsPerPage 

func PostsPerPage(value string) (int, bool)

PostsPerPage parses a site.posts_per_page value (an integer 1–100).

func ValidateGeneralSetting 

func ValidateGeneralSetting(key, value string) (string, error)

ValidateGeneralSetting validates and normalises one Settings → General value exactly as the admin screen does, for the keys that need no other service: site.title (required, trimmed, max 500 runes), site.tagline (trimmed, max 500 runes), site.locale (a supported locale), site.timezone (an IANA name; "" and "Local" are rejected) and site.base_url (absolute http(s) origin, no trailing slash). It returns the value to store, or a *SettingError. Other keys (site.theme and site.front_page need the theme and content services, site.logo the media service) are rejected with code "admin.settings.error_key". contact.email must be empty or a plain address; site.posts_per_page an integer 1–100 (returned in canonical decimal form; store it as a number, see PostsPerPage).

func ValidateSEOSetting 

func ValidateSEOSetting(key, value string) (string, error)

ValidateSEOSetting validates one Settings → SEO value. The rules belong to the seo module (seo.ValidateSetting); this alias keeps the admin settings validators in one place for callers such as mcp.

func WorkAgentProviderReady 

func WorkAgentProviderReady(ctx context.Context, d *kernel.Deps, connectionID, model string) bool

WorkAgentProviderReady verifies configuration and credential readability, without sending a request or claiming the provider is reachable.

func WorkspaceMode added in v0.4.0 

func WorkspaceMode(ctx context.Context, s *settings.Store) string

WorkspaceMode returns simple, full, or "" when unset / unknown.

func WorkspaceShowsAdvanced added in v0.4.0 

func WorkspaceShowsAdvanced(ctx context.Context, s *settings.Store) bool

WorkspaceShowsAdvanced is true when Agents / Commerce / AI surfaces should appear (full mode, or unset so existing installs keep working).

Types

type CanvasDocument added in v0.11.0 

type CanvasDocument struct {
	ID        string       `json:"id"`
	Title     string       `json:"title"`
	UpdatedAt string       `json:"updated_at"`
	Version   int64        `json:"version"`
	Cards     []canvasCard `json:"cards"`
	Edges     []canvasEdge `json:"edges"`
}

CanvasDocument is get_canvas / GET /api/v1/canvases/{id} (no secrets).

type CanvasReader added in v0.11.0 

type CanvasReader interface {
	List(ctx context.Context, page, perPage int) ([]CanvasSummary, int, error)
	Get(ctx context.Context, id string) (*CanvasDocument, error)
}

CanvasReader is the grant-scoped list/get surface for MCP and REST.

type CanvasSummary added in v0.11.0 

type CanvasSummary struct {
	ID        string `json:"id"`
	Title     string `json:"title"`
	UpdatedAt string `json:"updated_at"`
	Version   int64  `json:"version"`
}

CanvasSummary is one board in list_canvases / GET /api/v1/canvases.

type CapabilityCheck added in v0.14.0 

type CapabilityCheck struct {
	Kind               string  `json:"kind" enum:"connectivity,operation"`
	Scope              string  `json:"scope" doc:"What exactly ran, e.g. connectivity, operation:send, operation:write_read_delete, operation:complete"`
	Status             string  `json:"status" enum:"passed,failed,unknown,stale,expired,waiting,running"`
	Result             string  `` /* 131-byte string literal not displayed */
	CheckedAt          *string `json:"checked_at" doc:"Persisted RFC3339 time of the saved result; null if missing or invalid"`
	ExpiresAt          *string `json:"expires_at" doc:"When the evidence stops counting (checked_at + 7 days); null when unknown"`
	ConfigurationMatch *bool   `json:"configuration_match" doc:"Null for legacy checks not bound to a configuration revision"`
	Reason             string  `json:"reason"`
	Remediation        string  `json:"remediation"`
}

CapabilityCheck describes evidence, not a promise that a future operation will succeed. Kind says what ran: a connectivity/discovery check or an explicit operation test.

type CapabilityReport added in v0.14.0 

type CapabilityReport struct {
	ObservedAt  string            `json:"observed_at" doc:"When this local snapshot was read, not a health-check timestamp"`
	Modules     []CapabilityState `json:"modules"`
	Services    []CapabilityState `json:"services" doc:"Core services that are not modules (mail)"`
	Connections []CapabilityState `json:"connections"`
	Coverage    string            `json:"coverage"`
}

CapabilityReport is GET /site/capabilities.

type CapabilityState added in v0.14.0 

type CapabilityState struct {
	ID                  string           `json:"id"`
	Kind                string           `json:"kind" enum:"module,service,ai,mcp,s3,unknown"`
	Available           bool             `json:"available"`
	Enabled             *bool            `` /* 133-byte string literal not displayed */
	Configured          *bool            `` /* 139-byte string literal not displayed */
	Connected           *bool            `json:"connected" doc:"True only for a current, unexpired, passed connectivity check; null when never checked"`
	Tested              bool             `json:"tested" doc:"True only for a current, unexpired, passed operation test; connectivity never sets this flag"`
	OperationSupported  bool             `json:"operation_supported" doc:"Whether a safe operation test exists for this kind"`
	Source              string           `json:"source"`
	ConfigurationStatus string           `json:"configuration_status" enum:"configured,incomplete,unknown"`
	Reason              string           `json:"reason"`
	Remediation         string           `json:"remediation"`
	LastCheck           *CapabilityCheck `json:"last_check" doc:"Last saved connectivity check, or null; GET never runs one"`
	Operation           *CapabilityCheck `json:"operation" doc:"Last saved operation test, or null; GET never runs one"`
}

CapabilityState separates facts we can observe from facts not yet reported. Null configured/enabled values must not be interpreted as false or success.

type HealthCheck 

type HealthCheck struct {
	Name        string `json:"name"`
	Status      string `json:"status"` // ok | warn | fail
	Detail      string `json:"detail"`
	OptionalOff bool   `json:"-"`
}

HealthCheck is one line of the System Health "Checks" list.

type KeyCreateRequest 

type KeyCreateRequest struct {
	Name       string   `json:"name"`
	Kind       string   `json:"kind" doc:"api (default) | agent"`
	Scopes     []string `json:"scopes" doc:"permission names, or [\"*\"]; never more than the caller holds (session callers only)"`
	RatePerMin int      `json:"rate_per_min" doc:"default 60"`
	ExpiresAt  string   `json:"expires_at" doc:"RFC3339, empty for never"`
}

KeyCreateRequest is the POST /v1/keys body.

type KeyDTO 

type KeyDTO struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Prefix      string   `json:"prefix" doc:"first characters after gp_, shown to identify the key"`
	Kind        string   `json:"kind" doc:"api | agent"`
	UserID      string   `json:"user_id"`
	Scopes      []string `json:"scopes"`
	RatePerMin  int      `json:"rate_per_min"`
	ExpiresAt   string   `json:"expires_at"`
	LastUsedAt  string   `json:"last_used_at"`
	UseCount    int64    `json:"use_count" doc:"approximate; flushed at most once a minute"`
	CreatedAt   string   `json:"created_at"`
	RevokedAt   string   `json:"revoked_at"`
	RotatedFrom string   `json:"rotated_from"`
	Status      string   `json:"status" doc:"active | expired | revoked"`
}

KeyDTO is an API key as the key console API returns it (never the secret).

type KeyRotateRequest 

type KeyRotateRequest struct {
	GraceSeconds int `json:"grace_seconds" doc:"0 revokes the old key now; up to 604800 keeps it working that long"`
}

KeyRotateRequest is the POST /v1/keys/{id}/rotate body.

type KeySecretResponse 

type KeySecretResponse struct {
	Key   KeyDTO `json:"key"`
	Token string `json:"token"`
}

KeySecretResponse is returned once by create and rotate: token is the plaintext key and is never shown again.

type LatestRelease added in v0.15.0 

type LatestRelease struct {
	Status     string  `json:"status" enum:"fresh,stale,failed,waiting,running,unknown" doc:"unknown: no source configured or never observed"`
	Version    *string `json:"version" doc:"Null when unknown"`
	Artifact   *string `json:"artifact"`
	ObservedAt *string `json:"observed_at" doc:"When the saved value was read from the source"`
	AgeSeconds *int64  `json:"age_seconds"`
	Source     string  `json:"source"`
	Error      string  `json:"error" doc:"Sanitized reason of the newest failed attempt"`
}

LatestRelease is the saved background observation of the trusted source.

type Module 

type Module struct{}

Module is the admin kernel.Module.

func New 

func New() *Module

New returns the admin module.

func (*Module) Catalogs 

func (*Module) Catalogs() fs.FS

Catalogs implements kernel.CatalogProvider.

func (*Module) Migrations 

func (*Module) Migrations() fs.FS

Migrations implements kernel.Module.

func (*Module) Name 

func (*Module) Name() string

Name implements kernel.Module.

func (*Module) Register 

func (*Module) Register(d *kernel.Deps) error

Register declares permissions, publishes the mailer, adds nav items, dashboard widgets, admin routes and API operations.

type ModuleRequirement added in v0.15.0 

type ModuleRequirement struct {
	Module      string `json:"module"`
	Configured  bool   `json:"configured"`
	Reason      string `json:"reason"`
	Remediation string `json:"remediation"`
}

ModuleRequirement is a module's own configuration verdict: whether its required settings are present, why not, and the practical repair step.

type SettingError 

type SettingError struct{ Key, Code string }

SettingError is a rejected setting value; Code is an i18n key.

func (*SettingError) Error 

func (e *SettingError) Error() string

type SettingsDTO 

type SettingsDTO struct {
	SiteTitle           string `json:"site.title"`
	SiteTagline         string `json:"site.tagline"`
	SiteLocale          string `json:"site.locale"`
	SiteTimezone        string `json:"site.timezone"`
	SiteBaseURL         string `json:"site.base_url"`
	SiteTheme           string `json:"site.theme"`
	SiteFrontPage       string `json:"site.front_page"`
	SiteLogoDark        string `json:"site.logo_dark" doc:"Media id shown on dark backgrounds; empty falls back to site.logo"`
	SiteLogoLight       string `json:"site.logo_light" doc:"Media id shown on light backgrounds; empty falls back to site.logo"`
	SiteIcon            string `json:"site.icon" doc:"Media id for the favicon / app icon"`
	ContactEmail        string `json:"contact.email"`
	PostsPerPage        int    `json:"site.posts_per_page"`
	MailProvider        string `json:"mail.provider"`
	MailResendAPIKeySet bool   `json:"mail.resend_api_key_set"`
	MailHost            string `json:"mail.host"`
	MailPort            int    `json:"mail.port"`
	MailUsername        string `json:"mail.username"`
	MailFrom            string `json:"mail.from"`
	MailFromName        string `json:"mail.from_name"`
	MailTLS             string `json:"mail.tls"`
	MailReplyTo         string `json:"mail.reply_to"`
	MailPasswordSet     bool   `json:"mail.password_set"`
}

SettingsDTO is the GET /v1/settings response (and the PATCH response). mail.password is never returned; mail.password_set reports whether one is stored.

type SettingsPatchDTO 

type SettingsPatchDTO struct {
	SiteTitle        *string `json:"site.title,omitempty"`
	SiteTagline      *string `json:"site.tagline,omitempty"`
	SiteLocale       *string `json:"site.locale,omitempty"`
	SiteTimezone     *string `json:"site.timezone,omitempty"`
	SiteBaseURL      *string `json:"site.base_url,omitempty"`
	SiteTheme        *string `json:"site.theme,omitempty"`
	SiteFrontPage    *string `json:"site.front_page,omitempty"`
	SiteLogoDark     *string `json:"site.logo_dark,omitempty"`
	SiteLogoLight    *string `json:"site.logo_light,omitempty"`
	SiteIcon         *string `json:"site.icon,omitempty"`
	ContactEmail     *string `json:"contact.email,omitempty"`
	PostsPerPage     *int    `json:"site.posts_per_page,omitempty"`
	MailProvider     *string `json:"mail.provider,omitempty"`
	MailResendAPIKey *string `json:"mail.resend_api_key,omitempty"`
	MailHost         *string `json:"mail.host,omitempty"`
	MailPort         *int    `json:"mail.port,omitempty"`
	MailUsername     *string `json:"mail.username,omitempty"`
	MailPassword     *string `json:"mail.password,omitempty"`
	MailFrom         *string `json:"mail.from,omitempty"`
	MailFromName     *string `json:"mail.from_name,omitempty"`
	MailTLS          *string `json:"mail.tls,omitempty"`
	MailReplyTo      *string `json:"mail.reply_to,omitempty"`
}

SettingsPatchDTO documents the PATCH /v1/settings body: send only the keys to change. "mail.password": null clears the stored password, "" keeps it, any other string replaces it (stored encrypted). Unknown keys are rejected.

type TestHelper added in v0.15.0 

type TestHelper struct{ App *kernel.App }

TestHelper exposes test-only encoding helpers to external test packages. It is compiled into the package but only useful from tests.

func (*TestHelper) EncryptSecrets added in v0.15.0 

func (h *TestHelper) EncryptSecrets(t *testing.T, token, access, secret string) string

EncryptSecrets encrypts a connection secret bundle with the app's secret key.

type UpdateStatus added in v0.15.0 

type UpdateStatus struct {
	RunningVersion  string            `json:"running_version" doc:"Serving process identity (build string)"`
	IsRelease       bool              `json:"is_release" doc:"False for development builds, which cannot be compared"`
	AcceptedVersion *string           `json:"accepted_version" doc:"Last target durably accepted by a completed operation; null if none"`
	Latest          LatestRelease     `json:"latest"`
	UpdateAvailable *bool             `json:"update_available" doc:"Null when latest or the running identity is unknown"`
	Configured      bool              `json:"configured" doc:"A trusted release source is configured"`
	Source          string            `json:"source"`
	Adapter         string            `json:"adapter" enum:"manual,coolify"`
	Active          *update.Operation `json:"active" doc:"Pending or running operation; null when idle"`
	Last            *update.Operation `json:"last" doc:"Most recent operation; null when none"`
}

UpdateStatus is GET /system/update. Latest, accepted, activated and requested versions are reported separately and never conflated.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.