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 Arg(args []json.RawMessage, i int, v any) error
- func Call(ctx context.Context, module, name string, recv, back any, args []any, ...) error
- func Main(c Config)
- func Marshal(v any) ([]byte, error)
- func OnStart(module string, fn func(*Conn))
- 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 Handler
- type Started
Constants ¶
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 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 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()
// Busy says it has work going on, such as a game being played, with nobody calling.
Busy func() bool
}
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.