Documentation
¶
Overview ¶
Package service is how a module that stays running reaches a server: a process of its own that listens on this machine only, with a secret for each start, where calls can overlap and a browser's connection can be passed straight through. It is for what a pipe with one call at a time can't do, such as a game: everything else is a helper. Both ends are here, and nothing else, so a module and a server share this package and no code of each other's.
Index ¶
- Constants
- Variables
- func Admins(next http.Handler) http.Handler
- func Arg(args []json.RawMessage, i int, v any) error
- func Call(ctx context.Context, module, name string, recv, back any, args []any, ...) error
- func EncodeItem(it Item) string
- func Main(c Config)
- func Marshal(v any) ([]byte, error)
- func OnStart(module string, fn func(*Conn))
- func People(next http.Handler) http.Handler
- func Recv(raw json.RawMessage, v any) error
- func RegisterError(code string, err error)
- func RegisterErrorType[T any, P interface{ ... }](name string)
- func RunStarted(module string, c *Conn)
- func Unmarshal(data []byte, v any) error
- type CallError
- type Config
- type Conn
- type File
- type Handler
- type Identity
- type Item
- type StartParams
- type Started
Constants ¶
const ( HeaderUser = "X-Witty-User" // the signed-in account's id HeaderAdmin = "X-Witty-Admin" // "1" for an administrator HeaderProfile = "X-Witty-Profile" // the profile in use, when it isn't the account's own // HeaderItem is the item a route's "item" parameter names, already checked for this // profile: base64url JSON of Item. HeaderItem = "X-Witty-Item" // HeaderFeatures is the features this profile may use, space-separated; set on every // request to a module route. HeaderFeatures = "X-Witty-Features" // HeaderKind is the profile's kind: adult, kids or guest (a guest can only look). HeaderKind = "X-Witty-Kind" // HeaderConfirmed is "1" when the person gave their password with this request, and the // server found it right (a route with "confirm"). HeaderConfirmed = "X-Witty-Confirmed" // HeaderSignIn is an opaque name for the sign-in a request came from, for host.Session.SignIn. HeaderSignIn = "X-Witty-SignIn" // HeaderAway is "1" when the server counts the device as away from home (not on its network). HeaderAway = "X-Witty-Away" )
Headers a server tells a module's routes who is asking by. Only the server sets them: it drops every X-Witty- header a browser sends before it sets its own, and only the server holds the token that reaches a service at all.
const CallBusy = "service.busy"
CallBusy asks a service whether it has work going on, before it's stopped for being idle.
const DefaultLimit = 3 * time.Minute
DefaultLimit is what a call may take: a game loading can take a while, and a call with a deadline of its own has that instead.
const MethodStart = "service"
MethodStart is the helper call that says where the service is.
const TokenHeader = "X-Witty-Service-Token"
TokenHeader carries the start's secret on every request.
Variables ¶
var ( // Running says a module's service is running now, without starting it. Running func(module string) bool // Proxy passes a request straight through to a path of a module's service. Proxy func(module string, w http.ResponseWriter, r *http.Request, path string) error // Subscribe hears one kind of thing a module's service says unasked, until it next starts. Subscribe func(module, method string, fn func(json.RawMessage)) error )
What else a server sets as it starts.
var Dial func(module string) (*Conn, error)
Dial finds the service of a module, starting it if need be. A server sets it as it starts, and without it, or without the module, calls fail with what it returned.
var ErrNoService = errors.New("this module isn't on this server")
ErrNoService: nothing has been set up to reach a service with.
Functions ¶
func Arg ¶
func Arg(args []json.RawMessage, i int, v any) error
Arg reads one argument of a call. One the server left off stays at its zero value.
func Call ¶
Call makes a call to a module's service. back is the receiver to update, and out are where the results go. It returns the module's error, or why it couldn't be asked.
func EncodeItem ¶ added in v0.5.0
EncodeItem is HeaderItem's value for an item: the server's half of Who.
func Main ¶
func Main(c Config)
Main runs a service module. Started by hand, it explains itself instead of waiting silently.
func OnStart ¶
OnStart runs something each time a module's service starts: a service that stopped has forgotten anything it was told.
func People ¶ added in v0.5.0
People wraps a route for signed-in people only: what the server checked, checked again.
func RegisterError ¶
RegisterError says which error a code means here.
func RegisterErrorType ¶
RegisterErrorType says an error type has more to say than its words, so that errors.As finds it on the other side. Both sides register their own copy under the same name.
func RunStarted ¶
RunStarted runs what OnStart was given. A server calls it with a new connection.
Types ¶
type Config ¶
type Config struct {
Manifest []byte
Handlers map[string]Handler
// ErrorCode names an error the server has its own copy of.
ErrorCode func(error) string
// Routes adds whatever isn't a call, such as a stream a browser connects to.
Routes func(mux *http.ServeMux)
// OnStop runs when the server goes away, before the process does.
OnStop func()
// UI answers the server's SDUI calls on the helper protocol (sdui.items, sdui.image,
// settings.changed), for a module of API 4 whose sdui.json has sources, pictures or
// settings. Its zero value answers none of them.
UI sdui.Answers
// Busy says it has work going on, such as a game being played, with nobody calling.
Busy func() bool
// HTTP adds the module's own routes, those its integration.json lists (module API 5). The
// server passes a person's request for /api/modules/<id><path> (or an alias of it) to
// /http<path> here, once it has checked who may call it; Who says who is asking. Patterns
// are written without the /http prefix: "POST /games/{id}/play".
HTTP func(mux *http.ServeMux)
// Lifecycle answers the lifecycle calls its integration.json says it answers
// (wittymodule.CallInstall and the rest). An error rolls the install or upgrade back.
Lifecycle func(ctx context.Context, call string, args wittymodule.LifecycleArgs) error
}
Config is a service module's side of things.
type Conn ¶
type Conn struct {
Base *url.URL
Token string
Client *http.Client
// Limit is what a call may take with no deadline of its own; 0 means the default.
Limit time.Duration
}
Conn reaches a running service.
type File ¶ added in v0.5.0
File is one of an item's files. Path is for reading only: the module never writes there.
type Handler ¶
type Handler func(ctx context.Context, recv json.RawMessage, args []json.RawMessage) (rets []any, back any, err error)
Handler answers one call from a server: with its results, and with the receiver if the call changed it.
type Identity ¶ added in v0.5.0
type Identity struct {
User int64
Admin bool
Profile string
Kind string // adult, kids, guest
// Confirmed: the person gave their password with this request and it was right.
Confirmed bool
// SignIn names the sign-in the request came from, for host.Session.SignIn. Opaque.
SignIn string
// Away: the server counts the device as away from home, by its own rules (not the address's say).
Away bool
// Item is the item its route names, when it names one.
Item *Item
}
Identity is who a request to a module route is from.
type Item ¶ added in v0.5.0
type Item struct {
ID int64 `json:"id"`
Library int64 `json:"library"`
Kind string `json:"kind"` // the item kind: game, movie, …
Title string `json:"title"`
Facets map[string]string `json:"facets,omitempty"` // console, …
Files []File `json:"files,omitempty"`
}
Item is a library item as a server describes it to a module that was asked about it.
type StartParams ¶ added in v0.5.0
type StartParams struct {
Host string `json:"host,omitempty"` // http://127.0.0.1:port, this server's host API
HostToken string `json:"hostToken,omitempty"`
// Offers is what the server offers: host feature (wittymodule.HostHTTP …) → its version.
Offers map[string]int `json:"offers,omitempty"`
}
StartParams is what a server of module API 5 or newer tells a service as it starts it: where its host API is, and the secret for this start. An older server sends none.
func Host ¶ added in v0.5.0
func Host() StartParams
Host is where this service's host API is, as the server said at the start; zero when the server is older than module API 5.