gamestream

package
v0.4.1 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: 34 Imported by: 0

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

View Source
const (
	DefaultPort = 47989 // HTTP: identity and pairing

)

Sunshine's ports, for the default base port. Every port moves with the base.

View Source
const DeviceName = "WittyMediaServer"

DeviceName is how this server appears in Sunshine's list of paired devices.

View Source
const PairTimeout = 3 * time.Minute

PairTimeout is how long someone gets to walk to the PC and type the PIN.

Variables

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

View Source
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")
)
View Source
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")
)
View Source
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

func CertFingerprint(certPEM []byte) string

CertFingerprint is the SHA-256 of a pinned certificate, for showing to an admin.

func CleanAddress

func CleanAddress(s string) (host string, port int, err error)

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.

func NewPIN

func NewPIN() (string, error)

NewPIN makes the four digits a person types into Sunshine.

func ParseMAC

func ParseMAC(s string) (net.HardwareAddr, error)

ParseMAC checks a MAC address. All zeroes is what Sunshine says when it won't name it, and a group address would wake a whole network.

func ValidPIN

func ValidPIN(pin string) bool

ValidPIN: exactly four digits.

func Wake

func Wake(mac, lastAddress string) error

Wake sends the packet to every network this machine is on, and straight to the PC's last known address, which is the only way that crosses to another subnet or a VPN.

Types

type App

type App struct {
	ID    int    `xml:"ID" json:"id"`
	Title string `xml:"AppTitle" json:"title"`
}

App is one thing a rig offers to run.

type Found

type Found struct {
	Name    string `json:"name"`
	Address string `json:"address"`
	Port    int    `json:"port"`
}

Found is one PC that answered.

func Browse

func Browse(ctx context.Context, wait time.Duration) ([]Found, error)

Browse asks the home network who runs Sunshine, and listens for wait. It costs nothing until someone presses Find, and it doesn't keep a socket open afterwards.

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

func LoadOrCreateIdentity(dir string) (*Identity, error)

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

func NewIdentity() (*Identity, error)

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

func (i *Identity) UnmarshalJSON(b []byte) error

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.

func (Policy) Allow

func (p Policy) Allow(ip netip.Addr) error

Allow reports whether a connection may go to ip.

type Reach

type Reach int

Reach is what kind of place an address is.

const (
	Unusable Reach = iota // nothing a computer could be: multicast, link-local, unspecified
	Loopback              // this machine
	Private               // the home network, or a private overlay network
	Public                // the internet
)

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.

func Classify

func Classify(ip netip.Addr) Reach

Classify says what kind of place an address is. Link-local addresses count as unusable: 169.254.169.254 is where cloud machines keep their credentials.

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

func (r *Rig) AppImage(ctx context.Context, id int) (data []byte, ext string, err error)

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

func (r *Rig) Apps(ctx context.Context) ([]App, error)

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

func (r *Rig) Hello(ctx context.Context) (*Info, error)

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

func (r *Rig) Launch(ctx context.Context, o StreamOptions) (*Launched, error)

Launch asks the PC to start an app and get ready to stream it.

func (*Rig) Pair

func (r *Rig) Pair(ctx context.Context, pin string) ([]byte, error)

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

func (r *Rig) Quit(ctx context.Context) error

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

func (r *Rig) Resume(ctx context.Context, o StreamOptions) (*Launched, error)

Resume asks the PC to stream what it's already running.

func (*Rig) StartOnly

func (r *Rig) StartOnly(ctx context.Context, appID int) error

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

func (r *Rig) Status(ctx context.Context) (*Info, error)

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.

func (*Rig) SubmitPIN

func (r *Rig) SubmitPIN(ctx context.Context, user, password, pin, deviceName string) error

SubmitPIN gives Sunshine a PIN for a device that is waiting to pair. Newer versions of Sunshine name each waiting device; older ones take the PIN for whichever is waiting.

func (*Rig) WebURL

func (r *Rig) WebURL() string

WebURL is Sunshine's own web interface on this PC.

type StatusError

type StatusError struct {
	Code    int
	Message string
}

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.

Directories

Path Synopsis
Package fake is a stand-in for Sunshine, for tests.
Package fake is a stand-in for Sunshine, for tests.

Jump to

Keyboard shortcuts

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