Documentation
¶
Overview ¶
Package modules runs the plugins, none of which is compiled into the server: which version is in use, why, and getting a newer or older one. docs/MODULES.md has the design.
A server with no modules works, and says what each missing one would add. A version is used only while it is signed, in range for this server and behaving, so nothing here can stop the server from running.
Index ¶
- Constants
- Variables
- func Fingerprint(key ed25519.PublicKey) string
- func ForgetVersion(dir, id, ver, server string) (now string, err error)
- func ForkRefusal() string
- func IsHidden(name string) bool
- func Offers() map[string]int
- func OlderServerWarning(name, version, madeFor, server string) string
- func PermissionWords(p string) (name, words string)
- func ProtectServer()
- func ProxyToService(c *service.Conn, w http.ResponseWriter, r *http.Request, path string, ...)
- func ProxyToServiceWith(c *service.Conn, w http.ResponseWriter, r *http.Request, path string, ...)
- func ReadInstalledState(dir string) (map[string]InstalledState, error)
- func ReportTasksTo(r *tasks.Registry)
- func RunSandboxed(args []string) int
- func SandboxNetworkProgram(cmd *exec.Cmd, log *slog.Logger)
- func ServerManifests() [][]byte
- func WithIdentity(ctx context.Context, user int64, admin bool) context.Context
- type Attached
- type CDs
- type CatalogInfo
- type Config
- type Entry
- type ErrBadOverride
- type ErrInUse
- type ErrMissing
- type ErrModuleMissing
- type ErrNeedsConfirm
- type ErrNeedsOverride
- type ErrNoVersion
- type ErrOlderServer
- type ErrResting
- type ErrStoreAddress
- type Event
- type Failure
- type FileBrowser
- type Fit
- type InUse
- type InstalledState
- type ItemDetail
- type ItemsAnswer
- type ItemsRequest
- type LibraryType
- type ListOptions
- type Listing
- type Manager
- func (m *Manager) AddModule(id string) error
- func (m *Manager) AddModuleOlder(id string, confirmOlder bool) error
- func (m *Manager) Attach(id string, callTimeout time.Duration) *Attached
- func (m *Manager) Call(id, method string, params, out any) ([]byte, error)
- func (m *Manager) Capability(id, name string) []string
- func (m *Manager) Check(ctx context.Context, maxAge time.Duration) Report
- func (m *Manager) CheckEnabled() bool
- func (m *Manager) ClearSource(id string) error
- func (m *Manager) Close()
- func (m *Manager) DiscardUpload(token string, by int64) error
- func (m *Manager) DropPending(id string) error
- func (m *Manager) HostModule(token string) (string, bool)
- func (m *Manager) IconFile(ctx context.Context, id string) (string, error)
- func (m *Manager) Install(id string) error
- func (m *Manager) InstallOlder(id string, confirmOlder bool) error
- func (m *Manager) InstallUpload(token string, by int64, accept *OverrideAccept) error
- func (m *Manager) InstallVersion(id, ver string, confirm bool) error
- func (m *Manager) InstallVersionOlder(id, ver string, confirm, confirmOlder bool) error
- func (m *Manager) InstallVersionWith(id, ver string, confirm bool, accept *OverrideAccept) error
- func (m *Manager) InstallVersionWithOlder(id, ver string, confirm, confirmOlder bool, accept *OverrideAccept) error
- func (m *Manager) Installed(id string) bool
- func (m *Manager) Integration(id string) *wittymodule.Integration
- func (m *Manager) Integrations() ([]InUse, uint64)
- func (m *Manager) Libraries(id string) []string
- func (m *Manager) LibraryAllowed(libType string) error
- func (m *Manager) LibraryTypes() []LibraryType
- func (m *Manager) LogTopics(id string) []string
- func (m *Manager) MadeForOlder(id, ver string) bool
- func (m *Manager) Missing(id string) error
- func (m *Manager) ModuleReport(id string, working bool, reason string) error
- func (m *Manager) Name(id string) string
- func (m *Manager) Notices(id string) ([]byte, bool)
- func (m *Manager) OlderThanInUse(id, ver string) bool
- func (m *Manager) OnServiceNotify(id, method string, fn func(json.RawMessage)) error
- func (m *Manager) Pin(id string) error
- func (m *Manager) Program(id string) (path, version string, ok bool)
- func (m *Manager) ProgramCommand(id string) (path string, args []string, version string, ok bool)
- func (m *Manager) ReinstallNow(ctx context.Context, id string) error
- func (m *Manager) RemoveModule(id string, libraries map[string][]string) error
- func (m *Manager) RemoveOverride(id string, libraries map[string][]string) error
- func (m *Manager) Report() Report
- func (m *Manager) ReportBrowserFailure(id, ver, reason string, admin bool) error
- func (m *Manager) ReportFailure(id, ver, reason string) error
- func (m *Manager) ReportWorking(id, ver string)
- func (m *Manager) Requires(id string) []string
- func (m *Manager) Resting(id string) error
- func (m *Manager) Rollback(id string) error
- func (m *Manager) Run(ctx context.Context)
- func (m *Manager) RunningDownload(id string) bool
- func (m *Manager) ServiceConn(id string) (*service.Conn, error)
- func (m *Manager) ServiceProxy(id string, w http.ResponseWriter, r *http.Request, path string) error
- func (m *Manager) SetAutoUpdate(id string, on bool) error
- func (m *Manager) SetEnabled(id string, on bool, libraries map[string][]string) error
- func (m *Manager) SetHost(url string)
- func (m *Manager) SetInstalled(ids []string, libraries map[string][]string) error
- func (m *Manager) SetInstalledOlder(ids []string, libraries map[string][]string, confirmOlder []string) error
- func (m *Manager) SetLibraryLabel(libType, label string, taken map[string]string) error
- func (m *Manager) SetSource(id, repo, key, by string, confirm bool, accept *OverrideAccept) error
- func (m *Manager) SettingsChanged(id string, values map[string]any)
- func (m *Manager) StageUpload(u Upload) (*UploadInfo, error)
- func (m *Manager) ToLatest(id string) error
- func (m *Manager) UI(id string) *sdui.ModuleUI
- func (m *Manager) UIImage(id, name string) ([]byte, error)
- func (m *Manager) UIItems(id string, req ItemsRequest) (ItemsAnswer, error)
- func (m *Manager) UIs() ([]sdui.ModuleUI, uint64)
- func (m *Manager) Uninstall(id string, keepData bool) error
- func (m *Manager) Unpin(id string) error
- func (m *Manager) UploadOf(token string, by int64) (id, version string)
- func (m *Manager) UseBuiltin(id string) error
- func (m *Manager) UseServices()
- func (m *Manager) VersionInUse(id string) string
- func (m *Manager) Versions(id string) (VersionList, error)
- func (m *Manager) WebBundles() []WebBundle
- func (m *Manager) WebFile(id, ver, rel string) (path, hash string, err error)
- type ModuleRef
- type NeedKey
- type Offer
- type Override
- type OverrideAccept
- type OverrideInfo
- type PendingInfo
- type PermissionRow
- type Place
- type PreviewModule
- type Report
- type RouteKinds
- type Run
- type RunItem
- type SandboxInfo
- type Source
- type SourceInfo
- type Status
- type StoreInfo
- type StoreIntegration
- type StoreItem
- type StorePreview
- type StoreUI
- type StoreView
- type Stores
- func (s *Stores) Add(ctx context.Context, raw, key string, private bool, by string) (*StoreInfo, error)
- func (s *Stores) AutoUpdate()
- func (s *Stores) CheckAll(ctx context.Context) []string
- func (s *Stores) CurrentRun() *Run
- func (s *Stores) Detail(store, id string) (*ItemDetail, error)
- func (s *Stores) DismissRun()
- func (s *Stores) InstallPlan(id string) ([]RunItem, error)
- func (s *Stores) InstallWithNeeds(id, by string) (*Run, error)
- func (s *Stores) InstallWithNeedsOlder(id, by string, confirmOlder bool) (*Run, error)
- func (s *Stores) List() []StoreInfo
- func (s *Stores) Media(ctx context.Context, store, sha string) (path, contentType string, err error)
- func (s *Stores) OlderInPlan(plan []RunItem) []*ErrOlderServer
- func (s *Stores) Preview(ctx context.Context, raw, key string, private bool) (*StorePreview, error)
- func (s *Stores) Refresh(ctx context.Context, id string) error
- func (s *Stores) Remove(id, by string) error
- func (s *Stores) Run(ctx context.Context)
- func (s *Stores) SetEnabled(id string, on bool, by string) error
- func (s *Stores) UndoRun(by string) (*Run, error)
- func (s *Stores) UpdateAll(by string) (*Run, error)
- func (s *Stores) UpdateCount() int
- func (s *Stores) UseFork(store, id, by string, confirm bool, seen string, accept *OverrideAccept) error
- func (s *Stores) View() StoreView
- type StoresConfig
- type Tuners
- func (t Tuners) Discover(ctx context.Context, env tuner.Env) ([]tuner.Found, error)
- func (t Tuners) Drivers(ctx context.Context, env tuner.Env) ([]tuner.Driver, error)
- func (t Tuners) New(ctx context.Context, driver string, cfg tuner.Config, env tuner.Env) (tuner.Source, error)
- func (t Tuners) SecretFields(ctx context.Context, driver string, env tuner.Env) ([]string, error)
- type UIAdds
- type UIPage
- type Upload
- type UploadInfo
- type UploadProblem
- type VersionInfo
- type VersionList
- type VersionProblem
- type Viewer
- type WebBundle
Constants ¶
const ( ProblemMissing = "missing" // the folder or its manifest has gone ProblemSignature = "signature" // the signature or a file doesn't match ProblemVersion = "version" // it isn't for this server )
What can be wrong with an installed version, for choosing what to say.
const ( FailSignature = "signature" // not signed with the expected key, or changed since it was FailKey = "key-changed" // a store's signing key isn't the one that was agreed to FailNetwork = "network" FailDisk = "disk" FailTooOld = "too-old" // built for an older server than this one FailTooNew = "too-new" // needs a newer server than this one FailCrash = "crash" // its program wouldn't start, or kept stopping FailCorrupt = "corrupt" // its package is damaged FailMismatch = "mismatch" // the catalogue and the release disagree FailWithdrawn = "withdrawn" // its publisher took it back FailMissing = "missing" // nothing was found to install FailOther = "other" )
Kinds of failure.
const ( PhaseIdle = "idle" PhaseDownloading = "downloading" PhaseVerifying = "verifying" PhaseInstalling = "installing" PhaseFailed = "failed" // PhaseNeedsOverride: a download is held until an administrator overrides what it needs. PhaseNeedsOverride = "needs-override" )
Phases of an install, shown in Settings.
const ( StateAbsent = "absent" // no version of it is on this server StateBuiltin = "builtin" // a part of the server, which updates with it StateInstalled = "installed" // a version is in use StateFallback = "fallback" // a version was refused; see Notice StateDisabled = "disabled" // someone turned it off, and it is still on disk )
What a module is doing.
const ( OverrideIncomplete = "incomplete" OverrideOutOfRange = "out-of-range" OverrideLocalFile = "local-file" OverrideCustom = "custom" OverrideUntrustedKey = "untrusted-key" OverrideWeakSandbox = "weak-sandbox" OverrideUnsigned = "unsigned" )
Kinds of override.
const ( StatusStable = "stable" StatusBeta = "beta" StatusExperimental = "experimental" StatusIncomplete = "incomplete" )
Status of a version, as its manifest says (module API 4; absent in older manifests).
const ( SandboxNetwork = 1 << iota // it may have a network, and open devices for writing SandboxStrict // a fork: if a limit can't be applied, it doesn't run SandboxDevices // it may open devices for writing, as a graphics card is SandboxSaveArg // it may write to the folder after its -save argument SandboxWriteData // it may write to WITTYMODULE_DATA, and the folders in SandboxWriteEnv SandboxPrograms // it may start other programs )
What the launcher is asked to allow and to insist on.
const ( SandboxFull = "full" // everything the security model promises SandboxPartial = "partial" // most of it, and the words say what's missing SandboxLimited = "limited" // some limits, which aren't a sandbox SandboxUnconfined = "unconfined" // nothing that would stop it doing harm )
How well a helper is boxed in on this system.
const ( API = 5 MinAPI = 3 SDUIAPI = 4 IntegrationAPI = 5 )
The module API this server speaks. The numbers are the server's own: it decides what it takes, and the published wittymodule a server is built with may be older than the contract here (a test keeps wittymodule's from getting ahead of these).
API 4 makes a module's SDUI part of the module (docs/SDUI-MODULES.md): a version built for it carries sdui.json, checked against the catalogue before it is used, and a version without one is refused. Versions built for API 3 keep working as they did; one that carries sdui.json anyway has it used.
API 5 makes a module own its whole feature (docs/MODULES-API5.md): a version built for it carries integration.json, read by integration.go, saying which routes it answers, what its web bundle adds, its data and its lifecycle. The server keeps its own copy of a module's feature for versions built for 3 and 4 (legacyFor).
const ( // MethodSDUIItems answers one of the module's data sources: ItemsRequest in, // ItemsAnswer out. MethodSDUIItems = "sdui.items" // MethodSDUIImage answers a picture the module's cards show: {"name"} in, the // picture as the call's blob. MethodSDUIImage = "sdui.image" // MethodSettingsChanged tells a running helper its settings changed: {"values"}. MethodSettingsChanged = "settings.changed" )
Methods a helper answers for its SDUI.
const ( HeaderUser = "X-Witty-User" // the signed-in account's id HeaderAdmin = "X-Witty-Admin" // "1" for an administrator )
Headers a module's service is told who is asking by. Only the server sets them: whatever a browser sent under these names, or any other X-Witty- name, never reaches a module.
const ( FitOK = "ok" FitTooOld = "too-old" FitTooNew = "too-new" FitNoBuild = "no-build" FitNone = "no-version" FitLibrary = "library" FitWithdrawn = "withdrawn" // FitOlderServer: the only version that would run was made for an older server. It is // installed only when the request says confirmOlder, after its warning (Why) was shown. FitOlderServer = "older-server" )
Why a version can or can't be installed.
const ( RunQueued = "queued" RunWorking = "working" RunDone = "done" RunFailed = "failed" RunSkipped = "skipped" RunUndone = "undone" )
What a module in a run is doing.
const ( RunUpdateAll = "update-all" RunInstall = "install" )
Kinds of run.
const ( KindOfficial = "official" // from this project's catalogue KindFork = "fork" // another publisher's version of a module this server knows KindDev = "in-development" // a new kind of module, which can't be installed yet KindRefused = "refused" // it may never be replaced )
How a third-party store's module relates to this server.
const ForkWarning = "Only do this for someone you trust. A module from another publisher is their code running on your server, " +
"and neither this project nor anyone else has reviewed it. A helper or game runner can read what this server's account can read, " +
"which may include your media and this server's database. A reader bundle runs in the browser of whoever is reading, with their access, " +
"including yours as an admin. The signature only proves it came from whoever holds that key, not that it is safe. " +
"This server won't install updates from a fork by itself, and still refuses encrypted media whatever the fork says. " + forkLimits +
" Check the key's fingerprint with the publisher, somewhere other than the place you got the key."
ForkWarning is what someone agrees to before using a fork. It is said by the server, so every client that offers this says the same thing.
const LockForks = "WMS_NO_MODULE_FORKS"
LockForks keeps forks out whatever an administrator asks, for whoever runs the machine when that isn't the same person as this server's administrator.
const LogCapability = "logTopics"
LogCapability is where a module's manifest lists the advanced logging options it offers, each as "id|label|description". The module prints the detail when asked by WITTYMODULE_LOG_TOPICS. See docs/MODULES.md.
const MaxUIImage = 4 << 20
MaxUIImage bounds a picture a module answers.
const MaxUpload = 512 << 20
MaxUpload bounds a module archive uploaded by hand.
const MinModuleServer = wittymodule.FirstServer
MinModuleServer is the oldest server a module may have been built for.
const (
// OfficialStore is this project's catalogue, in everything that names a store.
OfficialStore = "official"
)
const PinBuiltin = "builtin"
PinBuiltin is the pin of a module kept on its built-in copy.
const PolicyWords = "Modules start with " + MinModuleServer + ": one built for an older server can't run, and those older alpha versions won't be fixed or updated. A later server may keep running a module built for " + MinModuleServer + " or after, if the module says it fits. That's a limited courtesy and it's unofficial: nothing is promised until the beta, which is when proper versioning for modules begins."
PolicyWords is the module compatibility policy, the same everywhere it is shown.
const RepairRoute = "/settings/repair"
RepairRoute is where the repair tools are, in Settings.
const SandboxFlag = "__module-sandbox"
SandboxFlag is what the server starts itself with to box a program in before it runs.
const SandboxWriteEnv = "WITTYMODULE_WRITE"
SandboxWriteEnv lists other folders a program may write to, as the environment.
const SettingsEnv = "WITTYMODULE_SETTINGS"
SettingsEnv names the environment variable a helper is started with: its server settings, as a JSON object.
const SignedFix = "WittyMediaServer's own modules will come signed; for a module from another store, ask its publisher for a signed build."
SignedFix is what to do when Windows' Smart App Control refuses a module's program.
Variables ¶
var ( // ErrFolderNotFound: there's no such folder. ErrFolderNotFound = errors.New("no such folder") // ErrFolderDenied: it isn't allowed to open that folder. ErrFolderDenied = errors.New("not allowed to open this folder") )
var ErrNoFile = errors.New("no such file")
ErrNoFile: the bundle has no such file, or it isn't the version in use.
var ErrNotRunning = errors.New("the module isn't running on this server")
ErrNotRunning is a module's SDUI call when the module has no helper running here.
var ErrRunBusy = errors.New("modules are already being changed; wait for that to finish")
ErrRunBusy: one run at a time.
var ErrStorePrivate = errors.New("that address is on this machine or your own network, which a store can't use unless you allow it")
ErrStorePrivate: the address is on this machine or a private network, and the admin hasn't allowed that for this store.
var ErrUnknown = errors.New("there is no such module")
ErrUnknown: no module has that id.
var ErrUnknownStore = errors.New("there is no such store")
ErrUnknownStore: no store has that id.
var ErrUnknownUpload = errors.New("that upload isn't waiting any more: choose the file again")
ErrUnknownUpload: no upload has that token, or it isn't this administrator's, or it ran out.
var OverrideWarnings = map[string]string{ OverrideIncomplete: "Its publisher says it isn't finished, or what it adds to the apps doesn't fit this server. " + "Parts of it may be missing or not work, and whatever doesn't fit isn't shown in any app.", OverrideOutOfRange: "It wasn't made for this version of the server. It speaks a module API this server knows, so it may work, " + "but nobody has tried it here: pages, libraries or playback that depend on it may break, and updating the server may break it further.", OverrideLocalFile: "It comes from a file you chose, not from a store this server checks for updates and withdrawals. " + "You'll be told about nothing that goes wrong with this version later.", OverrideCustom: "This server doesn't know this module. Nothing about it has been checked by this project: " + "it runs with the strict sandbox and no permissions you don't tick, and what it adds to the apps is its own.", OverrideUntrustedKey: "It is signed, but by a key this server doesn't trust for it. The signature proves only that whoever holds that key made it, " + "not who they are or that it is safe. Compare the key's fingerprint with its publisher, somewhere other than where you got the file.", OverrideWeakSandbox: "This system's sandbox for modules from other publishers is Apple's sandbox-exec, which Apple has deprecated. " + "The module is refused if it won't start inside it, but it can still read anything this server's account can read, " + "which may include your media and this server's database.", OverrideUnsigned: "It isn't signed at all. Nothing proves who made it or that it wasn't changed on its way to you. " + "It runs with the strict sandbox and no permissions you don't tick, but it is someone's code running on your server. " + "Only install it if you made it yourself or got it from someone you trust, by a route nobody else could change.", }
OverrideWarnings say what each override bypasses and what could go wrong. The server says them, so every app that offers an override says the same thing.
var ReservedPaths = []string{"install", "rollback", "versions", "pin", "autoupdate", "latest", "source",
"icon", "notices", "add", "remove", "enable", "disable", "web", "failed", "pending", "override", "check"}
ReservedPaths are the first parts of /api/modules/{id}/... that are the server's own, which a module's route can't start with.
var StoreWarning = []string{
"Add a store only if you trust whoever runs it. Nobody at this project has reviewed anything in it.",
"A module is someone's code running on your server. It can read what this server's account can read, which may include your media and this server's database. A web module runs in the browser of whoever uses it, with their access, including yours as an admin.",
"Whoever runs this store holds its signing key, not this project. A signature only proves a file came from whoever holds that key, not that it's safe. If that key leaks, or its owner turns, this server can't tell.",
"This server pins the key below now, and refuses the store if the key ever changes. It won't install anything from the store by itself: you choose each version, and each one replaces a module only after its own warning. " + forkLimits + " Encrypted media stays refused whatever a module says.",
"Check the key's fingerprint with the store's owner, somewhere other than the store itself.",
}
StoreWarning is what someone agrees to before adding a store. The server says it, so every client that offers this says the same thing.
Functions ¶
func Fingerprint ¶
Fingerprint is a short form of a key that two people can read out to compare.
func ForgetVersion ¶
ForgetVersion takes a version out of use in state.json, with no Manager running: the version before it becomes the choice if it's still good, or else no version is. A running server keeps this in memory, so it must use Rollback and UseBuiltin instead.
func ForkRefusal ¶
func ForkRefusal() string
ForkRefusal says why this server takes no fork, or "". A fork is someone else's code, and here it would have nothing to box it in, or whoever runs the machine has said no.
func Offers ¶
Offers is what this server offers a module, host feature by host feature: the versions a module's integration.json ranges are checked against.
func OlderServerWarning ¶
OlderServerWarning is what is said before a version made for an older server is installed, and while one is in use: which server it was made for, which this is, and what that means.
func PermissionWords ¶
PermissionWords says what a permission means, for a person.
func ProtectServer ¶
func ProtectServer()
ProtectServer has nothing to do here: a helper's filter refuses reaching into another process.
func ProxyToService ¶
func ProxyToService(c *service.Conn, w http.ResponseWriter, r *http.Request, path string, onErr func(error), modify ...func(*http.Response) error)
ProxyToService passes a request through to path on a running service, WebSocket upgrades included. Inbound X-Witty- headers are always dropped; the token, and the identity from WithIdentity if any, are set afresh. onErr hears a failure to reach it; modify, if given, may change the service's answer before it is sent on.
func ProxyToServiceWith ¶
func ProxyToServiceWith(c *service.Conn, w http.ResponseWriter, r *http.Request, path string, extra http.Header, onErr func(error), modify func(*http.Response) error)
ProxyToServiceWith is ProxyToService with more of the server's own X-Witty- headers, set after every one the browser sent is dropped (a module route's item and features).
func ReadInstalledState ¶
func ReadInstalledState(dir string) (map[string]InstalledState, error)
ReadInstalledState reads <dir>/state.json. No file means nothing was ever chosen. An error means the file is there and can't be read.
func ReportTasksTo ¶
ReportTasksTo says where helpers' task reports go. Until it's called they are ignored.
func RunSandboxed ¶
RunSandboxed is the server's other life as a launcher: args are memory in MiB, the mode, the program, and its arguments. It never returns if all goes well. A layer this kernel lacks is skipped for a stock helper, as with the other limits; for a fork it means not running. Everything here applies to one thread, and that thread becomes the program, so it must not move: limits on another thread would simply be lost.
func SandboxNetworkProgram ¶
SandboxNetworkProgram limits a separate program that has to reach the network. Here that's left to the program, which gives things up for itself: namespaces would take its network away too.
func ServerManifests ¶
func ServerManifests() [][]byte
ServerManifests describe the kinds of media that are part of the server rather than projects of their own. They are listed in the store with the rest, so someone who only wants music can leave films out, and they update with the server.
Types ¶
type Attached ¶
type Attached struct {
// contains filtered or unexported fields
}
Attached is a helper of its own for one long job, such as an open disc: it keeps its state between calls, isn't stopped when idle, and the job's failure doesn't get in anyone else's way. It stops when the job closes it, or with the server.
func (*Attached) Call ¶
Call asks the helper one thing. A *wittymodule.CallError is a working helper saying no. Any other error means it failed, which counts against the version, and the job loses the helper's state with it.
func (*Attached) OnNotify ¶
func (a *Attached) OnNotify(fn func(method string, params json.RawMessage))
OnNotify hears what the helper says unasked. It takes effect from the helper's next start, and it also keeps the pipe read between calls, so this is one thing per process: a job that streams can't use it. What's heard is untrusted, and fn must not block or call the helper.
type CDs ¶
type CDs struct{ M *Manager }
CDs reaches WittyCD: a helper for each open image, which an idle image lets go of.
type CatalogInfo ¶
type CatalogInfo struct {
Name string `json:"name,omitempty"`
Serial int64 `json:"serial,omitempty"`
Generated string `json:"generated,omitempty"`
Error string `json:"error,omitempty"` // why the last look failed, in words
}
CatalogInfo is what the store shows about the catalogue itself.
type Config ¶
type Config struct {
Dir string // <data>/modules
Server string // this server's version
Builtins [][]byte
// Known says to start from the list of modules this server was built knowing about, so a
// page can name what's missing before any catalogue has been read.
Known bool
// OnReady hears when a module has just arrived or been turned back on, off to the side.
OnReady func(id string)
// CatalogURL is where to look for the signed catalogue. Without it, each module's
// releases are read from its own repository, as a fork's are.
CatalogURL string
// Starter is a folder of signed archives that came with this server, with a catalogue,
// so modules can be installed offline. Optional, and only ever read.
Starter string
Transport http.RoundTripper // internet-only transport for GitHub
Log *slog.Logger
// CheckEnabled and AutoInstall read the owner's settings. Without them, nothing
// happens on its own.
CheckEnabled func() bool
AutoInstall func() bool
// Launcher is this server's own program, which boxes a helper in before it runs
// (Linux; see RunSandboxed). Without it helpers have the rest of their limits.
Launcher string
// LogEnv is how the owner wants a module logged, as environment for its helper.
LogEnv func(id string) []string
// UIChecks are the theme engine's checks a module's sdui.json is held to.
UIChecks sdui.ModuleChecks
// IntegrationCheck holds a module's integration.json to what this server can do (the
// features it knows, the paths it keeps for itself); nil checks only the file itself.
IntegrationCheck func(id string, in *wittymodule.Integration) error
// SettingsEnv gives a module's settings (docs/SDUI-MODULES.md), as environment for its
// helper.
SettingsEnv func(id string) []string
// WriteFolders are folders of the server's that a module allowed to write may write to,
// beside its own: a game's saves stay where a server keeps them.
WriteFolders func(id string) []string
// For tests.
Keys []ed25519.PublicKey
Fetch *update.Fetcher
}
Config prepares a Manager.
type Entry ¶
type Entry struct {
Name string `json:"name"`
Path string `json:"path"`
Dir bool `json:"dir"`
Kind string `json:"kind,omitempty"`
Disc string `json:"disc,omitempty"`
Size int64 `json:"size,omitempty"`
Modified int64 `json:"modified,omitempty"`
Hidden bool `json:"hidden,omitempty"`
}
Entry is one thing in a folder.
type ErrBadOverride ¶
type ErrBadOverride struct {
Reason string
Needs *ErrNeedsOverride
}
covers checks a go-ahead against what is needed: exactly the kinds needed, the name typed when the severity asks for it, and only grants the module asks for, for a fork-like one. ErrBadOverride is a go-ahead that doesn't fit what installing needs: kinds that aren't exactly those needed, the name not typed, a permission that can't be granted. Needs says what would.
func (*ErrBadOverride) Error ¶
func (e *ErrBadOverride) Error() string
type ErrMissing ¶
ErrMissing: a module this needs isn't on this server, or is turned off. The page says so and offers to install it, rather than showing a broken screen.
func (*ErrMissing) Error ¶
func (e *ErrMissing) Error() string
type ErrModuleMissing ¶
ErrModuleMissing: a library of this type needs a module that isn't installed.
func (*ErrModuleMissing) Error ¶
func (e *ErrModuleMissing) Error() string
type ErrNeedsConfirm ¶
type ErrNeedsConfirm struct{ Warning string }
ErrNeedsConfirm is what choosing a version needs before it goes ahead: someone has read the warning.
func (*ErrNeedsConfirm) Error ¶
func (e *ErrNeedsConfirm) Error() string
type ErrNeedsOverride ¶
type ErrNeedsOverride struct {
Version string `json:"version"`
Kinds []string `json:"kinds"`
Reasons []string `json:"reasons"`
Severity int `json:"severity"`
Warning string `json:"warning"`
Permissions []string `json:"permissions,omitempty"` // what it asks for, which may be granted
// Pending: it has been downloaded and checked, and is held until the answer.
Pending bool `json:"pending,omitempty"`
}
ErrNeedsOverride is what installing needs before it goes ahead: an administrator who has read each warning and accepted each kind.
func (*ErrNeedsOverride) Error ¶
func (e *ErrNeedsOverride) Error() string
type ErrNoVersion ¶
type ErrNoVersion struct{ Reason string }
ErrNoVersion: nothing the server knows of can be installed, and says why.
func (*ErrNoVersion) Error ¶
func (e *ErrNoVersion) Error() string
type ErrOlderServer ¶
type ErrOlderServer struct {
Module string `json:"module"`
Name string `json:"name"`
Version string `json:"version"`
MadeFor string `json:"madeFor"`
Server string `json:"server"`
Warning string `json:"warning"`
}
ErrOlderServer refuses a version made for an older server that nobody confirmed. Installing it needs the request to say so (confirmOlder), after a person has read Warning.
func (*ErrOlderServer) Error ¶
func (e *ErrOlderServer) Error() string
type ErrResting ¶
ErrResting: a module's only version failed again and again, and is left alone for a while.
func (*ErrResting) Error ¶
func (e *ErrResting) Error() string
type ErrStoreAddress ¶
type ErrStoreAddress struct{ Why string }
ErrStoreAddress: this isn't an address a store can be at.
func (*ErrStoreAddress) Error ¶
func (e *ErrStoreAddress) Error() string
type Event ¶
type Event struct {
At int64 `json:"at"` // unix ms
Kind string `json:"kind"`
Version string `json:"version,omitempty"`
Detail string `json:"detail,omitempty"`
}
Event is one thing that happened to a module, newest kept, for the page's log.
type Failure ¶
type Failure struct {
Kind string `json:"kind"`
Title string `json:"title"`
Message string `json:"message"`
Try []string `json:"try"`
Detail string `json:"detail,omitempty"` // the original words, for "Show details"
Repair bool `json:"repair,omitempty"` // the repair tools may help
}
Failure is one thing that went wrong, for a person.
func Explain ¶
Explain turns what went wrong with a module into words for a person. name is the module's. An error's words are what's left of it once it has been through the steps of an install, so this reads those; each check here is covered by a test against the words that step uses.
func ExplainError ¶
ExplainError is Explain for an error, recognising the kinds that have a type of their own.
type FileBrowser ¶
type FileBrowser struct{ M *Manager }
FileBrowser lists the server's folders through the WittyIntegratedFileBrowser version in use. Without it, someone can still type a folder's path. M may be nil.
func (FileBrowser) List ¶
func (b FileBrowser) List(path string, o ListOptions) (*Listing, error)
List lists a folder. o.Kind can't reach a helper, so the server names each file's kind itself, which also keeps the page's words the same whichever version is in use.
type InUse ¶
type InUse struct {
ID string
Name string
Version string
Integration *wittymodule.Integration
}
InUse is a module's integration while one of its versions is in use.
type InstalledState ¶
type InstalledState struct {
Active string
Previous string
Pin string
Removed bool
Blocked map[string]string
// contains filtered or unexported fields
}
InstalledState is one module's saved choices.
type ItemDetail ¶
type ItemDetail struct {
Item StoreItem `json:"item"`
Versions []VersionInfo `json:"versions"`
Plan []RunItem `json:"plan"`
BuiltOn []ModuleRef `json:"builtOn"`
Permissions []PermissionRow `json:"permissions"`
ForkWarning string `json:"forkWarning,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Policy string `json:"policy"`
Server string `json:"server"`
}
ItemDetail is a module's page.
type ItemsAnswer ¶
type ItemsAnswer struct {
Items []sdui.Item `json:"items"`
More bool `json:"more,omitempty"`
Total int `json:"total,omitempty"`
}
ItemsAnswer is a helper's answer.
type ItemsRequest ¶
type ItemsRequest struct {
// Source is the section's source, with every $variable filled in.
Source map[string]any `json:"source"`
// Filter holds the page's filter and sort parameters, for a filterable source.
Filter map[string]string `json:"filter,omitempty"`
Offset int `json:"offset"`
Limit int `json:"limit"`
// Viewer is who is asking, so the module can leave out what isn't for them.
Viewer Viewer `json:"viewer"`
// Settings are the module's settings for this profile: the server's, then the
// profile's own.
Settings map[string]any `json:"settings,omitempty"`
}
ItemsRequest is what a helper is asked for one of its data sources.
type LibraryType ¶
type LibraryType struct {
Type string `json:"type"`
Available bool `json:"available"`
Modules []ModuleRef `json:"modules"` // any one of these makes it possible
// Label is what this server calls it, when someone chose a name. Empty: the usual one.
Label string `json:"label,omitempty"`
Shared bool `json:"shared,omitempty"`
}
LibraryType says whether a kind of library can be made here, and what it takes.
type ListOptions ¶
type ListOptions struct {
ShowHidden bool
MaxEntries int
Kind func(name string) string // names what each file is
}
ListOptions says how to list a folder.
type Listing ¶
type Listing struct {
Path string `json:"path"`
Parent *string `json:"parent"`
Sep string `json:"sep"`
Entries []Entry `json:"entries"`
Counts map[string]int `json:"counts"`
Truncated bool `json:"truncated"`
}
Listing is a folder's contents.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager keeps track of every module.
func New ¶
New reads what is installed and picks the version of each module to use. A manifest that can't be read is a build error caught by tests, so it is only logged here; nothing about modules can stop a server from starting.
func (*Manager) AddModule ¶
AddModule puts a module on this server, with what it's built on: straight away for what's here already, or by installing the newest version that fits, in the background, with no restart. Progress is in the Report.
func (*Manager) AddModuleOlder ¶
AddModuleOlder is AddModule that, when no version made for this server is known, may install the newest made for an older server: only with confirmOlder, and otherwise it is refused with *ErrOlderServer naming it. What it's built on is added the same way.
func (*Manager) Attach ¶
Attach starts nothing yet, and gives a job its own helper for the version in use. It returns nil when no helper version is in use, and the job then can't go ahead.
func (*Manager) Call ¶
Call asks a module's helper one thing. Without a version in use, it says which is missing.
func (*Manager) Capability ¶
Capability is a fact from the manifest of the version in use.
func (*Manager) Check ¶
Check looks for releases of every module that can have them, unless the last answer is younger than maxAge. Concurrent calls share one look. When the network is down, or GitHub asks this network to wait, the last answer stays, along with why this one failed; nothing that is running depends on it.
func (*Manager) CheckEnabled ¶
CheckEnabled says whether the owner allows looking for updates.
func (*Manager) ClearSource ¶
ClearSource goes back to the module's own repository and this project's key.
func (*Manager) Close ¶
func (m *Manager) Close()
Close stops every helper. A helper in the middle of a call may keep it waiting until its time limit, so nothing waits for long, and none of them outlives the server anyway.
func (*Manager) DiscardUpload ¶
DiscardUpload forgets an upload.
func (*Manager) DropPending ¶
DropPending forgets a module's held download.
func (*Manager) HostModule ¶
HostModule is the module a host API secret was given to, if any.
func (*Manager) IconFile ¶
IconFile is where a module's picture from the catalogue is kept, fetched the first time it's asked for. It's checked against the signed catalogue, so it can't be swapped for anything else.
func (*Manager) Install ¶
Install starts installing the newest release the last check found, in the background. Progress is in the Report. An admin may choose a version that was taken out of use before; nothing automatic does.
func (*Manager) InstallOlder ¶
InstallOlder installs the newest version made for an older server, when that is all there is for this module: only when confirmOlder says someone read the warning, and otherwise refused with *ErrOlderServer naming it. Nothing automatic calls this.
func (*Manager) InstallUpload ¶
func (m *Manager) InstallUpload(token string, by int64, accept *OverrideAccept) error
InstallUpload installs an uploaded release with an administrator's go-ahead.
func (*Manager) InstallVersion ¶
InstallVersion starts moving a module to a given version, newer or older. Without confirm, a choice with a warning is refused with *ErrNeedsConfirm. A version already on disk is switched to with no download, so going back works offline.
func (*Manager) InstallVersionOlder ¶
InstallVersionOlder is InstallVersion that may also install a version made for an older server, when confirmOlder says someone read that warning. Without it such a version is refused with *ErrOlderServer.
func (*Manager) InstallVersionWith ¶
func (m *Manager) InstallVersionWith(id, ver string, confirm bool, accept *OverrideAccept) error
InstallVersionWith is InstallVersion with an administrator's go-ahead past what the server would refuse (override.go). A download held for that go-ahead is installed from what was held.
func (*Manager) InstallVersionWithOlder ¶
func (m *Manager) InstallVersionWithOlder(id, ver string, confirm, confirmOlder bool, accept *OverrideAccept) error
InstallVersionWithOlder is InstallVersionWith that may also install a version made for an older server, when confirmOlder says so.
func (*Manager) Installed ¶
Installed says whether a module is here and in use. An unknown one doesn't count: nothing can be asked of it.
func (*Manager) Integration ¶
func (m *Manager) Integration(id string) *wittymodule.Integration
Integration is one module's integration in use, nil when it has none: a module with none in use (absent, turned off, or a version older than API 5) is the server's own copy's to answer.
func (*Manager) Integrations ¶
Integrations are the integrations of the modules in use and turned on, in module order, and a number that changes whenever the versions in use may have, so a caller can keep what it makes of them.
func (*Manager) Libraries ¶
Libraries are the kinds of library a module's version in use says it serves: what it may ask the host API about.
func (*Manager) LibraryAllowed ¶
LibraryAllowed says whether a library of this type can be made now; nil if it can.
func (*Manager) LibraryTypes ¶
func (m *Manager) LibraryTypes() []LibraryType
LibraryTypes lists every kind of library a module declares, with whether it can be made. A type no module declares isn't listed, and is always available.
func (*Manager) MadeForOlder ¶
MadeForOlder says whether installing ver (or, with "", what an add or install would pick) means a version made for an older server, for the audit log.
func (*Manager) Missing ¶
missing is the ErrMissing for a module. Missing is the ErrMissing for a module.
func (*Manager) ModuleReport ¶
ModuleReport is a module's own word on the version in use: working (a game started), or failing in a way the server can't see itself (its helper failed). Through the host API.
func (*Manager) OlderThanInUse ¶
OlderThanInUse says a version is older than the one in use. "" means none is.
func (*Manager) OnServiceNotify ¶
func (m *Manager) OnServiceNotify(id, method string, fn func(json.RawMessage)) error
OnServiceNotify hears one kind of thing a module's running service says unasked. It lasts until the service next starts. fn must not block.
func (*Manager) Pin ¶
Pin keeps the version in use: automatic updates leave it alone until Unpin. A pin doesn't override safety: a version withdrawn for security reasons, or one that stops working, still goes out of use, and the page says so.
func (*Manager) Program ¶
Program finds a program module's version in use: the path to run, checked against its signature just now, and that version. ok is false when no version is in use.
func (*Manager) ProgramCommand ¶
ProgramCommand finds a program module's version in use, like Program, ready to start: a fork's goes through the launcher, since a program from another publisher can't be trusted to limit itself. It can write only to the folder after its -save argument, and open devices, since a game core may need a graphics card.
func (*Manager) ReinstallNow ¶
ReinstallNow asks the publisher for the newest compatible version, installs it and waits. It's the one thing here that goes online, and only someone asking for it gets here.
func (*Manager) RemoveModule ¶
RemoveModule takes a module off this server. libraries names the libraries there are, by type; if any would be left with no module, nothing changes and *ErrInUse says which. Its downloaded versions go, and no data is touched.
func (*Manager) RemoveOverride ¶
RemoveOverride ends an override: the module goes back to the version before, when that one needed none, or off this server. A module this server didn't know goes altogether.
func (*Manager) ReportBrowserFailure ¶
ReportBrowserFailure records a browser saying a bundle failed. It only applies to bundles: nothing a browser says counts against a helper or a program. Only an admin's report can take a version out of use. Anyone else's goes in the module's log for an admin to see: their own page has already fallen back, and a profile shouldn't be able to take a version, perhaps one with a security fix, away from everyone.
func (*Manager) ReportFailure ¶
ReportFailure records a version failing where the server can't see it itself: a bundle in someone's browser, or a helper during a game. Three within a day and the version goes out of use. A report about any other version is ignored, so an old tab can't count against what replaced it. A game that couldn't start because of that game, its core or its console isn't one: see liftGameFailureBlocks.
func (*Manager) ReportWorking ¶
ReportWorking clears a program's failures: it did its job, so they weren't in a row.
func (*Manager) Requires ¶
Requires are the modules a module's version in use is built on (module.json requires).
func (*Manager) Resting ¶
Resting says whether a module is resting after failing again and again, as an *ErrResting.
func (*Manager) Rollback ¶
Rollback takes the version in use out of use, going back to the previous one, if any. It isn't installed on its own again, though an admin may.
func (*Manager) Run ¶
Run looks for updates after a pause at start and then twice a day, while the owner's settings allow it, and installs them if the settings say so too.
func (*Manager) RunningDownload ¶
RunningDownload says a module is running a downloaded version, which going back would leave.
func (*Manager) ServiceConn ¶
ServiceConn finds a module's service, starting it if need be. It is what service.Dial is set to.
func (*Manager) ServiceProxy ¶
func (m *Manager) ServiceProxy(id string, w http.ResponseWriter, r *http.Request, path string) error
ServiceProxy passes a request through to a module's service, connections that stay open included. The server has already decided this person may make it.
func (*Manager) SetAutoUpdate ¶
SetAutoUpdate says whether this module may update by itself while the server's setting is on. Off, it still looks for updates and offers them, and an admin installs them by hand. A built-in part of the server has no updates of its own to turn off.
func (*Manager) SetEnabled ¶
SetEnabled turns a module off without taking it off the server, or back on. Nothing is downloaded or lost, and no restart is needed. Turning off is refused while libraries or other modules need it, and the reason names them.
func (*Manager) SetHost ¶
SetHost says where this server's host API listens (module API 5): services started from now on are told it, with a secret of their own.
func (*Manager) SetInstalled ¶
SetInstalled makes the set of modules on this server what someone chose, as during first-run setup. It adds first, so a choice that moves libraries from one module to another isn't refused along the way. Core modules stay whatever the list says.
func (*Manager) SetInstalledOlder ¶
func (m *Manager) SetInstalledOlder(ids []string, libraries map[string][]string, confirmOlder []string) error
SetInstalledOlder is SetInstalled that may install, for the modules named in confirmOlder, a version made for an older server when that is all there is. Any other such module isn't installed: it says why on its status, as a module that couldn't start does.
func (*Manager) SetLibraryLabel ¶
SetLibraryLabel gives a kind of library a name of this server's own, which is how two modules bringing one kind, or two kinds that read alike, can be told apart. An empty name goes back to the usual one. taken are the names the app already shows for other kinds, since only it knows those: two kinds with one name are the thing this is here to prevent.
func (*Manager) SetSource ¶
func (m *Manager) SetSource(id, repo, key, by string, confirm bool, accept *OverrideAccept) error
SetSource makes a fork the source of a module. Without confirm it answers *ErrNeedsConfirm with the warning, and changes nothing. What was downloaded from the old source goes, since it was signed by someone else: the module has no version in use until one of the fork's is chosen, and nothing installs on its own.
func (*Manager) SettingsChanged ¶
SettingsChanged tells a module's running helper its settings changed. A helper that isn't running reads them when it starts; one that doesn't know the call is fine.
func (*Manager) StageUpload ¶
func (m *Manager) StageUpload(u Upload) (*UploadInfo, error)
StageUpload unpacks and checks an uploaded release, and holds it for an administrator's go-ahead. A file that can't be installed at all answers its refusal, and nothing is kept.
func (*Manager) ToLatest ¶
ToLatest unpins a module and starts moving it to the newest version that fits: a release if one is newer than what's built in, or else what's built in.
func (*Manager) UIItems ¶
func (m *Manager) UIItems(id string, req ItemsRequest) (ItemsAnswer, error)
UIItems asks a module for one of its sources: a module of API 5 in its service, where its data and its host API are (its helper process is started without them); any other in its helper.
func (*Manager) UIs ¶
UIs are the SDUI files of the modules in use, by module, and a number that changes whenever which versions are in use does, so a caller can keep what it makes of them.
func (*Manager) Uninstall ¶
Uninstall tells a module of API 5 it is being taken off this server, and whether to keep its data, before it goes. A module that doesn't answer the call, or isn't running, is let go: its data folder stays unless the server removes it.
func (*Manager) UploadOf ¶
UploadOf names the module and version an administrator's held upload would install, for the audit log; empty once it has gone.
func (*Manager) UseBuiltin ¶
UseBuiltin stops using a downloaded version without blaming it: it stays available to choose again.
func (*Manager) UseServices ¶
func (m *Manager) UseServices()
UseServices connects the service package to this manager, which stubs reach modules through.
func (*Manager) VersionInUse ¶
VersionInUse is the version of one module in use, or "".
func (*Manager) Versions ¶
func (m *Manager) Versions(id string) (VersionList, error)
Versions lists what is known, without going online: the last check's answer, or an empty list until there has been one. Incompatible versions are there too, explained, rather than hidden.
func (*Manager) WebBundles ¶
WebBundles lists the bundles in use.
type ModuleRef ¶
type ModuleRef struct {
ID string `json:"id"`
Name string `json:"name"`
Installed bool `json:"installed"`
}
ModuleRef names a module for the store's links.
type NeedKey ¶
type NeedKey struct{}
NeedKey: the store has no key beside it, or none that can be read, so the admin has to give it.
type Offer ¶
type Offer struct {
Version string `json:"version"`
MinServer string `json:"minServer"`
MaxServer string `json:"maxServer"`
Notes string `json:"notes,omitempty"`
URL string `json:"url,omitempty"`
Published int64 `json:"published,omitempty"` // unix ms
Prerelease bool `json:"prerelease"`
Size int64 `json:"size,omitempty"`
Reason string `json:"reason,omitempty"` // why it doesn't fit
Blocked string `json:"blocked,omitempty"` // why it was taken out of use before
// OlderServer: it was made for an older server (its range is MadeFor), and fits only when
// widened. It is never chosen by itself, and installing it needs confirmOlder.
OlderServer bool `json:"olderServer,omitempty"`
MadeFor string `json:"madeFor,omitempty"`
}
Offer is a release of a module.
type Override ¶
type Override struct {
Kinds []string `json:"kinds"`
Version string `json:"version"`
By string `json:"by,omitempty"`
At int64 `json:"at"`
// Key is the publisher key (base64) an untrusted-key version was signed with, or this
// server's own local key for an unsigned one: what its files are checked against.
Key string `json:"key,omitempty"`
// Grants are the permissions the administrator ticked for a fork-like module.
Grants []string `json:"grants,omitempty"`
// Source is "catalogue" or "upload".
Source string `json:"source"`
}
Override is what an administrator bypassed for the version in use, as it is kept.
type OverrideAccept ¶
OverrideAccept is an administrator's go-ahead, after the server checked their password (and the typed name, where the severity asks for it).
type OverrideInfo ¶
type OverrideInfo struct {
Kinds []string `json:"kinds"`
Reasons []string `json:"reasons"`
Version string `json:"version"`
By string `json:"by,omitempty"`
At int64 `json:"at"`
Fingerprint string `json:"fingerprint,omitempty"`
Grants []string `json:"grants,omitempty"`
Source string `json:"source"`
}
OverrideInfo is an override as the pages show it.
type PendingInfo ¶
type PendingInfo struct {
Version string `json:"version"`
NeedsOverride *ErrNeedsOverride `json:"needsOverride"`
Expires int64 `json:"expires"`
}
PendingInfo is a download waiting for a go-ahead, as the page shows it.
type PermissionRow ¶
PermissionRow is one thing a module asks for.
type Place ¶
type Place struct {
Name string `json:"name"`
Path string `json:"path"`
Group string `json:"group"`
Label string `json:"label,omitempty"`
Free uint64 `json:"free,omitempty"`
Total uint64 `json:"total,omitempty"`
}
Place is somewhere to start from.
type PreviewModule ¶
type PreviewModule struct {
ID string `json:"id"`
Name string `json:"name"`
Summary string `json:"summary,omitempty"`
Kind string `json:"kind"`
Why string `json:"why,omitempty"`
}
PreviewModule is one module a store would bring.
type Report ¶
type Report struct {
Server string `json:"server"` // this server's version
API int `json:"api"` // the newest module API it has
MinAPI int `json:"minApi"` // the oldest it still takes
CheckedAt int64 `json:"checkedAt,omitempty"`
CheckError string `json:"checkError,omitempty"`
HoldUntil int64 `json:"holdUntil,omitempty"` // GitHub asked this network to wait until then
Modules []Status `json:"modules"`
// Libraries is every kind of library a module provides, and whether it can be made.
Libraries []LibraryType `json:"libraries"`
Catalog *CatalogInfo `json:"catalog,omitempty"`
// Sandbox says how well a helper is boxed in here, in words when it isn't fully.
Sandbox SandboxInfo `json:"sandbox"`
}
Report is what Settings shows.
type RouteKinds ¶
type RouteKinds struct {
User int `json:"user"` // anyone signed in may call it
Admin int `json:"admin"` // administrators only
Ticket int `json:"ticket"` // no sign-in: a secret in the address, answered in a sandboxed frame
Items int `json:"items"` // about one library item, which the profile must be allowed to see
Streams int `json:"streams"` // a stream or a WebSocket
Plays int `json:"plays"` // starts playing something, so it counts towards screen time
}
RouteKinds counts a version's routes by what they are. One route can be several.
type Run ¶
type Run struct {
ID string `json:"id"`
Kind string `json:"kind"`
By string `json:"by,omitempty"`
Started int64 `json:"started"`
Finished int64 `json:"finished,omitempty"`
Items []RunItem `json:"items"`
Updated int `json:"updated"`
Failed int `json:"failed"`
Skipped int `json:"skipped"`
CanUndo bool `json:"canUndo,omitempty"`
Undone bool `json:"undone,omitempty"`
// contains filtered or unexported fields
}
Run is a whole run, as the page shows it.
type RunItem ¶
type RunItem struct {
ID string `json:"id"`
Name string `json:"name"`
From string `json:"from,omitempty"`
To string `json:"to,omitempty"`
State string `json:"state"`
Why string `json:"why,omitempty"` // why it was skipped, or what it's here for
Phase string `json:"phase,omitempty"`
Done int64 `json:"done,omitempty"`
Total int64 `json:"total,omitempty"`
Failure *Failure `json:"failure,omitempty"`
// OlderServer: To was made for an older server (MadeFor), because nothing made for this one
// is known. Warning says so; the run installs it only when the request said confirmOlder.
OlderServer bool `json:"olderServer,omitempty"`
MadeFor string `json:"madeFor,omitempty"`
Warning string `json:"warning,omitempty"`
}
RunItem is one module in a run.
type SandboxInfo ¶
type SandboxInfo struct {
Level string `json:"level"`
Title string `json:"title,omitempty"`
Words string `json:"words,omitempty"`
}
SandboxInfo says, in words a person can act on, what a module's helper is held to here. Anything short of full is shown on the pages that add modules.
type Source ¶
type Source struct {
Repo string `json:"repo"`
Key string `json:"key"` // base64 of the publisher's Ed25519 public key
AddedAt int64 `json:"addedAt"`
AddedBy string `json:"addedBy,omitempty"`
// Store is the store it comes from, when its versions come from a store's catalogue rather
// than a GitHub repository. See stores.go.
Store string `json:"store,omitempty"`
}
Source is where a module's releases come from instead of its own repository.
type SourceInfo ¶
type SourceInfo struct {
Repo string `json:"repo"`
Fingerprint string `json:"fingerprint"` // to compare with what the publisher says
AddedAt int64 `json:"addedAt"`
AddedBy string `json:"addedBy,omitempty"`
Store string `json:"store,omitempty"`
}
SourceInfo is what the page shows about a fork in use.
type Status ¶
type Status struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"` // the version in use; empty if none is
BuiltinVersion string `json:"builtinVersion,omitempty"`
Delivery string `json:"delivery"`
Updatable bool `json:"updatable"` // can be updated without a new server
MinServer string `json:"minServer"` // of the version in use
MaxServer string `json:"maxServer"`
API int `json:"api"`
Repo string `json:"repo"`
License string `json:"license,omitempty"`
State string `json:"state"`
Notice string `json:"notice,omitempty"` // why a version isn't in use, in plain words
Previous string `json:"previous,omitempty"` // an installed version to go back to
CanRollback bool `json:"canRollback"`
Latest *Offer `json:"latest,omitempty"`
TooNew *Offer `json:"tooNew,omitempty"` // a newer version that doesn't fit this server
Phase string `json:"phase"`
Done int64 `json:"done,omitempty"` // bytes downloaded
Total int64 `json:"total,omitempty"`
Error string `json:"error,omitempty"` // why the last install failed
// OlderOffer is the newest version made for an older server, when no version made for this one
// is known: it can be installed only with confirmOlder, after the warning in its Reason.
OlderOffer *Offer `json:"olderOffer,omitempty"`
// OlderServer: the version in use was made for an older server (MadeFor), so pages, settings and
// features may be missing. OlderWarning says so, and what to do: the newer version, or removal.
OlderServer bool `json:"olderServer,omitempty"`
MadeFor string `json:"madeFor,omitempty"`
OlderWarning string `json:"olderWarning,omitempty"`
// What the page needs in order to explain it.
Group string `json:"group,omitempty"`
Summary string `json:"summary,omitempty"`
Needs []string `json:"needs,omitempty"`
Updates string `json:"updates,omitempty"` // what a release of its own changes
Stays string `json:"stays,omitempty"` // what only a new server changes
Pin string `json:"pin,omitempty"` // a version kept on purpose, or "builtin"
Withdrawn *wittymodule.Withdrawn `json:"withdrawn,omitempty"`
LastFail string `json:"lastFailure,omitempty"`
Events []Event `json:"events,omitempty"`
// What the store needs.
Description string `json:"description,omitempty"`
Publisher *wittymodule.Publisher `json:"publisher,omitempty"`
Icon string `json:"icon,omitempty"`
Enabled bool `json:"enabled"`
Installed bool `json:"installed"`
// Overrides (override.go): what an administrator bypassed for the version in use, a
// download held for a go-ahead, what the version says of itself, and what it adds to the apps.
Override *OverrideInfo `json:"override,omitempty"`
Pending *PendingInfo `json:"pending,omitempty"`
ReleaseStatus string `json:"releaseStatus,omitempty"`
StatusNote string `json:"statusNote,omitempty"`
UIAdds *UIAdds `json:"uiAdds,omitempty"`
Core bool `json:"core,omitempty"` // other modules are built on it, so it stays
ComesInside bool `json:"comesInside,omitempty"` // a library: it reaches this server inside what's built on it
Libraries []string `json:"libraries,omitempty"` // the kinds of library it makes possible
Requires []string `json:"requires,omitempty"`
RequiredBy []string `json:"requiredBy,omitempty"`
// What the version in use adds to this server, from its integration.json (module API 5).
IntegrationAdds *StoreIntegration `json:"integrationAdds,omitempty"`
// A fork in place of the module's own repository.
StockRepo string `json:"stockRepo"`
Source *SourceInfo `json:"source,omitempty"`
NoFork string `json:"noFork,omitempty"` // why a fork can't replace it
// for this system. A page shows it in place of the button.
Unavailable string `json:"unavailable,omitempty"`
// AutoUpdate says this module may update by itself when the server's setting is on.
AutoUpdate bool `json:"autoUpdate"`
}
Status is one module.
type StoreInfo ¶
type StoreInfo struct {
ID string `json:"id"`
Name string `json:"name"`
Host string `json:"host"` // always shown beside the name, which the store chose itself
URL string `json:"url"`
Official bool `json:"official,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Private bool `json:"private,omitempty"`
Enabled bool `json:"enabled"`
AddedAt int64 `json:"addedAt,omitempty"`
AddedBy string `json:"addedBy,omitempty"`
Serial int64 `json:"serial,omitempty"`
Generated string `json:"generated,omitempty"`
CheckedAt int64 `json:"checkedAt,omitempty"`
Modules int `json:"modules"`
Problem *Failure `json:"problem,omitempty"`
InUse []string `json:"inUse,omitempty"` // names of modules using this store now
}
StoreInfo is one store, for the page.
type StoreIntegration ¶
type StoreIntegration struct {
// Routes is how many HTTP routes of its own it answers, under /api/v1/modules/<id>/.
Routes int `json:"routes"`
// RouteKinds says who may call them and what they do; known only for a copy on this
// server, since a catalogue gives only the count.
RouteKinds *RouteKinds `json:"routeKinds,omitempty"`
// Screens are the web app's addresses it draws (react-router style, "/couch/:id").
Screens []string `json:"screens"`
// Settings are the sections it adds to Settings, by label.
Settings []string `json:"settings"`
// Setup are the steps it adds to the server's first-run setup, by title (installed copy only).
Setup []string `json:"setup,omitempty"`
// Data: it keeps a database of its own.
Data bool `json:"data,omitempty"`
// Feature is the parental and profile-limits feature it all belongs to, such as "games".
Feature string `json:"feature,omitempty"`
// Libraries are the kinds of library whose pages it draws (installed copy only; the store
// falls back to the module's own list of library kinds).
Libraries []string `json:"libraries,omitempty"`
}
StoreIntegration is what a version adds to a server (its integration.json), for the store's "What this adds": from the catalogue before it is installed, from the installed copy after.
type StoreItem ¶
type StoreItem struct {
Key string `json:"key"` // store/id
Store string `json:"store"`
StoreName string `json:"storeName"`
StoreHost string `json:"storeHost"`
Official bool `json:"official"`
Kind string `json:"kind"`
Why string `json:"why,omitempty"`
Lookalike string `json:"lookalike,omitempty"` // it has the name of a module from this project
ID string `json:"id"`
Name string `json:"name"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Group string `json:"group,omitempty"`
Publisher *wittymodule.Publisher `json:"publisher,omitempty"`
Repo string `json:"repo,omitempty"`
Icon string `json:"icon,omitempty"`
Screenshots []string `json:"screenshots,omitempty"`
Libraries []string `json:"libraries,omitempty"`
Requires []string `json:"requires,omitempty"`
Needs []string `json:"needs,omitempty"`
Core bool `json:"core,omitempty"`
Updates string `json:"updates,omitempty"`
Stays string `json:"stays,omitempty"`
// Of the version the store would offer: the newest that fits, or the newest there is.
Platforms []string `json:"platforms,omitempty"`
Delivery string `json:"delivery,omitempty"`
Version string `json:"version,omitempty"`
Released string `json:"released,omitempty"`
Size int64 `json:"size,omitempty"`
License string `json:"license,omitempty"`
Permissions []string `json:"permissions,omitempty"`
Changelog string `json:"changelog,omitempty"`
MinServer string `json:"minServer,omitempty"`
MaxServer string `json:"maxServer,omitempty"`
// What kind of module it is: its delivery (helper, web, program, library), or builtin for a
// part that updates with the server. Kind above says where it comes from.
ModuleKind string `json:"moduleKind,omitempty"`
// How finished the offered version says it is (stable, beta, experimental, incomplete), and
// what isn't done, as the catalogue copies them; the downloaded manifest decides.
ReleaseStatus string `json:"releaseStatus,omitempty"`
StatusNote string `json:"statusNote,omitempty"`
// The SDUI the offered version adds to every app, as the catalogue sums it up.
UI *StoreUI `json:"ui,omitempty"`
// What the offered version adds to this server (module API 5): its routes, screens,
// settings and data, as the catalogue sums up its integration.json.
Integration *StoreIntegration `json:"integration,omitempty"`
// The override the version in use was installed with, when it was.
Override *OverrideInfo `json:"override,omitempty"`
// OlderServer: the version offered was made for an older server (MadeFor, e.g. "0.6.x"), as
// Fit.Why explains. Installing it needs confirmOlder.
OlderServer bool `json:"olderServer,omitempty"`
MadeFor string `json:"madeFor,omitempty"`
Fit Fit `json:"fit"`
Status *Status `json:"status,omitempty"`
Failure *Failure `json:"failure,omitempty"`
}
StoreItem is one module in the store.
func (*StoreItem) MatchesKinds ¶
MatchesKinds says whether an item is of one of the kinds asked for: a comma-separated list of moduleKind values, any of them; empty matches everything.
type StorePreview ¶
type StorePreview struct {
URL string `json:"url"`
Host string `json:"host"`
Name string `json:"name"`
Serial int64 `json:"serial"`
Generated string `json:"generated"`
Key string `json:"key"`
Fingerprint string `json:"fingerprint"`
KeySource string `json:"keySource"` // "pasted", or "offered" when the store itself supplied it
Private bool `json:"private,omitempty"`
Modules []PreviewModule `json:"modules"`
Count int `json:"count"`
Warning []string `json:"warning"`
}
StorePreview is what an admin reads before agreeing to add a store.
type StoreUI ¶
type StoreUI struct {
Pages []UIPage `json:"pages"`
Settings bool `json:"settings,omitempty"`
Sources int `json:"sources,omitempty"`
Inserts int `json:"inserts,omitempty"`
}
StoreUI is a catalogue's summary of the SDUI a version adds.
type StoreView ¶
type StoreView struct {
Server string `json:"server"`
API int `json:"api"`
MinAPI int `json:"minApi"`
Policy string `json:"policy"`
MinServer string `json:"minServer"`
Platform string `json:"platform"`
CheckedAt int64 `json:"checkedAt,omitempty"`
CheckError string `json:"checkError,omitempty"`
Stores []StoreInfo `json:"stores"`
Items []StoreItem `json:"items"`
Updates int `json:"updates"`
Run *Run `json:"run,omitempty"`
RepairRoute string `json:"repairRoute"`
Sandbox SandboxInfo `json:"sandbox"`
}
StoreView is everything the store's pages need at once.
type Stores ¶
type Stores struct {
// Watch, if set before anything runs, hears how each run stands: what the activity button
// shows. It runs on the run's own goroutine, and must not block.
Watch func(r *Run)
// contains filtered or unexported fields
}
Stores keeps the third-party stores and runs what the store pages ask for.
func NewStores ¶
func NewStores(cfg StoresConfig) *Stores
NewStores reads the stores this server has. A kept catalogue is checked again, with the key that was pinned, since the folder may be a shared one.
func (*Stores) Add ¶
func (s *Stores) Add(ctx context.Context, raw, key string, private bool, by string) (*StoreInfo, error)
Add keeps a store, pinning the key the admin agreed to. It fetches again rather than believing what was previewed, and refuses if the store's answer has changed in between.
func (*Stores) AutoUpdate ¶
func (s *Stores) AutoUpdate()
AutoUpdate is what the owner's "Install updates automatically" runs: everything Update All would do, in the same order, except what has been told to wait for an admin.
func (*Stores) CheckAll ¶
CheckAll brings every store that's on up to date, one at a time, and says what went wrong.
func (*Stores) CurrentRun ¶
CurrentRun is the run going on now, or the last one to finish.
func (*Stores) Detail ¶
func (s *Stores) Detail(store, id string) (*ItemDetail, error)
Detail builds a module's page.
func (*Stores) DismissRun ¶
func (s *Stores) DismissRun()
DismissRun forgets the last run's summary.
func (*Stores) InstallPlan ¶
InstallPlan says what installing a module would bring with it: everything it's built on that isn't here yet, first, then the module. A module with no version that fits is named with why, so nothing starts that can't finish.
func (*Stores) InstallWithNeeds ¶
InstallWithNeeds starts installing a module and what it's built on. A plan with a version made for an older server in it is refused (*ErrOlderServer); InstallWithNeedsOlder can confirm it.
func (*Stores) InstallWithNeedsOlder ¶
InstallWithNeedsOlder is InstallWithNeeds that installs versions made for an older server in the plan when confirmOlder says someone was shown each of them and said go ahead.
func (*Stores) Media ¶
func (s *Stores) Media(ctx context.Context, store, sha string) (path, contentType string, err error)
Media serves a picture a catalogue lists: only one it lists, only of the kinds a browser can be trusted to read as pictures, and checked against its size and hash when it arrives. Kept once fetched, so a page never asks anyone else for it.
func (*Stores) OlderInPlan ¶
func (s *Stores) OlderInPlan(plan []RunItem) []*ErrOlderServer
OlderInPlan lists the versions in a plan that were made for an older server, as refusals that name each one.
func (*Stores) Preview ¶
Preview fetches a store and says what adding it would mean. Nothing is kept. key is what the admin pasted, which may be nothing: the store may offer one beside its catalogue, which is only a suggestion the admin has to agree to.
func (*Stores) Refresh ¶
Refresh brings one store up to date. A catalogue that fails any check changes nothing: the last good one stays, and the store says why.
func (*Stores) Remove ¶
Remove forgets a store and what was kept of it. Any module using it goes back to the official version first, so nothing keeps running on trust nobody holds any more.
func (*Stores) Run ¶
Run looks at the stores after a pause at start and then twice a day, while the owner's settings allow looking for updates. A server with no stores asks nobody anything.
func (*Stores) SetEnabled ¶
SetEnabled turns a store on or off. Off, it isn't fetched or shown in the store, and nothing new can be installed from it. What's already installed from it stays, labelled, until it's removed or put back to the official version.
func (*Stores) UndoRun ¶
UndoRun takes the last Update All back: each module it moved goes back to what it was using, and the version it moved to isn't installed by itself again.
func (*Stores) UpdateAll ¶
UpdateAll starts updating every module with an update, in order of what's built on what.
func (*Stores) UpdateCount ¶
UpdateCount is how many modules Update All would change now.
func (*Stores) UseFork ¶
func (s *Stores) UseFork(store, id, by string, confirm bool, seen string, accept *OverrideAccept) error
UseFork makes a store's version of a module the one this server uses: the choice a fork needs, with its warning, and then the newest version that fits, which also has its own signature and manifest to pass. Without confirm it answers *ErrNeedsConfirm and changes nothing. seen is the fingerprint the admin was shown, when the page sends it: the store may have named another key since, and that one wasn't agreed to.
type StoresConfig ¶
type StoresConfig struct {
Manager *Manager
Dir string // <data>/modules
Transport http.RoundTripper // internet-only
Log *slog.Logger
CheckEnabled func() bool
}
StoresConfig prepares Stores.
type Tuners ¶
type Tuners struct{ M *Manager }
Tuners makes WittyTuner's sources for the server. Every question is a helper of its own, which leaves when it has answered, so nothing runs while no one is watching and a new version takes over with no restart.
What is a helper's to say and what isn't: it may say a channel is protected or busy, since that only ever refuses something. It can't say a channel is clear. Every stream it hands over is watched by this server's own guard, and the server only believes what that guard sees. WittyTuner has no forks for the same reason. What it asks FFmpeg to open is held to checkInput, since FFmpeg's options can read files and run other protocols.
type UIAdds ¶
UIAdds is what a module in use adds to every app, from its sdui.json, for its page in the store.
type Upload ¶
type Upload struct {
Archive string // the archive, saved by the caller, with its name's extension (.tar.gz or .zip)
Sums, Sig []byte // the checksum list and its signature, when they came with it
Key string // a publisher key, base64, to check the signature against
By int64 // the administrator who uploaded it
ArchiveName string
}
Upload is a module release someone chose from their computer.
type UploadInfo ¶
type UploadInfo struct {
Token string `json:"token,omitempty"`
Expires int64 `json:"expiresAt,omitempty"`
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Delivery string `json:"delivery"`
API int `json:"api"`
ReleaseStatus string `json:"releaseStatus"`
StatusNote string `json:"statusNote,omitempty"`
Signed bool `json:"signed"`
Trusted bool `json:"trusted"`
Fingerprint string `json:"fingerprint,omitempty"`
Permissions []string `json:"permissions"`
Problems []UploadProblem `json:"problems"`
NeedsOverride *ErrNeedsOverride `json:"needsOverride,omitempty"`
Refusal string `json:"refusal,omitempty"`
Known bool `json:"known"` // a module this server knows
}
UploadInfo says what an uploaded file is and what installing it would take.
type UploadProblem ¶
UploadProblem is one thing about an upload that needs an override.
type VersionInfo ¶
type VersionInfo struct {
Offer
Builtin bool `json:"builtin,omitempty"` // the copy compiled into this server
License string `json:"license,omitempty"`
Permissions []string `json:"permissions,omitempty"`
InUse bool `json:"inUse,omitempty"` // the version running now
Installed bool `json:"installed,omitempty"` // on disk, so switching needs no download
Older bool `json:"older,omitempty"` // older than the version in use
Allowed bool `json:"allowed"` // it can be chosen
Refused string `json:"refused,omitempty"` // why it can't, in words for a person
Warning string `json:"warning,omitempty"` // what to know first; choosing it needs confirming; for Offer.OlderServer, confirmOlder too
Withdrawn *wittymodule.Withdrawn `json:"withdrawn,omitempty"`
}
VersionInfo is one version, explained: what it is, and whether it can be chosen.
type VersionList ¶
type VersionList struct {
ID string `json:"id"`
Name string `json:"name"`
Repo string `json:"repo"`
InUse string `json:"inUse"`
Pin string `json:"pin,omitempty"`
CheckedAt int64 `json:"checkedAt,omitempty"`
Versions []VersionInfo `json:"versions"`
}
VersionList is everything known about a module's versions.
type VersionProblem ¶
VersionProblem is why an installed version can't be used.
func CheckInstalled ¶
func CheckInstalled(dir, id, ver, server string, st InstalledState) *VersionProblem
CheckInstalled looks at an installed version as a starting server would. It returns nil when the version would be used.
func (*VersionProblem) Error ¶
func (p *VersionProblem) Error() string
type Viewer ¶
type Viewer struct {
// User is the account the page is for, for a module's own data about that person.
User int64 `json:"user,omitempty"`
ProfileKind string `json:"profileKind"`
Admin bool `json:"admin,omitempty"`
// Cannot are the parental feature switches that are off for it.
Cannot []string `json:"cannot,omitempty"`
FormFactor string `json:"formFactor,omitempty"`
Platform string `json:"platform,omitempty"`
Locale string `json:"locale,omitempty"`
}
Viewer describes the profile a page is drawn for, as much as a module needs.
type WebBundle ¶
type WebBundle struct {
ID string `json:"id"`
Version string `json:"version"`
Entry string `json:"entry"` // the script, under Base
Style string `json:"style,omitempty"` // a stylesheet, under Base
Base string `json:"base"`
API int `json:"api"`
// Pages are what it adds to the app's menus.
Pages []wittymodule.Page `json:"pages,omitempty"`
// Views are the IDs of the views of its own in its SDUI (docs/SDUI-MODULES.md, "Views"):
// the bundle exports a component for each, and the web app says it can draw them.
Views []string `json:"views,omitempty"`
// Integration is what its integration.json says the bundle adds to the web app (module
// API 5): its routes and frames, cards, players, readers, Settings sections, setup steps
// and menu folding, so the app knows before loading any of its code. The bundle's
// register(host) export hands over the components.
Integration *wittymodule.WebPart `json:"integration,omitempty"`
}
WebBundle says where the browser finds a bundle in use.
Source Files
¶
- attached.go
- catalog.go
- catalog_extras.go
- catalogue.go
- cdengine.go
- doctor.go
- failure.go
- feed.go
- filebrowser.go
- forklimits_linux.go
- gamefailures.go
- install.go
- integration.go
- logtopics.go
- manager.go
- override.go
- override_install.go
- proc.go
- protocol.go
- sandbox.go
- sandbox_linux.go
- sandbox_network_other.go
- sandbox_profile.go
- sandbox_weak_other.go
- sdui.go
- seccomp_linux_amd64.go
- service.go
- source.go
- storefetch.go
- storelist.go
- storerun.go
- stores.go
- storesource.go
- tasks.go
- tuner.go
- web.go
- widen.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bdremote runs a Blu-ray session's engine in a helper process, of the WittyBluray version in use.
|
Package bdremote runs a Blu-ray session's engine in a helper process, of the WittyBluray version in use. |
|
Package dvdremote plays a disc through the WittyDVD version in use: a helper process for each open disc, behind the interfaces a session uses.
|
Package dvdremote plays a disc through the WittyDVD version in use: a helper process for each open disc, behind the interfaces a session uses. |
|
Package modtest gives a test real modules, from a catalogue on this machine: the one scripts/make-test-catalog.sh makes.
|
Package modtest gives a test real modules, from a catalogue on this machine: the one scripts/make-test-catalog.sh makes. |