environment

package
v0.0.0-...-8af54a5 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2024 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StateChangeEvent         = "state change"
	ResourceEvent            = "resources"
	DockerImagePullStarted   = "docker image pull started"
	DockerImagePullStatus    = "docker image pull status"
	DockerImagePullCompleted = "docker image pull completed"
)
View Source 
const (
	ProcessOfflineState  = "offline"
	ProcessStartingState = "starting"
	ProcessRunningState  = "running"
	ProcessStoppingState = "stopping"
)

Variables

This section is empty.

Functions

func ConfigureDocker 

func ConfigureDocker(ctx context.Context) error

ConfigureDocker configures the required network for the docker environment.

func Docker 

func Docker() (*client.Client, error)

Docker returns a docker client to be used throughout the codebase. Once a client has been created it will be returned for all subsequent calls to this function.

Types

type Allocations 

type Allocations struct {
	// ForceOutgoingIP causes a dedicated bridge network to be created for the
	// server with a special option, causing Docker to SNAT outgoing traffic to
	// the DefaultMapping's IP. This is important to servers which rely on external
	// services that check the IP of the server (Source Engine servers, for example).
	ForceOutgoingIP bool `json:"force_outgoing_ip"`
	// Defines the default allocation that should be used for this server. This is
	// what will be used for {SERVER_IP} and {SERVER_PORT} when modifying configuration
	// files or the startup arguments for a server.
	DefaultMapping struct {
		Ip   string `json:"ip"`
		Port int    `json:"port"`
	} `json:"default"`

	// Mappings contains all the ports that should be assigned to a given server
	// attached to the IP they correspond to.
	Mappings map[string][]int `json:"mappings"`
}

Defines the allocations available for a given server. When using the Docker environment driver these correspond to mappings for the container that allow external connections.

func (*Allocations) Bindings 

func (a *Allocations) Bindings() nat.PortMap

Converts the server allocation mappings into a format that can be understood by Docker. While we do strive to support multiple environments, using Docker's standardized format for the bindings certainly makes life a little easier for managing things.

You'll want to use DockerBindings() if you need to re-map 127.0.0.1 to the Docker interface.

func (*Allocations) DockerBindings 

func (a *Allocations) DockerBindings() nat.PortMap

Returns the bindings for the server in a way that is supported correctly by Docker. This replaces any reference to 127.0.0.1 with the IP of the pterodactyl0 network interface which will allow the server to operate on a local address while still being accessible by other containers.

func (*Allocations) Exposed 

func (a *Allocations) Exposed() nat.PortSet

Converts the server allocation mappings into a PortSet that can be understood by Docker. This formatting is slightly different than "Bindings" as it should return an empty struct rather than a binding.

To accomplish this, we'll just get the values from "DockerBindings" and then set them to empty structs. Because why not.

type Configuration 

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

Defines the actual configuration struct for the environment with all of the settings defined within it.

func NewConfiguration 

func NewConfiguration(s Settings, envVars []string) *Configuration

Returns a new environment configuration with the given settings and environment variables defined within it.

func (*Configuration) Allocations 

func (c *Configuration) Allocations() Allocations

Returns the allocations associated with this environment.

func (*Configuration) EnvironmentVariables 

func (c *Configuration) EnvironmentVariables() []string

Returns the environment variables associated with this instance.

func (*Configuration) Labels 

func (c *Configuration) Labels() map[string]string

Labels returns the container labels associated with this instance.

func (*Configuration) Limits 

func (c *Configuration) Limits() Limits

Returns the limits assigned to this environment.

func (*Configuration) Mounts 

func (c *Configuration) Mounts() []Mount

Returns all of the mounts associated with this environment.

func (*Configuration) SetEnvironmentVariables 

func (c *Configuration) SetEnvironmentVariables(ev []string)

Updates the environment variables associated with this environment by replacing the entire array of them with a new one.

func (*Configuration) SetSettings 

func (c *Configuration) SetSettings(s Settings)

Updates the settings struct for this environment on the fly. This allows modified servers to automatically push those changes to the environment.

type Limits 

type Limits struct {
	// The total amount of memory in mebibytes that this server is allowed to
	// use on the host system.
	MemoryLimit int64 `json:"memory_limit"`

	// The amount of additional swap space to be provided to a container instance.
	Swap int64 `json:"swap"`

	// The relative weight for IO operations in a container. This is relative to other
	// containers on the system and should be a value between 10 and 1000.
	IoWeight uint16 `json:"io_weight"`

	// The percentage of CPU that this instance is allowed to consume relative to
	// the host. A value of 200% represents complete utilization of two cores. This
	// should be a value between 1 and THREAD_COUNT * 100.
	CpuLimit int64 `json:"cpu_limit"`

	// The amount of disk space in megabytes that a server is allowed to use.
	DiskSpace int64 `json:"disk_space"`

	// Sets which CPU threads can be used by the docker instance.
	Threads string `json:"threads"`

	OOMDisabled bool `json:"oom_disabled"`
}

Limits is the build settings for a given server that impact docker container creation and resource limits for a server instance.

func (Limits) AsContainerResources 

func (l Limits) AsContainerResources() container.Resources

AsContainerResources returns the available resources for a container in a format that Docker understands.

func (Limits) BoundedMemoryLimit 

func (l Limits) BoundedMemoryLimit() int64

func (Limits) ConvertedCpuLimit 

func (l Limits) ConvertedCpuLimit() int64

ConvertedCpuLimit converts the CPU limit for a server build into a number that can be better understood by the Docker environment. If there is no limit set, return -1 which will indicate to Docker that it has unlimited CPU quota.

func (Limits) ConvertedSwap 

func (l Limits) ConvertedSwap() int64

ConvertedSwap returns the amount of swap available as a total in bytes. This is returned as the amount of memory available to the server initially, PLUS the amount of additional swap to include which is the format used by Docker.

func (Limits) MemoryOverheadMultiplier 

func (l Limits) MemoryOverheadMultiplier() float64

MemoryOverheadMultiplier sets the hard limit for memory usage to be 5% more than the amount of memory assigned to the server. If the memory limit for the server is < 4G, use 10%, if less than 2G use 15%. This avoids unexpected crashes from processes like Java which run over the limit.

func (Limits) ProcessLimit 

func (l Limits) ProcessLimit() int64

ProcessLimit returns the process limit for a container. This is currently defined at a system level and not on a per-server basis.

type Mount 

type Mount struct {
	// In Docker environments this makes no difference, however in a non-Docker environment you
	// should treat the "Default" mount as the root directory for the server. All other mounts
	// are just in addition to that one, and generally things like shared maps or timezone data.
	Default bool `json:"-"`

	// The target path on the system. This is "/home/container" for all server's Default mount
	// but in non-container environments you can likely ignore the target and just work with the
	// source.
	Target string `json:"target"`

	// The directory from which the files will be read. In Docker environments this is the directory
	// that we're mounting into the container at the Target location.
	Source string `json:"source"`

	// Whether the directory is being mounted as read-only. It is up to the environment to
	// handle this value correctly and ensure security expectations are met with its usage.
	ReadOnly bool `json:"read_only"`
}

type NetworkStats 

type NetworkStats struct {
	RxBytes uint64 `json:"rx_bytes"`
	TxBytes uint64 `json:"tx_bytes"`
}

type ProcessEnvironment 

type ProcessEnvironment interface {
	// Returns the name of the environment.
	Type() string

	// Returns the environment configuration to the caller.
	Config() *Configuration

	// Returns an event emitter instance that can be hooked into to listen for different
	// events that are fired by the environment. This should not allow someone to publish
	// events, only subscribe to them.
	Events() *events.Bus

	// Determines if the server instance exists. For example, in a docker environment
	// this should confirm that the container is created and in a bootable state. In
	// a basic CLI environment this can probably just return true right away.
	Exists() (bool, error)

	// IsRunning determines if the environment is currently active and running
	// a server process for this specific server instance.
	IsRunning(ctx context.Context) (bool, error)

	// Performs an update of server resource limits without actually stopping the server
	// process. This only executes if the environment supports it, otherwise it is
	// a no-op.
	InSituUpdate() error

	// Runs before the environment is started. If an error is returned starting will
	// not occur, otherwise proceeds as normal.
	OnBeforeStart(ctx context.Context) error

	// Starts a server instance. If the server instance is not in a state where it
	// can be started an error should be returned.
	Start(ctx context.Context) error

	// Stop stops a server instance. If the server is already stopped an error will
	// not be returned, this function will act as a no-op.
	Stop(ctx context.Context) error

	// WaitForStop waits for a server instance to stop gracefully. If the server is
	// still detected as running after "duration", an error will be returned, or the server
	// will be terminated depending on the value of the second argument. If the context
	// provided is canceled the underlying wait conditions will be stopped and the
	// entire loop will be ended (potentially without stopping or terminating).
	WaitForStop(ctx context.Context, duration time.Duration, terminate bool) error

	// Terminate stops a running server instance using the provided signal. This function
	// is a no-op if the server is already stopped.
	Terminate(ctx context.Context, signal string) error

	// Destroys the environment removing any containers that were created (in Docker
	// environments at least).
	Destroy() error

	// Returns the exit state of the process. The first result is the exit code, the second
	// determines if the process was killed by the system OOM killer.
	ExitState() (uint32, bool, error)

	// Creates the necessary environment for running the server process. For example,
	// in the Docker environment create will create a new container instance for the
	// server.
	Create() error

	// Attach attaches to the server console environment and allows piping the output
	// to a websocket or other internal tool to monitor output. Also allows you to later
	// send data into the environment's stdin.
	Attach(ctx context.Context) error

	// Sends the provided command to the running server instance.
	SendCommand(string) error

	// Reads the log file for the process from the end backwards until the provided
	// number of lines is met.
	Readlog(int) ([]string, error)

	// Returns the current state of the environment.
	State() string

	// Sets the current state of the environment. In general you should let the environment
	// handle this itself, but there are some scenarios where it is helpful for the server
	// to update the state externally (e.g. starting -> started).
	SetState(string)

	// Uptime returns the current environment uptime in milliseconds. This is
	// the time that has passed since it was last started.
	Uptime(ctx context.Context) (int64, error)

	// SetLogCallback sets the callback that the container's log output will be passed to.
	SetLogCallback(func([]byte))
}

Defines the basic interface that all environments need to implement so that a server can be properly controlled.

type Settings 

type Settings struct {
	Mounts      []Mount
	Allocations Allocations
	Limits      Limits
	Labels      map[string]string
}

type Stats 

type Stats struct {
	// The total amount of memory, in bytes, that this server instance is consuming. This is
	// calculated slightly differently than just using the raw Memory field that the stats
	// return from the container, so please check the code setting this value for how that
	// is calculated.
	Memory uint64 `json:"memory_bytes"`

	// The total amount of memory this container or resource can use. Inside Docker this is
	// going to be higher than you'd expect because we're automatically allocating overhead
	// abilities for the container, so it's not going to be a perfect match.
	MemoryLimit uint64 `json:"memory_limit_bytes"`

	// The absolute CPU usage is the amount of CPU used in relation to the entire system and
	// does not take into account any limits on the server process itself.
	CpuAbsolute float64 `json:"cpu_absolute"`

	// Current network transmit in & out for a container.
	Network NetworkStats `json:"network"`

	// The current uptime of the container, in milliseconds.
	Uptime int64 `json:"uptime"`
}

Stats defines the current resource usage for a given server instance.

type Variables 

type Variables map[string]interface{}

func (Variables) Get 

func (v Variables) Get(key string) string

Get is an ugly hacky function to handle environment variables that get passed through as not-a-string from the Panel. Ideally we'd just say only pass strings, but that is a fragile idea and if a string wasn't passed through you'd cause a crash or the server to become unavailable. For now try to handle the most likely values from the JSON and hope for the best.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.