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

admin

package
v0.14.1 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2026 License: AGPL-3.0 Imports: 62 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"
)

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 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"`
	Status             string  `json:"status" enum:"passed,failed,unknown,stale"`
	Result             string  `json:"result" enum:"passed,failed,unknown" doc:"Recorded result, retained even when its applicability is stale or unknown"`
	CheckedAt          *string `json:"checked_at" doc:"Persisted RFC3339 time; null if missing or invalid"`
	ConfigurationMatch *bool   `json:"configuration_match" doc:"Null for legacy checks not bound to a configuration version"`
	Reason             string  `json:"reason"`
	Remediation        string  `json:"remediation"`
}

CapabilityCheck describes evidence, not a promise that a future operation will succeed. Existing connection tests only exercise discovery/connectivity.

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"`
	Connections []CapabilityState `json:"connections"`
	Coverage    string            `json:"coverage"`
}

type CapabilityState added in v0.14.0 

type CapabilityState struct {
	ID                  string           `json:"id"`
	Kind                string           `json:"kind" enum:"module,ai,mcp,s3,unknown"`
	Available           bool             `json:"available"`
	Enabled             *bool            `json:"enabled" doc:"Actual boot activation for modules; null for reusable profiles, which do not own feature activation"`
	Configured          *bool            `json:"configured" doc:"Local profile validation only; null when the module does not publish configuration requirements"`
	Tested              bool             `` /* 139-byte string literal not displayed */
	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 check, or null when no check exists; GET does not run a check"`
}

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 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 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"`
	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"`
	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"`
	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"`
}

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.

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.