portal

README

A lightweight transfer proxy written in Go for Minecraft: Bedrock Edition.

Installation

1. Download the latest release for your platform from the GitHub releases page
2. Move it to a directory of your choice, and run from the command line.

Note for Linux/macOS users: run chmod +x on the binary to make it executable.

Configuration

After running portal for the first time, a default configuration file called config.json will be created in the same directory as the program.

Overview of the configuration file

• network
  • address: The address on which the proxy should listen. Players may connect to this address in order to join. It should be in the format of "ip:port"
  • communication
    • address: Address is the address on which the communication service should listen. External connections can use this address in order to communicate with the proxy. It should be in the format of "ip:port"
    • secret: Secret is the authentication secret required by external connections in order to authenticate to the proxy and start communicating
• logger
  • file: File is the path to the file in which logs should be stored. If the path is empty then logs will not be written to a file
  • level: Level is the required level logs should have to be shown in console or in the file above
• player_latency
  • report: Determines if the proxy should send the proxy of a player to their server at a regular interval
  • update_interval: The interval to report a player's ping if report is true
• whitelist
  • enabled: Determines if the whitelist is enabled
  • players: A list of whitelisted players' usernames
• resource_packs
  • required: Determines if players are required to download the resource packs before connecting
  • directory: The directory to load resource packs from. They can be directories, .zip files or .mcpack files
  • encryption_keys: A map of resource pack UUIDs to their encryption key

Documentation

Index

• func LoadResourcePacks(dir string) ([]*resource.Pack, error)
• type Config
  • func DefaultConfig() (c Config)
• type MOTDStatusProvider
  • func NewMOTDStatusProvider(motd string) *MOTDStatusProvider
  • func (p *MOTDStatusProvider) MOTD(v string)
  • func (p *MOTDStatusProvider) ServerStatus(playerCount, maxPlayers int) minecraft.ServerStatus
• type Options
• type Portal
  • func New(opts Options) *Portal
  • func (p *Portal) Accept() (*session.Session, error)
  • func (p *Portal) Disconnect(conn *minecraft.Conn, message string) error
  • func (p *Portal) Listen() error
  • func (p *Portal) LoadBalancer() session.LoadBalancer
  • func (p *Portal) Logger() internal.Logger
  • func (p *Portal) ServerRegistry() *server.Registry
  • func (p *Portal) SessionStore() *session.Store
  • func (p *Portal) SetLoadBalancer(loadBalancer session.LoadBalancer)

Functions

func LoadResourcePacks

func LoadResourcePacks(dir string) ([]*resource.Pack, error)

LoadResourcePacks attempts to load all the resource packs in the provided directory. If the directory does not exist, it will be created. If any pack fails to compile, the error will be returned.

Types

type Config

type Config struct {
	// Network holds settings related to network aspects of the proxy.
	Network struct {
		// Address is the address on which the proxy should listen. Players may connect to this address in
		// order to join. It should be in the format of "ip:port".
		Address string `json:"address"`
		// Communication holds settings related to the communication aspects of the proxy.
		Communication struct {
			// Address is the address on which the communication service should listen. External connections
			// can use this address in order to communicate with the proxy. It should be in the format of
			// "ip:port".
			Address string `json:"address"`
			// Secret is the authentication secret required by external connections in order to authenticate
			// to the proxy and start communicating.
			Secret string `json:"secret"`
		} `json:"communication"`
		// ReaderLimits determines if things like slices will have a maximum length as they are read from socket clients.
		// It is recommended that this is always set to true in order to prevent possible attack vectors, however if any
		// non-malicious clients are reaching these limits, you may want to disable it.
		ReaderLimits bool `json:"reader_limits"`
	} `json:"network"`
	// Logger holds settings related to the logging aspects of the proxy.
	Logger struct {
		// File is the path to the file in which logs should be stored. If the path is empty then logs will
		// not be written to a file.
		File string `json:"file"`
		// Level is the required level logs should have to be shown in console or in the file above.
		Level string `json:"level"`
	} `json:"logger"`
	// PlayerLatency holds settings related to the latency reporting aspects of the proxy.
	PlayerLatency struct {
		// Report is if the proxy should send the proxy of a player to their server at a regular interval.
		Report bool `json:"report"`
		// UpdateInterval is the interval to report a player's ping if Report is true.
		UpdateInterval int `json:"update_interval"`
	} `json:"player_latency"`
	// Whitelist holds settings related to the proxy whitelist.
	Whitelist struct {
		// Enabled is if the whitelist is enabled.
		Enabled bool `json:"enabled"`
		// Players is a list of whitelisted players' usernames.
		Players []string `json:"players"`
	} `json:"whitelist"`
	// ResourcePacks holds settings related to sending resource packs to players.
	ResourcePacks struct {
		// Required is if players are required to download the resource packs before connecting.
		Required bool `json:"required"`
		// Directory is the directory to load resource packs from. They can be directories, .zip files or .mcpack files.
		Directory string `json:"directory"`
		// EncryptionKeys is a map of resource pack UUIDs to their encryption key.
		EncryptionKeys map[string]string `json:"encryption_keys,omitempty"`
	} `json:"resource_packs"`
}

Config represents the base configuration for portal. It holds settings that affect different aspects of the proxy.

func DefaultConfig

func DefaultConfig() (c Config)

DefaultConfig returns a configuration with the default values filled out.

type MOTDStatusProvider

type MOTDStatusProvider struct {
	// contains filtered or unexported fields
}

MOTDStatusProvider represents a status provider that shows a custom MOTD which can be changed at any time.

func NewMOTDStatusProvider

func NewMOTDStatusProvider(motd string) *MOTDStatusProvider

NewMOTDStatusProvider creates a new server status provider which shows a custom message in the server list.

func (*MOTDStatusProvider) MOTD

func (p *MOTDStatusProvider) MOTD(v string)

MOTD sets the MOTD for the current provider.

func (*MOTDStatusProvider) ServerStatus

func (p *MOTDStatusProvider) ServerStatus(playerCount, maxPlayers int) minecraft.ServerStatus

ServerStatus ...

type Options

type Options struct {
	// Logger represents the logger that will be used for the lifetime of the proxy.
	Logger internal.Logger

	// Address is the address that the proxy should run on. It should be in the format of "address:port".
	Address string
	// ListenConfig contains settings that can be changed for the listener. It can be used to change the MOTD
	// and add resource packs etc.
	ListenConfig minecraft.ListenConfig

	// LoadBalancer is the method used to balance load across the servers on the proxy. It can be used to
	// change which servers players connect to when they join the proxy.
	LoadBalancer session.LoadBalancer

	// Whitelist is used to limit the proxy to only allow certain players to join.
	Whitelist session.Whitelist
}

Options represents the options that control how the proxy should be set up. After the proxy has been instantiated, the options below are immutable unless instantiated again.

type Portal

type Portal struct {
	// contains filtered or unexported fields
}

Portal represents the proxy and controls its functionality.

func New

func New(opts Options) *Portal

New instantiates portal using the provided options and returns it. If some options are not set, default values will be used in replacement.

func (*Portal) Accept

func (p *Portal) Accept() (*session.Session, error)

Accept accepts a fully connected (on Minecraft layer) connection which is ready to receive and send packets. If the listener is closed or the player failed to spawn in then an error will be returned. When an error is returned the session is also returned, but it may be incomplete and contain nil values.

func (*Portal) Disconnect

func (p *Portal) Disconnect(conn *minecraft.Conn, message string) error

Disconnect disconnects a Minecraft Conn passed by first sending a disconnect with the message passed, and closing the connection after. If the message passed is empty, the client will be immediately sent to the player list instead of a disconnect screen.

func (*Portal) Listen

func (p *Portal) Listen() error

Listen starts to listen on the set address and allows connections from minecraft clients. An error is returned if the listener failed to listen.

func (*Portal) LoadBalancer

func (p *Portal) LoadBalancer() session.LoadBalancer

LoadBalancer returns the load balancer that handles the server a player joins when they first connect to the proxy.

func (*Portal) Logger

func (p *Portal) Logger() internal.Logger

Logger returns the global logger used by the proxy.

func (*Portal) ServerRegistry

func (p *Portal) ServerRegistry() *server.Registry

ServerRegistry returns the server registry provided to portal. It is used to store all the available servers.

func (*Portal) SessionStore

func (p *Portal) SessionStore() *session.Store

SessionStore returns the session store provided to portal. It is used to store all the open sessions.

func (*Portal) SetLoadBalancer

func (p *Portal) SetLoadBalancer(loadBalancer session.LoadBalancer)

SetLoadBalancer sets the load balancer that handles the server a player joins when they first connect to the proxy.