Documentation
¶
Overview ¶
Package host is a module's way back to the server that runs it (module API 5): library items and their files, whether a person may do something, the module's settings and secrets, pictures, live sessions, notifications, tasks and events. Both ends speak the paths below; the server's end is WittyMediaServer internal/modules/hostapi.go.
Every call that is on someone's behalf says so (On), and the server answers with that person's access, never more: a module can't see an item through the host that the person asking couldn't.
Index ¶
- Constants
- Variables
- func IsForbidden(err error) bool
- func IsNotFound(err error) bool
- func Needs(in *wittymodule.Integration, offers map[string]int) error
- type AuditRow
- type Client
- func (c *Client) Audit(ctx context.Context, on On, action, core, detail string) error
- func (c *Client) AuditLog(ctx context.Context, limit int) ([]AuditRow, error)
- func (c *Client) Counts(ctx context.Context, on On, libraryKind, facet string) (map[string]int, error)
- func (c *Client) CountsIn(ctx context.Context, on On, library int64, facet string) (map[string]int, error)
- func (c *Client) Do(ctx context.Context, on On, method, path string, body, out any) error
- func (c *Client) EndSession(ctx context.Context, id string) error
- func (c *Client) Events(ctx context.Context, after int64, wait time.Duration) ([]Event, int64, error)
- func (c *Client) Facets(ctx context.Context, on On, library int64) (json.RawMessage, error)
- func (c *Client) Has(feature string, v int) bool
- func (c *Client) Hello(ctx context.Context) (Hello, error)
- func (c *Client) Item(ctx context.Context, on On, id int64) (service.Item, error)
- func (c *Client) Items(ctx context.Context, on On, q Query) ([]service.Item, error)
- func (c *Client) ItemsFull(ctx context.Context, on On, q Query) ([]json.RawMessage, error)
- func (c *Client) Libraries(ctx context.Context) ([]Library, error)
- func (c *Client) May(ctx context.Context, on On, feature string) (bool, error)
- func (c *Client) Notify(ctx context.Context, user int64, text, link string) error
- func (c *Client) PutImage(ctx context.Context, item int64, role string, img io.Reader) (string, error)
- func (c *Client) Report(ctx context.Context, r Report) error
- func (c *Client) Rescan(ctx context.Context, library int64) error
- func (c *Client) Secret(ctx context.Context, name string) (string, error)
- func (c *Client) SetItem(ctx context.Context, f wittymodule.ItemFields) error
- func (c *Client) Settings(ctx context.Context, on On) (map[string]json.RawMessage, error)
- func (c *Client) StartSession(ctx context.Context, s Session) (string, error)
- func (c *Client) Task(ctx context.Context, name string, done, total int, err error) error
- func (c *Client) Tools(ctx context.Context) (Tools, error)
- func (c *Client) Users(ctx context.Context) ([]User, error)
- type Error
- type Event
- type Hello
- type Library
- type On
- type Query
- type Report
- type Session
- type SessionStop
- type Tools
- type User
Constants ¶
const ( HeaderToken = "X-Witty-Host-Token" // the secret the server gave this start HeaderOnUser = "X-Witty-On-User" // the person a call is for HeaderOnProf = "X-Witty-On-Profile" // and their profile, if not their own )
Headers on a host call.
const Base = "/host/v1"
Base is where the host API's paths start.
const EventSessionStop = "session.stop"
EventSessionStop is the event the server sends when it ends a session a module started: its person signed out or was deleted, their screen time ran out, or games were turned off for them. Data is SessionStop. The module stops it (the server has already let it go).
const Version = 1
Version is the host API this package speaks.
Variables ¶
var ErrNoHost = errors.New("this server has no host API (it is older than module API 5)")
ErrNoHost is returned when the server is older than module API 5 and has no host API.
var ErrNotOffered = errors.New("this server doesn't offer that")
ErrNotOffered is returned for a call the server doesn't offer.
Functions ¶
func IsForbidden ¶
func IsNotFound ¶
IsNotFound and IsForbidden tell the usual refusals apart.
func Needs ¶
func Needs(in *wittymodule.Integration, offers map[string]int) error
Needs is a module's host range check: whether this server offers every host feature the integration asks for, in range.
Types ¶
type AuditRow ¶
type AuditRow struct {
At int64 `json:"at"` // Unix seconds
User string `json:"user"`
Action string `json:"action"`
Core string `json:"core,omitempty"`
Detail string `json:"detail,omitempty"`
}
AuditRow is one row of the server's audit log.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls the host API.
func New ¶
New is a client for the server that started this service, from what it said at the start.
func (*Client) Audit ¶
Audit writes a row of the server's audit log: who (on), what, to what. The server keeps it, so it stays whatever happens to the module.
func (*Client) AuditLog ¶
AuditLog is the module's own rows of the audit log, newest first: at most limit, up to 500.
func (*Client) Counts ¶
func (c *Client) Counts(ctx context.Context, on On, libraryKind, facet string) (map[string]int, error)
Counts counts the items a person may see in the module's kinds of library, by a facet (console): what a console page says it has.
func (*Client) CountsIn ¶
func (c *Client) CountsIn(ctx context.Context, on On, library int64, facet string) (map[string]int, error)
CountsIn is Counts in one of the module's libraries.
func (*Client) Do ¶
Do makes one call: a JSON body in (unless body is an io.Reader), JSON out into out.
func (*Client) EndSession ¶
EndSession says it ended.
func (*Client) Events ¶
func (c *Client) Events(ctx context.Context, after int64, wait time.Duration) ([]Event, int64, error)
Events waits up to wait for events after seq, and returns them with the next seq to ask from.
func (*Client) Facets ¶
Facets is what one games library holds as a person may see it (consoles, genres, decades …), as the server's GET /api/v1/games/facets gives it.
func (*Client) ItemsFull ¶
ItemsFull lists the same items as the server's own brief item JSON, as its GET /api/v1/items gives each one (poster, rating, genres, progress …), for a module answering in that shape.
func (*Client) Libraries ¶
Libraries are the libraries of the kinds the module serves (all of them: this isn't on anyone's behalf, and the folders are for the module's own work, never shown to a person by it).
func (*Client) May ¶
May reports whether a person may use a feature (games, livetv …) now: their profile's limits, parental rules and screen time.
func (*Client) PutImage ¶
func (c *Client) PutImage(ctx context.Context, item int64, role string, img io.Reader) (string, error)
PutImage keeps a picture in the server's image cache, for an item's role (cover, logo, …) or for the module itself (item 0), and says the address pages can show it at.
func (*Client) Rescan ¶ added in v0.5.3
Rescan asks the server to scan a library of a kind the module scans, as soon as it can: after a person decided what a file is, say.
func (*Client) Secret ¶
Secret is a secret an administrator gave the module (a metadata service's key), or "".
func (*Client) SetItem ¶ added in v0.5.3
func (c *Client) SetItem(ctx context.Context, f wittymodule.ItemFields) error
SetItem sets an item's generic fields from what the module found out about it after a scan (scan hooks, wittymodule.ScanPart): only an item in a library of a kind the module scans. A field a person typed stays as they typed it.
func (*Client) Settings ¶
Settings are the module's settings (its sdui.json settings), for everyone, or a person's own.
func (*Client) StartSession ¶
StartSession tells the server something live started; it counts it for metrics, screen time and "playing now", and may end it (EndSession is then called by the server through the module's lifecycle events).
type Event ¶
type Event struct {
Seq int64 `json:"seq"`
Type string `json:"type"` // scan.finished, item.added, item.removed, user.deleted, profile.changed, session.stop, server.stopping
Data json.RawMessage `json:"data,omitempty"`
}
Event is something that happened on the server that a module may care about.
type Hello ¶
type Hello struct {
Module string `json:"module"`
Server string `json:"server"`
Offers map[string]int `json:"offers"`
// Machine is what whoever runs the machine has allowed, beyond the server's own settings:
// "gamingCustomCores" (the config file allows custom cores, and nothing locks them off) and
// "gamingTestCore" (the built-in test console is offered: a developer's server).
Machine map[string]bool `json:"machine,omitempty"`
}
Hello says which module the server thinks this is, and what it offers.
type Library ¶
type Library struct {
ID int64 `json:"id"`
Name string `json:"name"`
Kind string `json:"kind"` // games, …
Console string `json:"console,omitempty"` // a games library's console, or "auto"
Paths []string `json:"paths"` // its folders, for reading only (a BIOS sweep)
}
Library is one of the server's libraries of a kind the module serves.
type Query ¶
type Query struct {
LibraryKind string // games
Library int64 // one library
Kind string // an item kind
Facets map[string]string // console=snes
Search string
IDs []int64 // only these items (at most 500)
Sort string // added, rating, oldest or title; "" for by title
Desc bool // the other way round
MinRating float64 // at least this score out of 10
Genre string
Series string // games of one franchise
Offset int
Limit int // at most 500
}
Query picks items.
type Report ¶
Report is a module's word on its own version in use: Working after something that proves it (a game started), or a failure the server can't see itself. Three failures in a day take the version out of use.
type Session ¶
type Session struct {
ID string `json:"id,omitempty"` // the server's
Kind string `json:"kind"` // game, stream
User int64 `json:"user"`
Item int64 `json:"item,omitempty"`
Title string `json:"title,omitempty"`
// SignIn is the request's X-Witty-SignIn (service.Identity.SignIn): the sign-in that started
// it, so that signing out there ends it. Opaque; empty for none.
SignIn string `json:"signIn,omitempty"`
}
Session is something live: a game being played, a stream being watched.
type SessionStop ¶
type SessionStop struct {
ID string `json:"id"`
User int64 `json:"user"`
Reason string `json:"reason"`
}
SessionStop says which session the server ended, and why: signed-out, time-up, feature-off, gone.
type Tools ¶
type Tools struct {
FFmpeg string `json:"ffmpeg"`
FFprobe string `json:"ffprobe"`
Version string `json:"version,omitempty"`
Encoders map[string]bool `json:"encoders"`
// Hardware is the hardware encoders' test, once it has finished (HardwareDone).
Hardware []json.RawMessage `json:"hardware,omitempty"`
HardwareDone bool `json:"hardwareDone"`
}
Tools is the server's FFmpeg, and which encoders it found working.
type User ¶
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
DisplayName string `json:"displayName,omitempty"`
Kind string `json:"kind"` // adult, kids, guest
Admin bool `json:"admin,omitempty"`
LastSeen int64 `json:"lastSeen,omitempty"` // Unix seconds a sign-in of theirs was last used; 0 for none
}
User is an account on the server, as a module may know it: for showing names, and for a module's own lists of people (friends, who's online).