service

package
v0.5.2 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: 23 Imported by: 0

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

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

View Source
const CallBusy = "service.busy"

CallBusy asks a service whether it has work going on, before it's stopped for being idle.

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

View Source
const MethodStart = "service"

MethodStart is the helper call that says where the service is.

View Source
const TokenHeader = "X-Witty-Service-Token"

TokenHeader carries the start's secret on every request.

Variables

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

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

View Source
var ErrNoService = errors.New("this module isn't on this server")

ErrNoService: nothing has been set up to reach a service with.

Functions

func Admins added in v0.5.0

func Admins(next http.Handler) http.Handler

Admins wraps a route for administrators only.

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

func Call(ctx context.Context, module, name string, recv, back any, args []any, out []any) error

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

func EncodeItem(it Item) string

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 Marshal

func Marshal(v any) ([]byte, error)

Marshal writes a value for the other side.

func OnStart

func OnStart(module string, fn func(*Conn))

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

func People(next http.Handler) http.Handler

People wraps a route for signed-in people only: what the server checked, checked again.

func Recv

func Recv(raw json.RawMessage, v any) error

Recv reads a call's receiver.

func RegisterError

func RegisterError(code string, err error)

RegisterError says which error a code means here.

func RegisterErrorType

func RegisterErrorType[T any, P interface {
	*T
	error
}](name string)

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

func RunStarted(module string, c *Conn)

RunStarted runs what OnStart was given. A server calls it with a new connection.

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal reads what Marshal wrote.

Types

type CallError

type CallError struct {
	Code    string
	Message string
	// contains filtered or unexported fields
}

CallError is a service saying no, with its words.

func (*CallError) Error

func (e *CallError) Error() string

func (*CallError) Unwrap

func (e *CallError) Unwrap() error

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.

func (*Conn) Call

func (c *Conn) Call(ctx context.Context, name string, recv, back any, args []any, out []any) error

Call makes a call on this connection.

type File added in v0.5.0

type File struct {
	Path string `json:"path"`
	Size int64  `json:"size"`
}

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.

func Who added in v0.5.0

func Who(r *http.Request) Identity

Who reads who is asking. A request with no user wasn't a signed-in person's (a ticket route, or something else on this machine), and a route for people refuses it.

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.

type Started

type Started struct {
	URL   string `json:"url"`
	Token string `json:"token"`
}

Started is the answer to it.

Jump to

Keyboard shortcuts

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