service

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 21 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 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 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 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 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()
	// 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.

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