Documentation
¶
Overview ¶
Package gamestream speaks the protocol a Sunshine server offers to its clients: finding a PC, pairing with it, listing what it offers and starting it. Written from the protocol, and talks over the network only: it contains no Sunshine or Moonlight code. See docs/GAME-RIGS.md.
Index ¶
- Constants
- Variables
- func CertFingerprint(certPEM []byte) string
- func CleanAddress(s string) (host string, port int, err error)
- func MagicPacket(hw net.HardwareAddr) []byte
- func NewPIN() (string, error)
- func ParseMAC(s string) (net.HardwareAddr, error)
- func ValidPIN(pin string) bool
- func Wake(mac, lastAddress string) error
- type App
- type Found
- type Identity
- type Info
- type Launched
- type Policy
- type Reach
- type Rig
- func (r *Rig) AppImage(ctx context.Context, id int) (data []byte, ext string, err error)
- func (r *Rig) Apps(ctx context.Context) ([]App, error)
- func (r *Rig) Hello(ctx context.Context) (*Info, error)
- func (r *Rig) Launch(ctx context.Context, o StreamOptions) (*Launched, error)
- func (r *Rig) Pair(ctx context.Context, pin string) ([]byte, error)
- func (r *Rig) Quit(ctx context.Context) error
- func (r *Rig) Resume(ctx context.Context, o StreamOptions) (*Launched, error)
- func (r *Rig) StartOnly(ctx context.Context, appID int) error
- func (r *Rig) Status(ctx context.Context) (*Info, error)
- func (r *Rig) SubmitPIN(ctx context.Context, user, password, pin, deviceName string) error
- func (r *Rig) WebURL() string
- type StatusError
- type StreamOptions
Constants ¶
const (
DefaultPort = 47989 // HTTP: identity and pairing
)
Sunshine's ports, for the default base port. Every port moves with the base.
const DeviceName = "WittyMediaServer"
DeviceName is how this server appears in Sunshine's list of paired devices.
const PairTimeout = 3 * time.Minute
PairTimeout is how long someone gets to walk to the PC and type the PIN.
Variables ¶
var ( ErrRefused = errors.New("the PC is on, but Sunshine isn't running on it") ErrNoAnswer = errors.New("the PC isn't answering: it's asleep, off or not on this network") ErrCertChanged = errors.New("something other than the PC you paired with answered: its certificate is different") ErrNotPaired = errors.New("the PC no longer trusts this server. Pair it again") ErrBadAnswer = errors.New("the PC answered with something that isn't from Sunshine") ErrBlocked = errors.New("that address isn't allowed") ErrBusy = errors.New("another game is running on the PC") )
Why a rig didn't answer. Each of these can be explained to a person.
var ( ErrWrongPIN = errors.New("That PIN didn't match. Try again, typing the PIN shown here into Sunshine") ErrAlreadyPairing = errors.New("Sunshine is already pairing with something. Finish or cancel that first") ErrPairTimedOut = errors.New("Nobody typed the PIN into Sunshine in time. Start again when you're at the PC") ErrTooOld = errors.New("This PC is running something older than Sunshine. Install a current Sunshine") ErrImposter = errors.New("Something on your network tried to pose as this PC, so pairing was stopped") )
var ( ErrWebSignIn = errors.New("Sunshine didn't accept that user name and password") ErrWebDenied = errors.New("Sunshine's web interface refused this server. Its setting \"Origin Web UI Allowed\" has to include your network") ErrNoPending = errors.New("No device is waiting to pair. Start pairing on the device first, then type its PIN here") ErrManyWait = errors.New("Several devices are waiting to pair. Type the device's name as Sunshine shows it") )
var ErrBadAddress = errors.New("Type just the PC's name or IP address, like 192.168.1.20 or gaming-pc")
ErrBadAddress: what was typed isn't a computer's name or address.
Functions ¶
func CertFingerprint ¶
CertFingerprint is the SHA-256 of a pinned certificate, for showing to an admin.
func CleanAddress ¶
CleanAddress checks an address someone typed: a name or an IP and nothing else, with a port if one follows. There is no scheme, path, user name or anything else that could point a request somewhere unexpected.
func MagicPacket ¶
func MagicPacket(hw net.HardwareAddr) []byte
MagicPacket is six bytes of 0xFF and then the MAC address sixteen times.
Types ¶
type Found ¶
type Found struct {
Name string `json:"name"`
Address string `json:"address"`
Port int `json:"port"`
}
Found is one PC that answered.
type Identity ¶
type Identity struct {
ID string // 16 hex characters, sent as uniqueid
CertPEM []byte
// Dir is the folder it's kept in, which is how a server names it to this module's service:
// the key itself never leaves this side.
Dir string
// contains filtered or unexported fields
}
Identity is the certificate this server shows to a rig. Sunshine trusts a client by its certificate, so the private key is what stands between anyone else and the rig's games: it stays in a file of its own, never in the database or an API answer.
func LoadOrCreateIdentity ¶
LoadOrCreateIdentity reads the identity kept in dir, making one the first time. The key file is readable only by this server's account where the system allows it.
func NewIdentity ¶
NewIdentity makes a new certificate. GameStream expects RSA, and a rig keeps a certificate for as long as it stays paired, so this one lasts twenty years.
func (*Identity) UnmarshalJSON ¶
UnmarshalJSON finds an identity by the folder it's kept in.
type Info ¶
type Info struct {
Name string `xml:"hostname" json:"name"`
Version string `xml:"appversion" json:"version"`
GfeVersion string `xml:"GfeVersion" json:"-"`
CodecModes int `xml:"ServerCodecModeSupport" json:"-"`
UUID string `xml:"uniqueid" json:"uuid"`
MAC string `xml:"mac" json:"-"`
CurrentGame int `xml:"currentgame" json:"currentGame"`
State string `xml:"state" json:"-"`
Paired int `xml:"PairStatus" json:"-"`
}
Info is what a PC says about itself.
type Launched ¶
type Launched struct {
SessionURL string
}
Launched is what the PC says when a stream can begin.
type Policy ¶
type Policy struct {
AllowPublic bool // the internet may be reached
DenyPrivate bool // the home network and private overlays may not
DenyLoopback bool // this machine may not, which is for admins only
}
Policy decides which addresses connections may go to. It is checked when the connection is made, not only when an address is typed, so a name that later resolves somewhere else is caught.
type Reach ¶
type Reach int
Reach is what kind of place an address is.
func CheckAddress ¶
func CheckAddress(ctx context.Context, host string, lookup func(context.Context, string) ([]netip.Addr, error)) (Reach, error)
CheckAddress resolves a cleaned address and says what kind of place it is. When a name has several addresses, the least safe one decides, as a connection may use any of them.
type Rig ¶
type Rig struct {
Address string
Port int // the base port; 0 means the default
Identity *Identity
Cert []byte // PEM, from pairing
Policy Policy
}
Rig is one PC running Sunshine. Cert is the certificate pinned at pairing: once it is set, nothing else is accepted on the encrypted ports, whatever the network says.
func (*Rig) AppImage ¶
AppImage fetches an app's box art. The bytes come from another computer, so they must look like a PNG or JPEG, and a caller stores and serves them as nothing else.
func (*Rig) Apps ¶
Apps lists what the PC offers. Titles come from the PC, so they are clipped here and only ever shown as text.
func (*Rig) Hello ¶
Hello asks over plain HTTP who this PC is. Nothing here can be trusted yet, and it says nothing that needs protecting: this is how a new rig is recognised.
func (*Rig) Pair ¶
Pair runs the whole exchange. The first request waits, with the connection held open, until someone types the PIN into Sunshine or ctx ends. It returns the PC's certificate in PEM form, ready to pin.
func (*Rig) Quit ¶
Quit ends whatever is running on the PC, and any stream of it. A PC answers once the game has gone, which can take a while, and it answers nothing else until then.
func (*Rig) StartOnly ¶
StartOnly starts an app for a Moonlight app to pick up with Resume. The stream keys sent here are thrown away, as nothing here will stream with them.
func (*Rig) Status ¶
Status asks a paired PC over its pinned connection, which also gives its MAC address and proves it is still the same PC, and that it still trusts this server.
type StatusError ¶
StatusError is a refusal from Sunshine, with its own message.
func (*StatusError) Error ¶
func (e *StatusError) Error() string
type StreamOptions ¶
type StreamOptions struct {
AppID int
Width, Height int
FPS int
Key, IV [16]byte
LocalAudio bool // also play the sound on the PC itself
}
StreamOptions are what a stream is asked for. Key and IV protect the stream's input, and are made fresh for each one by whoever is going to receive it.