host

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

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

View Source
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.

View Source
const Base = "/host/v1"

Base is where the host API's paths start.

View Source
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).

View Source
const Version = 1

Version is the host API this package speaks.

Variables

View Source
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.

View Source
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 IsForbidden(err error) bool

func IsNotFound

func IsNotFound(err error) bool

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

func New() (*Client, error)

New is a client for the server that started this service, from what it said at the start.

func NewAt

func NewAt(base, token string, offers map[string]int) *Client

NewAt is a client for a host API at an address, for tests.

func (*Client) Audit

func (c *Client) Audit(ctx context.Context, on On, action, core, detail string) error

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

func (c *Client) AuditLog(ctx context.Context, limit int) ([]AuditRow, error)

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

func (c *Client) Do(ctx context.Context, on On, method, path string, body, out any) error

Do makes one call: a JSON body in (unless body is an io.Reader), JSON out into out.

func (*Client) EndSession

func (c *Client) EndSession(ctx context.Context, id string) error

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

func (c *Client) Facets(ctx context.Context, on On, library int64) (json.RawMessage, error)

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) Has

func (c *Client) Has(feature string, v int) bool

Has reports whether the server offers a host feature at a version at least v.

func (*Client) Hello

func (c *Client) Hello(ctx context.Context) (Hello, error)

Hello asks.

func (*Client) Item

func (c *Client) Item(ctx context.Context, on On, id int64) (service.Item, error)

Item is one item, with its files, if the person may see it.

func (*Client) Items

func (c *Client) Items(ctx context.Context, on On, q Query) ([]service.Item, error)

Items lists the items a person may see that match, without their files.

func (*Client) ItemsFull

func (c *Client) ItemsFull(ctx context.Context, on On, q Query) ([]json.RawMessage, error)

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

func (c *Client) Libraries(ctx context.Context) ([]Library, error)

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

func (c *Client) May(ctx context.Context, on On, feature string) (bool, error)

May reports whether a person may use a feature (games, livetv …) now: their profile's limits, parental rules and screen time.

func (*Client) Notify

func (c *Client) Notify(ctx context.Context, user int64, text, link string) error

Notify tells a person something, with a place in the app to go to.

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) Report

func (c *Client) Report(ctx context.Context, r Report) error

Report tells the server.

func (*Client) Rescan added in v0.5.3

func (c *Client) Rescan(ctx context.Context, library int64) error

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

func (c *Client) Secret(ctx context.Context, name string) (string, error)

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

func (c *Client) Settings(ctx context.Context, on On) (map[string]json.RawMessage, error)

Settings are the module's settings (its sdui.json settings), for everyone, or a person's own.

func (*Client) StartSession

func (c *Client) StartSession(ctx context.Context, s Session) (string, error)

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).

func (*Client) Task

func (c *Client) Task(ctx context.Context, name string, done, total int, err error) error

Task reports a long piece of work, shown with the server's tasks.

func (*Client) Tools

func (c *Client) Tools(ctx context.Context) (Tools, error)

Tools asks for the server's FFmpeg.

func (*Client) Users

func (c *Client) Users(ctx context.Context) ([]User, error)

Users is every account on the server.

type Error

type Error struct {
	Status  int
	Message string `json:"error"`
}

Error is what the server said when it refused a call.

func (*Error) Error

func (e *Error) Error() string

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 On

type On struct {
	User    int64
	Profile string
}

On is who a call is for.

func For

func For(r *http.Request) On

For is the person a module route's request is from.

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

type Report struct {
	Working bool   `json:"working"`
	Reason  string `json:"reason,omitempty"`
}

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).

Jump to

Keyboard shortcuts

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