httpapi

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 67 Imported by: 0

Documentation

Overview

Package httpapi is the backend's HTTP surface. New (api.go) builds one chi router that serves:

  • /api/v1: the REST API used by the frontend and scripts, declared with Huma, which also generates the OpenAPI document (api/openapi.json);
  • the game and launcher protocols, compatible with Blessing Skin;
  • health probes, the /events change stream and theme assets.

Handlers translate HTTP to calls on the services in internal/modules and back; the rules live in the services. Where to find an endpoint:

Site and accounts (/api/v1)
  site.go            bootstrap (settings, theme, viewer for every page), site stats
  auth.go            first-run setup, login, logout, the signed-in user; CSRF guard
  setup.go           Pre-Core setup wizard endpoints, chunked upload, BS import & restore jobs
  register.go        registration, image captcha
  mail.go            email verification, password reset, test mail
  me.go              profile, password, email, devices, account deletion
  social.go          sign-in with GitHub, Microsoft, OpenID Connect
Textures and players (/api/v1)
  textures.go        upload, skin library, texture pages, closet listing
  manage.go          closet changes, texture edits and deletion, check-in, dashboard
  players.go         players and what they wear
  reports.go         reporting textures and reviewing reports
  notifications.go   inbox, avatar choice, sending notifications
Administration (/api/v1/admin)
  admin_settings.go  settings, themes, home page blocks
  admin_users.go     users and the audit log
  admin_players.go   overview, players, closets of users
  admin_status.go    system status
  admin_cdn.go       CDN purge
Open platform
  oauth.go           OAuth 2.0 server (/oauth/*), consent, applications, tokens
  bsapi.go           Blessing Skin compatible user API (/api/user, /api/players...)
  bsadmin.go         Blessing Skin compatible admin API (/api/admin/*)
Game clients
  game.go            CustomSkinLoader, UniSkinMod and legacy profile URLs
  files.go           texture files (/textures/{hash}, /raw/{tid})
  render.go          avatars and previews (/avatar, /preview)
  yggdrasil.go       authlib-injector (/api/yggdrasil) and launcher sign-outs
Plumbing
  api.go             router, middleware, health probes, admin check
  events.go          /events (Server-Sent Events)

Index

Constants

View Source
const BSCompatVersion = "6.0.2"

BSCompatVersion is the Blessing Skin version whose API this one matches.

View Source
const CSRFHeader = "X-SkinLoom-Request"

CSRFHeader must accompany every state-changing API request made with a session cookie. Browsers only send custom headers cross-origin after a CORS preflight, which SkinLoom never approves, so a forged form or fetch from another site cannot set it.

View Source
const ProblemEmailNotVerified = "tag:skinloom.cn,2026:email-not-verified"

ProblemEmailNotVerified is the problem type (RFC 9457) of a refusal because the site requires a verified email address, so the frontend can ask the user to verify instead of showing what else a 403 means there.

View Source
const SessionCookie = "skinloom_session"

SessionCookie holds the browser session token.

View Source
const SetupCookie = "skinloom_setup"

SetupCookie holds the short-lived session token for the multi-step setup wizard.

View Source
const SocialCookie = "skinloom_social"

SocialCookie ties a sign-in with a provider to the browser that started it.

View Source
const YggdrasilPrefix = "/api/yggdrasil"

YggdrasilPrefix is where the Yggdrasil API lives (authlib-injector's API root).

Variables

View Source
var (
	ErrSetupInvalidToken   = errors.New("invalid or expired setup token")
	ErrSetupAlreadyDone    = errors.New("setup has already been completed")
	ErrSetupSessionInvalid = errors.New("setup session is missing or expired")
	ErrSetupNotFound       = errors.New("setup resource not found")
	ErrSetupConflict       = errors.New("setup state conflict")
)

Setup-specific error sentinels mapped to RFC 9457 responses.

View Source
var Locales = []LocaleInfo{
	{Code: "zh-CN", Name: "简体中文"},
	{Code: "en", Name: "English"},
}

Locales the M0 frontend ships messages for; the full BS set is imported in M1.

Functions

func New

func New(d Deps) (http.Handler, huma.API)

New returns the HTTP handler and the Huma API (whose OpenAPI document can be exported).

func PickLocale

func PickLocale(lang, cookie, accept string) string

PickLocale chooses the UI language: explicit ?lang, then the locale cookie, then Accept-Language. Unknown values are ignored (never persisted), unlike BS issue #684.

Types

type AdminMarketInstallResult added in v1.1.0

type AdminMarketInstallResult struct {
	Plugin                AdminPluginView   `json:"plugin"`
	InstalledDependencies []AdminPluginView `json:"installedDependencies,omitempty"`
}

AdminMarketInstallResult summarizes the installed market package and any cascade-installed dependencies.

type AdminOverview

type AdminOverview struct {
	Users          int           `json:"users"`
	Players        int           `json:"players"`
	Textures       int           `json:"textures"`
	PublicTextures int           `json:"publicTextures"`
	ClosetItems    int           `json:"closetItems"`
	Files          int           `json:"files" doc:"Stored files; equal images share one"`
	StorageBytes   int64         `json:"storageBytes"`
	PendingReports int           `json:"pendingReports"`
	Days           []OverviewDay `json:"days" doc:"The last 31 days, today last"`
}

AdminOverview is the admin overview.

type AdminPlayerPage

type AdminPlayerPage struct {
	Players []AdminPlayerView `json:"players"`
	Next    int64             `json:"next" doc:"Pass as before= for the next page; 0 = last page"`
}

AdminPlayerPage is one page of the player list.

type AdminPlayerView

type AdminPlayerView struct {
	ID        int64         `json:"id"`
	Name      string        `json:"name"`
	UUID      string        `json:"uuid" doc:"32 hex digits, no dashes"`
	Owner     *AdminUserRef `json:"owner,omitempty"`
	Skin      *WornTexture  `json:"skin,omitempty"`
	Cape      *WornTexture  `json:"cape,omitempty"`
	CreatedAt time.Time     `json:"createdAt"`
	UpdatedAt time.Time     `json:"updatedAt"`
}

AdminPlayerView is a player in the admin panel.

type AdminPluginRoute added in v1.1.0

type AdminPluginRoute struct {
	Method      string `json:"method"`
	Pattern     string `json:"pattern"`
	Auth        string `json:"auth"`
	StreamProxy bool   `json:"streamProxy,omitempty"`
}

AdminPluginRoute describes one registered HTTP route belonging to a plugin.

type AdminPluginView added in v1.1.0

type AdminPluginView struct {
	ID                 string                  `json:"id"`
	Kind               string                  `json:"kind"`
	Runtime            string                  `json:"runtime"`
	Version            string                  `json:"version"`
	Name               string                  `json:"name"`
	Description        string                  `json:"description,omitempty"`
	Authors            []string                `json:"authors,omitempty"`
	Homepage           string                  `json:"homepage,omitempty"`
	Status             string                  `json:"status"`
	Error              string                  `json:"error,omitempty"`
	Source             string                  `json:"source"`
	RegistrySource     string                  `json:"registrySource,omitempty"`
	PackageSHA256      string                  `json:"packageSha256,omitempty"`
	Platforms          []string                `json:"platforms,omitempty"`
	HasServer          bool                    `json:"hasServer"`
	HasWeb             bool                    `json:"hasWeb"`
	HasSettings        bool                    `json:"hasSettings"`
	Permissions        plugin.PermissionGroups `json:"permissions"`
	GrantedPermissions []string                `json:"grantedPermissions"`
	Settings           map[string]any          `json:"settings,omitempty"`
	Routes             []AdminPluginRoute      `json:"routes,omitempty"`
	Stats              *jsrt.PoolStats         `json:"stats,omitempty"`
	NativeStats        *plugin.NativeStats     `json:"nativeStats,omitempty"`
	Usage              *plugin.PluginUsage     `json:"usage,omitempty"`
	RecentLogs         []plugin.LogEntry       `json:"recentLogs,omitempty"`
	CircuitTripped     bool                    `json:"circuitTripped,omitempty"`
	ConsecutiveErrors  int                     `json:"consecutiveErrors,omitempty"`
}

AdminPluginView summarizes an installed plugin or theme for the admin panel.

type AdminReportPage

type AdminReportPage struct {
	Reports []AdminReportView `json:"reports"`
	Next    int64             `json:"next" doc:"Pass as before= for the next page; 0 = last page"`
}

AdminReportPage is one page of the review queue.

type AdminReportView

type AdminReportView struct {
	ID        int64         `json:"id"`
	Texture   *TextureView  `json:"texture,omitempty" doc:"Absent once the texture is deleted"`
	Reason    string        `json:"reason"`
	Status    string        `json:"status" enum:"pending,resolved,rejected"`
	Action    string        `json:"action,omitempty" enum:"delete,ban,reject,"`
	Reporter  *AdminUserRef `json:"reporter,omitempty" doc:"Absent once the account is gone"`
	Uploader  *AdminUserRef `json:"uploader,omitempty" doc:"The texture's uploader when it was reported"`
	Handler   *AdminUserRef `json:"handler,omitempty" doc:"Absent for the admin token"`
	CreatedAt time.Time     `json:"createdAt"`
	HandledAt *time.Time    `json:"handledAt,omitempty"`
}

AdminReportView is a report in the review queue.

type AdminUserRef

type AdminUserRef struct {
	ID       int64  `json:"id"`
	Nickname string `json:"nickname"`
	Email    string `json:"email"`
	Status   string `json:"status" enum:"active,banned,deleted"`
}

AdminUserRef names a user in the admin panel.

type AdminUserView

type AdminUserView struct {
	ID            int64            `json:"id"`
	Email         string           `json:"email"`
	Nickname      string           `json:"nickname"`
	Role          string           `json:"role" enum:"user,admin,superadmin"`
	Status        string           `json:"status" enum:"active,banned,deleted"`
	Score         int64            `json:"score"`
	EmailVerified bool             `json:"emailVerified"`
	Locale        string           `json:"locale"`
	RegisterIP    string           `json:"registerIp"`
	Badges        []hook.UserBadge `json:"badges,omitempty"`
	CreatedAt     time.Time        `json:"createdAt"`
	LastLoginAt   *time.Time       `json:"lastLoginAt,omitempty"`
	DeletedAt     *time.Time       `json:"deletedAt,omitempty" doc:"Set while a self-deleted account waits out its grace period"`
}

AdminUserView is a user as shown in the admin panel.

type AuditPage

type AuditPage struct {
	Records []AuditView `json:"records"`
	Next    int64       `json:"next"`
}

AuditPage is one page of the audit log.

type AuditView

type AuditView struct {
	ID         int64          `json:"id"`
	ActorID    *int64         `json:"actorId,omitempty" doc:"Absent for the system and the admin token"`
	Action     string         `json:"action"`
	TargetType string         `json:"targetType"`
	TargetID   string         `json:"targetId"`
	IP         string         `json:"ip"`
	Meta       map[string]any `json:"meta,omitempty"`
	CreatedAt  time.Time      `json:"createdAt"`
}

AuditView is one audit record.

type AuthInfo

type AuthInfo struct {
	Registration string      `json:"registration" enum:"open,closed"`
	Captcha      CaptchaInfo `json:"captcha"`
	// Mail is true when mail and site.url are configured: password reset and email
	// verification work.
	Mail bool `json:"mail"`
	// RequireVerification: accounts must verify their email before managing players,
	// uploading, reporting or signing in to launchers (auth.require_email_verification).
	RequireVerification bool `json:"requireVerification"`
	// Social are the sign-in providers (none until site.url is set).
	Social []SocialProviderInfo `json:"social"`
}

AuthInfo tells the frontend which account forms to show.

type AuthorizeInfo

type AuthorizeInfo struct {
	Error       string          `json:"error,omitempty" doc:"The request is broken and cannot go back to the application: show this"`
	Redirect    string          `json:"redirect,omitempty" doc:"Send the browser here (an error the application handles)"`
	Client      *OAuthClientRef `json:"client,omitempty"`
	RedirectURI string          `json:"redirectUri,omitempty"`
	Scopes      []string        `json:"scopes,omitempty" doc:"What would be granted"`
	Granted     bool            `json:"granted" doc:"You already allowed all of it: approve without asking"`
}

AuthorizeInfo answers a look at an authorization request, for the consent screen: exactly one of error, redirect or client is set.

type AuthorizeResult

type AuthorizeResult struct {
	Redirect string `json:"redirect"`
}

AuthorizeResult is where to send the browser after approving or refusing.

type BSDryRunInput added in v1.1.0

type BSDryRunInput struct {
	Source BSSourceInput `json:"source"`
}

BSDryRunInput starts a dry-run BS migration job.

type BSImportInput added in v1.1.0

type BSImportInput struct {
	Database       DBConfigInput       `json:"database"`
	Storage        StorageConfigInput  `json:"storage"`
	TrustedProxies []string            `json:"trustedProxies,omitempty"`
	Source         BSSourceInput       `json:"source"`
	SiteURL        string              `json:"siteUrl,omitempty" maxLength:"512"`
	FallbackAdmin  *FallbackAdminInput `json:"fallbackAdmin,omitempty"`
}

BSImportInput starts a real BS migration job and transitions the server.

type BSReportEntryView added in v1.1.0

type BSReportEntryView struct {
	Severity   string `json:"severity"`
	Table      string `json:"table"`
	ID         string `json:"id,omitempty"`
	Message    string `json:"message"`
	LeftBehind bool   `json:"leftBehind,omitempty"`
}

BSReportEntryView is one migration report entry in JSON.

type BSReportView added in v1.1.0

type BSReportView struct {
	DryRun      bool                `json:"dryRun"`
	Entries     []BSReportEntryView `json:"entries"`
	Imported    map[string]int      `json:"imported"`
	Files       int                 `json:"files"`
	FilesCopied int                 `json:"filesCopied"`
	Superadmins int                 `json:"superadmins"`
	Blocked     bool                `json:"blocked"`
	Failed      string              `json:"failed,omitempty"`
}

BSReportView is the structured BS migration report in JSON.

func BSReportToView added in v1.1.0

func BSReportToView(r *bs.Report) *BSReportView

BSReportToView converts *bs.Report into a JSON-friendly BSReportView.

type BSSourceInput added in v1.1.0

type BSSourceInput struct {
	EnvID              string   `json:"envId,omitempty" maxLength:"128"`
	SourceType         string   `json:"sourceType,omitempty" enum:"db,bridge,"`
	Driver             string   `json:"driver,omitempty" enum:"mysql,postgres,sqlite,"`
	Host               string   `json:"host,omitempty" maxLength:"255"`
	Port               int      `json:"port,omitempty"`
	Database           string   `json:"database,omitempty" maxLength:"255"`
	Username           string   `json:"username,omitempty" maxLength:"255"`
	Password           string   `json:"password,omitempty" maxLength:"1024"`
	Socket             string   `json:"socket,omitempty" maxLength:"512"`
	RawDSN             string   `json:"rawDsn,omitempty" maxLength:"1024"`
	Prefix             string   `json:"prefix,omitempty" maxLength:"64"`
	PasswordMethod     string   `json:"passwordMethod,omitempty" maxLength:"64"`
	Salt               string   `json:"salt,omitempty" maxLength:"1024"`
	TransitionMethods  []string `json:"transitionMethods,omitempty"`
	Timezone           string   `json:"timezone,omitempty" maxLength:"128"`
	TextureSource      string   `json:"textureSource,omitempty" enum:"dir,upload,none,bridge,"`
	TexturesDir        string   `json:"texturesDir,omitempty" maxLength:"1024"`
	UploadID           string   `json:"uploadId,omitempty" maxLength:"128"`
	BridgeURL          string   `json:"bridgeUrl,omitempty" maxLength:"512"`
	BridgeToken        string   `json:"bridgeToken,omitempty" maxLength:"512"`
	AllowInsecureLocal bool     `json:"allowInsecureLocal,omitempty"`
	MailFromEnv        *bs.Mail `json:"-"`
}

BSSourceInput specifies how to read the Blessing Skin source site.

type BackupManifestView added in v1.1.0

type BackupManifestView struct {
	Format       int       `json:"format"`
	Version      string    `json:"version"`
	CreatedAt    time.Time `json:"createdAt"`
	Database     string    `json:"database"`
	Migration    int64     `json:"migration"`
	HasDatabase  bool      `json:"hasDatabase"`
	Textures     int       `json:"textures"`
	TextureBytes int64     `json:"textureBytes"`
}

BackupManifestView mirrors backup.Manifest safely for OpenAPI.

type Bootstrap

type Bootstrap struct {
	Version int64                        `json:"version" doc:"Config version; changes whenever settings, themes or plugins change"`
	Locale  string                       `json:"locale"`
	Locales []LocaleInfo                 `json:"locales"`
	Site    SiteInfo                     `json:"site"`
	Theme   theme.ResolvedTheme          `json:"theme"`
	Menus   map[string][]MenuItem        `json:"menus" doc:"Keyed by area: explore, user, admin"`
	Plugins []PluginFrontend             `json:"plugins"`
	Forms   map[string][]PluginFormField `json:"forms,omitempty" doc:"Declarative form fields grouped by scope"`
	Server  ServerInfo                   `json:"server"`
	// NeedsSetup is true until the first administrator is created (see /api/v1/setup).
	NeedsSetup bool     `json:"needsSetup"`
	Auth       AuthInfo `json:"auth"`
	// Messages are the administrator's wording of interface texts in this locale
	// (i18n.overrides), by message key; the frontend lays them over its own.
	Messages map[string]string `json:"messages"`
}

Bootstrap is everything the frontend needs to render any page.

type CaptchaImage

type CaptchaImage struct {
	ID    string `json:"id"`
	Image string `json:"image" doc:"data:image/png;base64,…"`
}

CaptchaImage is a fresh image challenge.

type CaptchaInfo

type CaptchaInfo struct {
	Provider string `` /* 127-byte string literal not displayed */
	SiteKey  string `json:"siteKey,omitempty" doc:"Widget site key (turnstile, recaptcha, hcaptcha)"`
}

CaptchaInfo is the public half of the captcha configuration.

type ClosetItemView

type ClosetItemView struct {
	ID      int64       `json:"id"`
	Name    string      `json:"name"`
	AddedAt time.Time   `json:"addedAt"`
	Texture TextureView `json:"texture"`
}

ClosetItemView is a texture in the signed-in user's closet.

type ClosetPage

type ClosetPage struct {
	Items []ClosetItemView `json:"items"`
	Next  int64            `json:"next" doc:"Pass as before= for the next page; 0 = last page"`
}

ClosetPage is one page of a closet.

type CompleteWizardInput added in v1.1.0

type CompleteWizardInput struct {
	Database       DBConfigInput       `json:"database"`
	Storage        StorageConfigInput  `json:"storage"`
	TrustedProxies []string            `json:"trustedProxies,omitempty"`
	SiteName       string              `json:"siteName,omitempty" maxLength:"64"`
	SiteURL        string              `json:"siteUrl,omitempty" maxLength:"512"`
	Timezone       string              `json:"timezone,omitempty" maxLength:"128"`
	Email          string              `json:"email" maxLength:"255"`
	Nickname       string              `json:"nickname" maxLength:"128"`
	Password       string              `json:"password" maxLength:"1024"`
	Mail           *MailConfigInput    `json:"mail,omitempty"`
	ClientMeta     account.RequestMeta `json:"-"`
}

CompleteWizardInput finishes a brand-new SkinLoom installation with full infra & admin config.

type ConfigStatus

type ConfigStatus struct {
	Version int64  `json:"version" doc:"Config version"`
	Theme   string `json:"theme"`
	Changed int    `json:"changed" doc:"Settings changed from their defaults"`
}

type ConnectExistingInput added in v1.1.0

type ConnectExistingInput struct {
	Database       DBConfigInput      `json:"database"`
	Storage        StorageConfigInput `json:"storage"`
	TrustedProxies []string           `json:"trustedProxies,omitempty"`
}

ConnectExistingInput attaches this node to an already initialized SkinLoom database.

type ConnectExistingResult added in v1.1.0

type ConnectExistingResult struct {
	RedirectTo string `json:"redirectTo"`
}

ConnectExistingResult instructs the UI where to redirect after attaching to an existing DB.

type CreateUploadInput added in v1.1.0

type CreateUploadInput struct {
	Purpose   string `json:"purpose" enum:"bs_textures,backup"`
	Filename  string `json:"filename" maxLength:"255"`
	TotalSize int64  `json:"totalSize"`
}

CreateUploadInput initiates a chunked archive upload.

type CreateUploadResult added in v1.1.0

type CreateUploadResult struct {
	UploadID       string `json:"uploadId"`
	ChunkSize      int64  `json:"chunkSize"`
	MaxUploadBytes int64  `json:"maxUploadBytes"`
}

CreateUploadResult returns the upload session id and chunk size.

type DBConfigInput added in v1.1.0

type DBConfigInput struct {
	UseEnv     bool   `json:"useEnv,omitempty"`
	Driver     string `json:"driver,omitempty" enum:"sqlite,mysql,postgres,"`
	Host       string `json:"host,omitempty" maxLength:"255"`
	Port       int    `json:"port,omitempty"`
	Database   string `json:"database,omitempty" maxLength:"255"`
	Username   string `json:"username,omitempty" maxLength:"255"`
	Password   string `json:"password,omitempty" maxLength:"1024"`
	SSLMode    string `json:"sslMode,omitempty" maxLength:"64"`
	SQLitePath string `json:"sqlitePath,omitempty" maxLength:"512"`
	RawDSN     string `json:"rawDsn,omitempty" maxLength:"1024"`
}

DBConfigInput defines database parameters for probing or saving.

type DBSummary added in v1.1.0

type DBSummary struct {
	Driver     string `json:"driver"`
	SQLitePath string `json:"sqlitePath,omitempty"`
	Host       string `json:"host,omitempty"`
	Port       int    `json:"port,omitempty"`
	Database   string `json:"database,omitempty"`
}

DBSummary holds non-secret initial database hints.

type Dashboard

type Dashboard struct {
	Score            int64    `json:"score"`
	Players          int      `json:"players"`
	ClosetItems      int      `json:"closetItems"`
	Uploads          int      `json:"uploads"`
	StorageBytes     int64    `json:"storageBytes"`
	Sign             SignInfo `json:"sign"`
	Announcement     string   `json:"announcement,omitempty" doc:"Markdown, in the request's language"`
	AnnouncementHTML string   `json:"announcementHtml,omitempty" doc:"The announcement rendered: no raw HTML, no script links"`
}

Dashboard is the signed-in user's overview (/user).

type DatabaseStatus

type DatabaseStatus struct {
	Dialect    string  `json:"dialect" enum:"sqlite,mysql,postgres"`
	Version    string  `json:"version"`
	Migration  int64   `json:"migration" doc:"Latest migration applied"`
	Pending    int     `json:"pending" doc:"Migrations not applied (normally 0: they run at startup)"`
	PingMillis float64 `json:"pingMillis"`
}

type Deps

type Deps struct {
	Log         *slog.Logger
	DB          *db.DB // nil during OpenAPI export or Pre-Core Setup Mode
	Setup       SetupController
	Settings    *settings.Service
	SettingsReg *settings.Registry
	Themes      *theme.Registry
	Broker      *pubsub.Broker
	Bus         *hook.Bus
	Accounts    *account.Service
	Captcha     *captcha.Service
	Mailer      *mail.Mailer
	Textures    *texture.Service
	Players     *player.Service
	Reports     *report.Service
	Renders     *render.Service
	Notify      *notify.Service
	Yggdrasil   *yggdrasil.Service
	OAuth       *oauth.Service
	Social      *social.Service
	CDN         *cdn.Service
	Plugins     *plugin.Manager
	// ClientInfo resolves the client address and public host behind trusted proxies
	// (the gateway's live resolver). Nil = trust no proxy.
	ClientInfo func(*http.Request) realip.Info
	// AdminToken also authorizes /api/v1/admin, for scripts, until personal access
	// tokens land (M3). Browsers use an admin session.
	AdminToken string
	// MaxEventStreams caps concurrent /events connections (0 = default 5000), so a
	// flood of idle SSE clients cannot exhaust memory and file descriptors.
	MaxEventStreams int
	// Runtime describes this process for the system status page.
	Runtime RuntimeInfo
	// WebReady reports whether the frontend this process runs answers; /readyz waits for
	// it, so a probe does not send visitors to a site whose pages still fail. Nil = ready.
	WebReady func() bool
}

Deps are the services the API needs.

type DetectedProxy added in v1.1.0

type DetectedProxy struct {
	PeerIP        string `json:"peerIp"`
	SuggestedCIDR string `json:"suggestedCidr"`
	Proto         string `json:"proto,omitempty"`
	Host          string `json:"host,omitempty"`
}

DetectedProxy describes an untrusted reverse proxy sending X-Forwarded-* headers.

type EnvLockedInfo added in v1.1.0

type EnvLockedInfo struct {
	Database       bool   `json:"database"`
	DatabaseDriver string `json:"databaseDriver,omitempty"`
	DatabaseMask   string `json:"databaseMask,omitempty"`
	Storage        bool   `json:"storage"`
	StorageDriver  string `json:"storageDriver,omitempty"`
	StorageMask    string `json:"storageMask,omitempty"`
	TrustedProxies bool   `json:"trustedProxies"`
}

EnvLockedInfo summarizes which infrastructure fields are fixed by SKINLOOM_* env vars.

type ExecuteRestoreInput added in v1.1.0

type ExecuteRestoreInput struct {
	UploadID           string             `json:"uploadId,omitempty" maxLength:"128"`
	Path               string             `json:"path,omitempty" maxLength:"1024"`
	Database           DBConfigInput      `json:"database"`
	Storage            StorageConfigInput `json:"storage"`
	TrustedProxies     []string           `json:"trustedProxies,omitempty"`
	ApplyArchiveConfig bool               `json:"applyArchiveConfig,omitempty"`
}

ExecuteRestoreInput executes a backup restore job and transitions the server.

type FallbackAdminInput added in v1.1.0

type FallbackAdminInput struct {
	Email    string `json:"email" maxLength:"255"`
	Nickname string `json:"nickname" maxLength:"128"`
	Password string `json:"password" maxLength:"1024"`
}

FallbackAdminInput creates a fallback superadmin when BS had zero superadmins.

type Favorited

type Favorited struct {
	Item  ClosetItemView `json:"item"`
	Score int64          `json:"score"`
}

Favorited is a new closet item and the score left.

type InspectRestoreInput added in v1.1.0

type InspectRestoreInput struct {
	UploadID string `json:"uploadId,omitempty" maxLength:"128"`
	Path     string `json:"path,omitempty" maxLength:"1024"`
}

InspectRestoreInput inspects an uploaded or server-local SkinLoom backup archive.

type InspectRestoreResult added in v1.1.0

type InspectRestoreResult struct {
	Manifest      BackupManifestView `json:"manifest"`
	HasConfig     bool               `json:"hasConfig"`
	ConfigDialect string             `json:"configDialect,omitempty"`
	ConfigStorage string             `json:"configStorage,omitempty"`
	Warnings      []string           `json:"warnings"`
}

InspectRestoreResult summarizes an inspected backup archive.

type JobsStatus

type JobsStatus struct {
	Pending       int        `json:"pending"`
	Overdue       int        `json:"overdue" doc:"Pending for over a minute past their time"`
	Failed        int        `json:"failed" doc:"Given up after the last retry, kept for 7 days"`
	OldestOverdue *time.Time `json:"oldestOverdue,omitempty"`
}

type LocaleInfo

type LocaleInfo struct {
	Code string `json:"code" example:"zh-CN"`
	Name string `json:"name" example:"简体中文"`
}

LocaleInfo describes a supported UI language.

type MailConfigInput added in v1.1.0

type MailConfigInput struct {
	Driver     string `json:"driver,omitempty" enum:"none,smtp,log,"`
	From       string `json:"from,omitempty" maxLength:"255"`
	Host       string `json:"host,omitempty" maxLength:"255"`
	Port       int    `json:"port,omitempty"`
	Username   string `json:"username,omitempty" maxLength:"255"`
	Password   string `json:"password,omitempty" maxLength:"1024"`
	Encryption string `json:"encryption,omitempty" enum:"tls,starttls,none,"`
}

MailConfigInput defines optional SMTP/log mail settings during setup.

type MailStatus

type MailStatus struct {
	Driver string `json:"driver"`
	Ready  bool   `json:"ready" doc:"Mail is set up and site.url is set: verification and password reset work"`
}

type MarkedRead

type MarkedRead struct {
	Count int `json:"count" doc:"How many were unread"`
}

MarkedRead answers marking everything read.

type MenuItem struct {
	ID    string `json:"id"`
	Title string `json:"title" doc:"Message key resolved by the frontend, or literal text"`
	Href  string `json:"href"`
	Icon  string `json:"icon,omitempty"`
	Order int    `json:"order"`
}

MenuItem is one navigation entry. Modules and plugins contribute these.

type NewPersonalToken

type NewPersonalToken struct {
	Info  PersonalTokenView `json:"info"`
	Token string            `json:"token"`
}

NewPersonalToken is a created token: the token itself is shown only now.

type NotificationPage

type NotificationPage struct {
	Notifications []NotificationView `json:"notifications"`
	Next          int64              `json:"next" doc:"Pass as before= for the next page; 0 = last page"`
	Unread        int                `json:"unread"`
}

NotificationPage is one page of the inbox.

type NotificationView

type NotificationView struct {
	ID           int64     `json:"id"`
	Title        string    `json:"title"`
	ContentHTML  string    `json:"contentHtml" doc:"Rendered from Markdown: no raw HTML, no script links"`
	Read         bool      `json:"read"`
	Announcement bool      `json:"announcement" doc:"A copy of a message sent to many users"`
	CreatedAt    time.Time `json:"createdAt"`
}

NotificationView is one message in the signed-in user's inbox.

type OAuthClientList

type OAuthClientList struct {
	Clients []OAuthClientView `json:"clients"`
}

OAuthClientList is your applications.

type OAuthClientRef

type OAuthClientRef struct {
	ID    int64  `json:"id"`
	Name  string `json:"name"`
	Owner string `json:"owner" doc:"The nickname of who registered it"`
}

OAuthClientRef is an application as users see it.

type OAuthClientSecret

type OAuthClientSecret struct {
	Client OAuthClientView `json:"client"`
	Secret string          `json:"secret" doc:"Empty for a public client"`
}

OAuthClientSecret is a new application or secret: the secret is shown only now.

type OAuthClientView

type OAuthClientView struct {
	ID           int64     `json:"id" doc:"The client_id"`
	Name         string    `json:"name"`
	RedirectURIs []string  `json:"redirectUris"`
	Confidential bool      `json:"confidential" doc:"Has a secret; public clients must use PKCE"`
	CreatedAt    time.Time `json:"createdAt"`
}

OAuthClientView is one of your applications.

type OAuthGrantList

type OAuthGrantList struct {
	Grants []OAuthGrantView `json:"grants"`
}

OAuthGrantList is the applications you allowed.

type OAuthGrantView

type OAuthGrantView struct {
	Client    OAuthClientRef `json:"client"`
	Scopes    []string       `json:"scopes"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt" doc:"Last allowed"`
}

OAuthGrantView is an application you allowed.

type OAuthScopes

type OAuthScopes struct {
	Scopes []oauth.Scope `json:"scopes"`
}

OAuthScopes are the scopes applications and tokens can be given.

type OverviewDay

type OverviewDay struct {
	Date          string `json:"date" doc:"YYYY-MM-DD"`
	Registrations int    `json:"registrations"`
	Uploads       int    `json:"uploads"`
}

OverviewDay is one day of the admin overview chart, in the site's time zone.

type ParseBSEnvInput added in v1.1.0

type ParseBSEnvInput struct {
	Content string `json:"content,omitempty" maxLength:"262144"`
	Path    string `json:"path,omitempty" maxLength:"1024"`
}

ParseBSEnvInput parses a BS .env file from content or server path.

type ParseBSEnvResult added in v1.1.0

type ParseBSEnvResult struct {
	EnvID string     `json:"envId,omitempty"`
	Env   bs.EnvInfo `json:"env"`
}

ParseBSEnvResult returns sanitized metadata parsed from BS .env.

type PersonalTokenList

type PersonalTokenList struct {
	Tokens []PersonalTokenView `json:"tokens"`
}

PersonalTokenList is your personal access tokens.

type PersonalTokenView

type PersonalTokenView struct {
	ID         int64      `json:"id"`
	Name       string     `json:"name"`
	Scopes     []string   `json:"scopes"`
	CreatedAt  time.Time  `json:"createdAt"`
	ExpiresAt  *time.Time `json:"expiresAt" doc:"null: never"`
	LastUsedAt *time.Time `json:"lastUsedAt"`
}

PersonalTokenView is one of your personal access tokens.

type PlayerCreated

type PlayerCreated struct {
	Player PlayerView `json:"player"`
	Score  int64      `json:"score"`
}

PlayerCreated is a new player and the score left.

type PlayerDeleted

type PlayerDeleted struct {
	Refunded int64 `json:"refunded"`
}

PlayerDeleted reports what deleting a player gave back.

type PlayerRules

type PlayerRules struct {
	NameRule  string `json:"nameRule" enum:"official,cjk,utf8,custom"`
	NameRegex string `json:"nameRegexp,omitempty" doc:"For nameRule custom"`
	MinLength int    `json:"minLength"`
	MaxLength int    `json:"maxLength"`
	Cost      int64  `json:"cost" doc:"Score to create a player"`
	Refund    bool   `json:"refund" doc:"Deleting a player gives back what it cost"`
}

PlayerRules are the player rules of the site.

type PlayerView

type PlayerView struct {
	ID        int64        `json:"id"`
	Name      string       `json:"name"`
	UUID      string       `json:"uuid" doc:"32 hex digits, no dashes"`
	Skin      *WornTexture `json:"skin,omitempty"`
	Cape      *WornTexture `json:"cape,omitempty"`
	UpdatedAt time.Time    `json:"updatedAt"`
}

PlayerView is one of the signed-in user's players.

type PluginFormField added in v1.1.0

type PluginFormField struct {
	PluginID    string   `json:"pluginId"`
	Name        string   `json:"name"`
	Type        string   `json:"type"`
	Label       string   `json:"label"`
	Description string   `json:"description,omitempty"`
	Placeholder string   `json:"placeholder,omitempty"`
	Required    bool     `json:"required,omitempty"`
	MaxLength   int      `json:"maxLength,omitempty"`
	Options     []string `json:"options,omitempty"`
}

PluginFormField describes an extension field declared by a plugin for a host form scope.

type PluginFrontend

type PluginFrontend struct {
	ID        string                 `json:"id"`
	Kind      string                 `json:"kind,omitempty"`
	Version   string                 `json:"version"`
	Rev       string                 `json:"rev,omitempty"`
	Name      string                 `json:"name,omitempty"`
	Entry     string                 `json:"entry,omitempty"`
	Style     string                 `json:"style,omitempty"`
	Slots     []string               `json:"slots,omitempty"`
	Blocks    []plugin.FrontendBlock `json:"blocks,omitempty"`
	Overrides []string               `json:"overrides,omitempty"`
	Settings  map[string]any         `json:"settings,omitempty"`
	Messages  map[string]string      `json:"messages,omitempty"`
}

PluginFrontend tells the frontend which enabled plugin bundles and metadata to load.

type PurgeResult

type PurgeResult struct {
	URLs int `json:"urls" doc:"URLs the CDN was asked to drop"`
}

PurgeResult is what a manual purge did.

type PutUploadChunkResult added in v1.1.0

type PutUploadChunkResult struct {
	Received int64 `json:"received"`
	Complete bool  `json:"complete"`
}

PutUploadChunkResult reports chunk progress.

type QuickSetupInput added in v1.1.0

type QuickSetupInput struct {
	Token    string
	Email    string
	Nickname string
	Password string
	SiteName string
	SiteURL  string
	Meta     account.RequestMeta
}

QuickSetupInput is the single-step POST /api/v1/setup payload handled via SetupController.

type ReportPage

type ReportPage struct {
	Reports []ReportView `json:"reports"`
	Next    int64        `json:"next" doc:"Pass as before= for the next page; 0 = last page"`
}

ReportPage is one page of the signed-in user's reports.

type ReportView

type ReportView struct {
	ID        int64        `json:"id"`
	Texture   *TextureView `json:"texture,omitempty" doc:"Absent once the texture is deleted or no longer public"`
	Reason    string       `json:"reason"`
	Status    string       `json:"status" enum:"pending,resolved,rejected"`
	Action    string       `json:"action,omitempty" enum:"delete,ban,reject," doc:"What the reviewer did"`
	CreatedAt time.Time    `json:"createdAt"`
	HandledAt *time.Time   `json:"handledAt,omitempty"`
}

ReportView is a report as its reporter sees it.

type Reported

type Reported struct {
	Report ReportView `json:"report"`
	Score  int64      `json:"score" doc:"Your score after score.reporter_modification"`
}

Reported answers a new report.

type RuntimeInfo

type RuntimeInfo struct {
	Started time.Time
	Role    string // server.role
	Web     string // web.mode
	Storage string // storage.driver
}

RuntimeInfo is how this process was started.

type ScoreRates

type ScoreRates struct {
	PerStorage        int64 `json:"perStorage" doc:"Per KB of a public upload"`
	PrivatePerStorage int64 `json:"privatePerStorage" doc:"Per KB of a private upload"`
	PerClosetItem     int64 `json:"perClosetItem"`
	AwardPerTexture   int64 `json:"awardPerTexture" doc:"Earned for a public upload"`
	// Reports (score.reporter_*): what submitting one changes, and the reward when
	// it is upheld.
	ReporterModification int64 `json:"reporterModification" doc:"Negative: a report costs this much; positive: earns it"`
	ReporterReward       int64 `json:"reporterReward"`
}

ScoreRates are the score settings an uploader needs to see the cost in advance.

type SentNotification

type SentNotification struct {
	Kind string `json:"kind" enum:"announcement,notification" doc:"announcement: delivered to each user as they next open their inbox"`
	ID   int64  `json:"id"`
}

SentNotification answers an administrator's send.

type ServerInfo

type ServerInfo struct {
	Name    string `json:"name" example:"SkinLoom"`
	Version string `json:"version"`
}

ServerInfo identifies the running backend.

type ServerStatus

type ServerStatus struct {
	Version   string    `json:"version"`
	Commit    string    `json:"commit,omitempty"`
	BuildDate string    `json:"buildDate,omitempty"`
	Go        string    `json:"go"`
	OS        string    `json:"os"`
	Arch      string    `json:"arch"`
	Role      string    `json:"role" doc:"server.role"`
	Web       string    `json:"web" doc:"web.mode"`
	StartedAt time.Time `json:"startedAt"`
}

type SessionView

type SessionView struct {
	ID         string    `json:"id"`
	IP         string    `json:"ip"`
	UserAgent  string    `json:"userAgent"`
	CreatedAt  time.Time `json:"createdAt"`
	LastSeenAt time.Time `json:"lastSeenAt"`
	Current    bool      `json:"current" doc:"The session making this request"`
}

SessionView is one signed-in device.

type SettingView

type SettingView struct {
	Key     string `json:"key"`
	Type    string `json:"type"`
	Value   any    `json:"value" doc:"null for a secret setting; secret parts of other values are replaced by ********"`
	Default any    `json:"default"`
	IsSet   bool   `json:"isSet" doc:"false when the default is in effect"`
	Public  bool   `json:"public"`
	Secret  bool   `json:"secret" doc:"Write-only: the value is never sent back, leave the key out to keep it"`
	// Superadmin settings put code into every page; other administrators see them read-only.
	Superadmin bool   `json:"superadmin"`
	Enum       []any  `json:"enum,omitempty" doc:"The allowed values"`
	Min        *int64 `json:"min,omitempty"`
	Max        *int64 `json:"max,omitempty"`
	Doc        string `json:"doc"`
}

SettingView is one setting as shown in the admin panel.

type SettingsList

type SettingsList struct {
	Version  int64         `json:"version"`
	Settings []SettingView `json:"settings"`
}

SettingsList is the admin view of all settings.

type SetupController added in v1.1.0

type SetupController interface {
	Status(ctx context.Context) (needsSetup bool, lockedByEnv bool, err error)
	CompleteQuickSetup(ctx context.Context, in QuickSetupInput) (*ent.User, *account.NewSession, error)
	CreateSession(ctx context.Context, token string, clientIP string) (cookieToken string, state *SetupState, err error)
	ValidateSession(cookieToken string) bool
	GetState(ctx context.Context, req SetupStateRequest) (*SetupState, error)
	TestDB(ctx context.Context, in DBConfigInput) (*TestDBResult, error)
	TestStorage(ctx context.Context, in StorageConfigInput) (*TestStorageResult, error)
	TestMail(ctx context.Context, in TestMailInput, locale string) (*TestMailResult, error)
	ConnectExisting(ctx context.Context, in ConnectExistingInput) (*ConnectExistingResult, error)
	CompleteWizard(ctx context.Context, in CompleteWizardInput) (*ent.User, *account.NewSession, error)
	CreateUpload(ctx context.Context, in CreateUploadInput) (*CreateUploadResult, error)
	PutUploadChunk(ctx context.Context, uploadID string, offset int64, body io.Reader) (*PutUploadChunkResult, error)
	ParseBSEnv(ctx context.Context, in ParseBSEnvInput) (*ParseBSEnvResult, error)
	TestBSSource(ctx context.Context, in BSSourceInput) (*TestBSSourceResult, error)
	StartBSDryRun(ctx context.Context, in BSDryRunInput) (*StartJobResult, error)
	StartBSImport(ctx context.Context, in BSImportInput) (*StartJobResult, error)
	InspectRestore(ctx context.Context, in InspectRestoreInput) (*InspectRestoreResult, error)
	StartRestore(ctx context.Context, in ExecuteRestoreInput) (*StartJobResult, error)
	GetJob(ctx context.Context, jobID string) (*SetupJobView, error)
	GetJobReportText(ctx context.Context, jobID string) ([]byte, string, error)
}

SetupController coordinates Pre-Core setup, infrastructure probes, backup restore, Blessing Skin migration, and atomic transition to Running Mode.

type SetupFieldError added in v1.1.0

type SetupFieldError struct {
	Field   string
	Message string
}

SetupFieldError names one invalid field in a setup request body.

type SetupJobView added in v1.1.0

type SetupJobView struct {
	ID         string        `json:"id"`
	Kind       string        `json:"kind" enum:"bs_dry_run,bs_import,restore"`
	Status     string        `json:"status" enum:"running,succeeded,failed"`
	Stage      string        `json:"stage"`
	Percent    int           `json:"percent"`
	Done       int           `json:"done"`
	Total      int           `json:"total"`
	Message    string        `json:"message,omitempty"`
	Error      string        `json:"error,omitempty"`
	RedirectTo string        `json:"redirectTo,omitempty"`
	Report     *BSReportView `json:"report,omitempty"`
	HasReport  bool          `json:"hasReport"`
	UpdatedAt  time.Time     `json:"updatedAt"`
}

SetupJobView reports async dry-run, import, or restore progress and outcome.

type SetupProbeError added in v1.1.0

type SetupProbeError struct {
	Detail string
}

SetupProbeError carries a gateway/upstream diagnostic failure (e.g. SMTP test error).

func (*SetupProbeError) Error added in v1.1.0

func (e *SetupProbeError) Error() string

type SetupRateLimitError added in v1.1.0

type SetupRateLimitError struct {
	RetryAfter time.Duration
}

SetupRateLimitError carries the retry window when setup token attempts are throttled.

func (*SetupRateLimitError) Error added in v1.1.0

func (e *SetupRateLimitError) Error() string

type SetupState added in v1.1.0

type SetupState struct {
	NeedsSetup      bool           `json:"needsSetup"`
	InContainer     bool           `json:"inContainer"`
	EnvLocked       EnvLockedInfo  `json:"envLocked"`
	Database        DBSummary      `json:"database"`
	Storage         StorageSummary `json:"storage"`
	TrustedProxies  []string       `json:"trustedProxies"`
	DetectedProxy   *DetectedProxy `json:"detectedProxy,omitempty"`
	SuggestedURL    string         `json:"suggestedSiteUrl"`
	DefaultTimezone string         `json:"defaultTimezone"`
	MaxUploadBytes  int64          `json:"maxUploadBytes"`
	ActiveJobID     string         `json:"activeJobId,omitempty"`
	InitDBError     string         `json:"initDbError,omitempty"`
}

SetupState is the sanitized setup environment returned to an authenticated wizard session.

type SetupStateRequest added in v1.1.0

type SetupStateRequest struct {
	Client         realip.Info
	PeerIP         string
	HasForwarded   bool
	ForwardedHost  string
	ForwardedProto string
	LocalDataDir   string
}

SetupStateRequest carries raw HTTP proxy probe details for GetState.

type SetupValidationError added in v1.1.0

type SetupValidationError struct {
	Fields []SetupFieldError
}

SetupValidationError carries per-field 422 validation errors.

func (*SetupValidationError) Error added in v1.1.0

func (e *SetupValidationError) Error() string

type SignInfo

type SignInfo struct {
	NextAt *time.Time `json:"nextAt,omitempty" doc:"When the next check-in is possible; absent = now"`
	Min    int64      `json:"min"`
	Max    int64      `json:"max"`
	Daily  bool       `json:"daily" doc:"Once per calendar day instead of every gapHours"`
	Gap    int64      `json:"gapHours"`
}

SignInfo is the check-in state of the signed-in user.

type SignResult

type SignResult struct {
	Gained int64     `json:"gained"`
	Score  int64     `json:"score"`
	NextAt time.Time `json:"nextAt" doc:"When the next check-in is possible"`
}

SignResult is a check-in.

type SiteInfo

type SiteInfo struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	URL          string `json:"url" doc:"Canonical public URL; empty when not configured"`
	Announcement string `json:"announcement" doc:"Markdown"`
	// AnnouncementHTML is Announcement rendered: no raw HTML, no script links.
	AnnouncementHTML string `json:"announcementHtml"`
	Favicon          string `json:"favicon" doc:"Tab icon URL; empty = the built-in one"`
	// CopyrightHTML is the footer text (site.copyright) rendered like the announcement;
	// empty = © year and the site name.
	CopyrightHTML string `json:"copyrightHtml"`
	Keywords      string `json:"keywords" doc:"meta keywords"`
}

SiteInfo is the public, localized site identity.

type SiteStats

type SiteStats struct {
	Users    int `json:"users" doc:"Accounts that are not deleted"`
	Players  int `json:"players"`
	Textures int `json:"textures" doc:"Public textures"`
}

SiteStats are the public totals of the home page's stats block.

type SocialLinkView

type SocialLinkView struct {
	Provider     string     `json:"provider"`
	ProviderName string     `json:"providerName" doc:"Empty when the provider is no longer configured"`
	ProviderType string     `json:"providerType" doc:"github, microsoft, oidc; empty when no longer configured"`
	Name         string     `json:"name" doc:"The account at the provider (a login or an email)"`
	CreatedAt    time.Time  `json:"createdAt"`
	LastUsedAt   *time.Time `json:"lastUsedAt,omitempty"`
}

SocialLinkView is a provider account linked to the user.

type SocialLinks struct {
	Links     []SocialLinkView     `json:"links"`
	Providers []SocialProviderInfo `json:"providers"`
}

SocialLinks are the user's linked accounts and the providers they can link.

type SocialPending

type SocialPending struct {
	Provider      string `json:"provider"`
	ProviderName  string `json:"providerName"`
	ProviderType  string `json:"providerType"`
	Name          string `json:"name" doc:"The account at the provider"`
	Email         string `json:"email" doc:"May be empty"`
	EmailVerified bool   `json:"emailVerified" doc:"Keeping this address makes it verified without a mail"`
	Nickname      string `json:"nickname" doc:"Suggested nickname"`
	// Registration says whether a new account can be created; otherwise the person can
	// only link the provider account to an account they sign in to.
	Registration string    `json:"registration" enum:"open,closed"`
	Next         string    `json:"next" doc:"Where to go once signed in; empty = /user"`
	ExpiresAt    time.Time `json:"expiresAt"`
}

SocialPending is a provider account that is not linked to any account yet.

type SocialProviderInfo

type SocialProviderInfo struct {
	ID   string `json:"id" example:"github"`
	Name string `json:"name" example:"GitHub"`
	Type string `json:"type" enum:"github,microsoft,oidc"`
}

SocialProviderInfo is a sign-in provider as shown on the sign-in page.

type SocialRedirect

type SocialRedirect struct {
	URL string `json:"url" doc:"The provider's sign-in page"`
}

SocialRedirect is where to send the browser.

type StartJobResult added in v1.1.0

type StartJobResult struct {
	JobID string `json:"jobId"`
}

StartJobResult returns the created async job id.

type StatusCheck

type StatusCheck struct {
	ID    string `json:"id" enum:"database,migrations,jobs_overdue,jobs_failed,mail,site_url"`
	Level string `json:"level" enum:"ok,warn,error"`
}

StatusCheck is one finding. The frontend words it by ID.

type StorageConfigInput added in v1.1.0

type StorageConfigInput struct {
	UseEnv    bool   `json:"useEnv,omitempty"`
	Driver    string `json:"driver,omitempty" enum:"local,s3,"`
	Path      string `json:"path,omitempty" maxLength:"512"`
	Endpoint  string `json:"endpoint,omitempty" maxLength:"255"`
	Bucket    string `json:"bucket,omitempty" maxLength:"255"`
	Region    string `json:"region,omitempty" maxLength:"128"`
	AccessKey string `json:"accessKey,omitempty" maxLength:"255"`
	SecretKey string `json:"secretKey,omitempty" maxLength:"1024"`
	Prefix    string `json:"prefix,omitempty" maxLength:"255"`
	Insecure  bool   `json:"insecure,omitempty"`
	PathStyle bool   `json:"pathStyle,omitempty"`
	PublicURL string `json:"publicUrl,omitempty" maxLength:"512"`
}

StorageConfigInput defines local or S3 storage parameters for probing or saving.

type StorageStatus

type StorageStatus struct {
	Driver string `json:"driver" enum:"local,s3"`
	Files  int    `json:"files"`
	Bytes  int64  `json:"bytes"`
}

type StorageSummary added in v1.1.0

type StorageSummary struct {
	Driver    string `json:"driver"`
	Path      string `json:"path,omitempty"`
	Endpoint  string `json:"endpoint,omitempty"`
	Bucket    string `json:"bucket,omitempty"`
	Region    string `json:"region,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	PathStyle bool   `json:"pathStyle,omitempty"`
	Insecure  bool   `json:"insecure,omitempty"`
	PublicURL string `json:"publicUrl,omitempty"`
}

StorageSummary holds non-secret initial storage hints.

type SystemStatus

type SystemStatus struct {
	Server   ServerStatus   `json:"server"`
	Database DatabaseStatus `json:"database"`
	Storage  StorageStatus  `json:"storage"`
	Jobs     JobsStatus     `json:"jobs"`
	Mail     MailStatus     `json:"mail"`
	Config   ConfigStatus   `json:"config"`
	Checks   []StatusCheck  `json:"checks" doc:"Things worth a look; level ok when nothing is wrong"`
}

SystemStatus is the admin panel's system status page (02 F40). It names the database engine and version but never the connection string or user (BS showed the DB user name).

type TestBSSourceResult added in v1.1.0

type TestBSSourceResult struct {
	OK          bool             `json:"ok"`
	Counts      bs.SourceSummary `json:"counts"`
	Warning     string           `json:"warning,omitempty"`
	ErrorDetail string           `json:"errorDetail,omitempty"`
}

TestBSSourceResult reports read-only counts from BS.

type TestDBResult added in v1.1.0

type TestDBResult struct {
	OK          bool   `json:"ok"`
	Dialect     string `json:"dialect,omitempty"`
	Version     string `json:"version,omitempty"`
	State       string `json:"state" enum:"empty,skinloom_installed,suspected_bs,missing_db,error"`
	Summary     string `json:"summary,omitempty"`
	Users       int    `json:"users,omitempty"`
	Textures    int    `json:"textures,omitempty"`
	Players     int    `json:"players,omitempty"`
	HintSQL     string `json:"hintSql,omitempty"`
	ErrorDetail string `json:"errorDetail,omitempty"`
}

TestDBResult is returned by POST /api/v1/setup/test-db.

type TestMailInput added in v1.1.0

type TestMailInput struct {
	Mail MailConfigInput `json:"mail"`
	To   string          `json:"to" maxLength:"255"`
	Site string          `json:"siteName,omitempty" maxLength:"64"`
}

TestMailInput requests a synchronous test email during setup.

type TestMailResult added in v1.1.0

type TestMailResult struct {
	OK          bool   `json:"ok"`
	Summary     string `json:"summary,omitempty"`
	ErrorDetail string `json:"errorDetail,omitempty"`
}

TestMailResult is returned by POST /api/v1/setup/test-mail.

type TestStorageResult added in v1.1.0

type TestStorageResult struct {
	OK          bool   `json:"ok"`
	Driver      string `json:"driver"`
	Summary     string `json:"summary,omitempty"`
	ErrorDetail string `json:"errorDetail,omitempty"`
}

TestStorageResult is returned by POST /api/v1/setup/test-storage.

type TextureDetail

type TextureDetail struct {
	TextureView
	InCloset bool `json:"inCloset" doc:"In the signed-in user's closet"`
	Mine     bool `json:"mine" doc:"Uploaded by the signed-in user"`
}

TextureDetail is a texture as shown on its page.

type TexturePage

type TexturePage struct {
	Textures []TextureView `json:"textures"`
	Next     string        `json:"next" doc:"Pass as cursor= for the next page; empty = last page"`
}

TexturePage is one page of the skin library.

type TextureRules

type TextureRules struct {
	MaxSizeKB     int64      `json:"maxSizeKb"`
	MaxWidth      int        `json:"maxWidth"`
	NameRule      string     `json:"nameRule,omitempty" doc:"Regular expression names must match (RE2)"`
	AllowDownload bool       `json:"allowDownload"`
	Rates         ScoreRates `json:"rates"`
	ContentPolicy string     `json:"contentPolicy,omitempty" doc:"Markdown, in the request's language"`
}

TextureRules are the upload rules of the site.

type TextureView

type TextureView struct {
	ID        int64         `json:"id"`
	Name      string        `json:"name"`
	Type      string        `json:"type" enum:"steve,alex,cape" doc:"steve and alex are skins (classic and slim arms)"`
	Hash      string        `json:"hash" doc:"SHA-256 of the file; the image is at /textures/{hash}"`
	Size      int64         `json:"size" doc:"Bytes"`
	Public    bool          `json:"public"`
	Likes     int           `json:"likes" doc:"Closets holding it"`
	Uploader  *UploaderView `json:"uploader,omitempty" doc:"Absent when the uploader's account is gone"`
	CreatedAt time.Time     `json:"createdAt"`
}

TextureView is a texture in the skin library.

type ThemeView

type ThemeView struct {
	ID          string                   `json:"id"`
	Version     string                   `json:"version"`
	Name        map[string]string        `json:"name"`
	Description map[string]string        `json:"description,omitempty"`
	Source      string                   `json:"source"`
	Active      bool                     `json:"active"`
	Extends     string                   `json:"extends,omitempty"`
	Screenshot  string                   `json:"screenshot,omitempty"`
	ColorScheme string                   `json:"colorScheme"`
	Tokens      theme.Tokens             `json:"tokens"`
	Layout      map[string]string        `json:"layout"`
	Home        []theme.Block            `json:"home" doc:"The theme's home page, used while home.blocks is null"`
	Overrides   []string                 `json:"overrides,omitempty"`
	HasWeb      bool                     `json:"hasWeb,omitempty"`
	WebTrusted  bool                     `json:"webTrusted,omitempty"`
	Settings    map[string]theme.Setting `json:"settings,omitempty"`
	Error       string                   `json:"error,omitempty"`
}

ThemeView is one installed theme, with what it brings before the administrator's overrides: the appearance page shows these as the defaults.

type Unfavorited

type Unfavorited struct {
	Refunded int64 `json:"refunded"`
}

Unfavorited reports what removing a closet item gave back.

type UnreadCount

type UnreadCount struct {
	Unread int `json:"unread"`
}

UnreadCount is how many notifications are unread.

type UploadView

type UploadView struct {
	Texture   TextureView `json:"texture"`
	Duplicate bool        `json:"duplicate" doc:"The same image was already in the library: this is that texture, and nothing was charged"`
	Cost      int64       `json:"cost" doc:"Score spent; negative when the upload earned score"`
	Score     int64       `json:"score" doc:"The uploader's score afterwards"`
}

UploadView is the result of an upload.

type UploaderView

type UploaderView struct {
	ID       int64            `json:"id"`
	Nickname string           `json:"nickname"`
	Badges   []hook.UserBadge `json:"badges,omitempty"`
}

UploaderView is who uploaded a texture.

type UserPage

type UserPage struct {
	Users []AdminUserView `json:"users"`
	Next  int64           `json:"next" doc:"Pass as before= for the next page; 0 = last page"`
}

UserPage is one page of the user list.

type UserView

type UserView struct {
	ID            int64            `json:"id"`
	Email         string           `json:"email"`
	Nickname      string           `json:"nickname"`
	Role          string           `json:"role" enum:"user,admin,superadmin"`
	EmailVerified bool             `json:"emailVerified"`
	HasPassword   bool             `` /* 139-byte string literal not displayed */
	Locale        string           `json:"locale" doc:"Preferred UI language; empty = follow the browser"`
	Score         int64            `json:"score"`
	AvatarID      *int64           `json:"avatarTextureId,omitempty" doc:"The skin whose head is the avatar, /avatar/user/{id}"`
	Badges        []hook.UserBadge `json:"badges,omitempty" doc:"Custom badges injected by plugins"`
	CreatedAt     time.Time        `json:"createdAt"`
}

UserView is the signed-in user as shown to themselves.

type WornTexture

type WornTexture struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
	Type string `json:"type" enum:"steve,alex,cape"`
	Hash string `json:"hash"`
}

WornTexture is a texture a player wears.

type YggdrasilTokens

type YggdrasilTokens struct {
	Tokens int    `json:"tokens"`
	APIURL string `json:"apiUrl" doc:"The address to give authlib-injector"`
}

YggdrasilTokens is how many game launchers are signed in to the account.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL