common

Documentation

Index

• Constants
• func Compress(data []byte) []byte
• func Contains(list []string, target string) bool
• func ContainsAny(list, targets []string) bool
• func ContainsInt(list []int, target int) bool
• func ContainsWildcard(patterns []string, target string) bool
• func ContextError(err error) error
• func Decompress(data []byte) ([]byte, error)
• func FlipCoin() bool
• func FlipWeightedCoin(weight float64) bool
• func FormatByteCount(bytes uint64) string
• func GenerateAuthenticatedDataPackageKeys() (string, string, error)
• func GenerateHostName() string
• func GetCurrentTimestamp() string
• func GetInterfaceIPAddresses(interfaceName string) (net.IP, net.IP, error)
• func GetParentContext() string
• func GetStringSlice(value interface{}) ([]string, bool)
• func IPAddressFromAddr(addr net.Addr) string
• func Jitter(n int64, factor float64) int64
• func JitterDuration(d time.Duration, factor float64) time.Duration
• func MakeSecureRandomBytes(length int) ([]byte, error)
• func MakeSecureRandomInt(max int) (int, error)
• func MakeSecureRandomInt64(max int64) (int64, error)
• func MakeSecureRandomPadding(minLength, maxLength int) ([]byte, error)
• func MakeSecureRandomPeriod(min, max time.Duration) (time.Duration, error)
• func MakeSecureRandomPerm(max int) ([]int, error)
• func MakeSecureRandomRange(min, max int) (int, error)
• func MakeSecureRandomStringBase64(byteLength int) (string, error)
• func MakeSecureRandomStringHex(byteLength int) (string, error)
• func NewAuthenticatedDataPackageReader(dataPackage io.ReadSeeker, signingPublicKey string) (io.Reader, error)
• func ReadAuthenticatedDataPackage(dataPackage []byte, isCompressed bool, signingPublicKey string) (string, error)
• func RegisterHostNameGenerator(generator func() string)
• func TerminateHTTPConnection(responseWriter http.ResponseWriter, request *http.Request)
• func TruncateTimestampToHour(timestamp string) string
• func WriteAuthenticatedDataPackage(data string, signingPublicKey, signingPrivateKey string) ([]byte, error)
• type APIParameterLogFieldFormatter
• type APIParameterValidator
• type APIParameters
• type ActivityMonitoredConn
  • func NewActivityMonitoredConn(conn net.Conn, inactivityTimeout time.Duration, activeOnWrite bool, ...) (*ActivityMonitoredConn, error)
  • func (conn *ActivityMonitoredConn) GetActiveDuration() time.Duration
  • func (conn *ActivityMonitoredConn) GetLastActivityMonotime() monotime.Time
  • func (conn *ActivityMonitoredConn) GetStartTime() time.Time
  • func (conn *ActivityMonitoredConn) IsClosed() bool
  • func (conn *ActivityMonitoredConn) Read(buffer []byte) (int, error)
  • func (conn *ActivityMonitoredConn) Write(buffer []byte) (int, error)
• type ActivityUpdater
• type AuthenticatedDataPackage
• type BuildInfo
  • func GetBuildInfo() *BuildInfo
  • func (bi *BuildInfo) ToMap() *map[string]interface{}
• type Closer
• type Conns
  • func (conns *Conns) Add(conn net.Conn) bool
  • func (conns *Conns) CloseAll()
  • func (conns *Conns) Remove(conn net.Conn)
  • func (conns *Conns) Reset()
• type GeoIPData
• type LRUConns
  • func NewLRUConns() *LRUConns
  • func (conns *LRUConns) Add(conn net.Conn) *LRUConnsEntry
  • func (conns *LRUConns) CloseOldest()
• type LRUConnsEntry
  • func (entry *LRUConnsEntry) Remove()
  • func (entry *LRUConnsEntry) Touch()
• type LogContext
• type LogFields
• type Logger
• type RateLimits
• type ReloadableFile
  • func NewReloadableFile(fileName string, reloadAction func([]byte) error) ReloadableFile
  • func (reloadable *ReloadableFile) LogDescription() string
  • func (reloadable *ReloadableFile) Reload() (bool, error)
  • func (reloadable *ReloadableFile) WillReload() bool
• type Reloader
• type SubnetLookup
  • func NewSubnetLookup(CIDRs []string) (SubnetLookup, error)
  • func NewSubnetLookupFromRoutes(routesData []byte) (SubnetLookup, error)
  • func (lookup SubnetLookup) ContainsIPAddress(addr net.IP) bool
  • func (lookup SubnetLookup) Len() int
  • func (lookup SubnetLookup) Less(i, j int) bool
  • func (lookup SubnetLookup) Swap(i, j int)
• type ThrottledConn
  • func NewThrottledConn(conn net.Conn, limits RateLimits) *ThrottledConn
  • func (conn *ThrottledConn) Read(buffer []byte) (int, error)
  • func (conn *ThrottledConn) SetLimits(limits RateLimits)
  • func (conn *ThrottledConn) Write(buffer []byte) (int, error)

Constants

const RFC3339Milli = "2006-01-02T15:04:05.000Z07:00"

Functions

func Compress

func Compress(data []byte) []byte

Compress returns zlib compressed data

func Contains

func Contains(list []string, target string) bool

Contains is a helper function that returns true if the target string is in the list.

func ContainsAny

func ContainsAny(list, targets []string) bool

ContainsAny returns true if any string in targets is present in the list.

func ContainsInt

func ContainsInt(list []int, target int) bool

ContainsInt returns true if the target int is in the list.

func ContainsWildcard

func ContainsWildcard(patterns []string, target string) bool

ContainsWildcard returns true if target matches any of the patterns. Patterns may contain the '*' wildcard.

func ContextError

func ContextError(err error) error

ContextError prefixes an error message with the current function name and source file line number.

func Decompress

func Decompress(data []byte) ([]byte, error)

Decompress returns zlib decompressed data

func FlipCoin

func FlipCoin() bool

FlipCoin is a helper function that randomly returns true or false.

If the underlying random number generator fails, FlipCoin still returns false.

func FlipWeightedCoin

func FlipWeightedCoin(weight float64) bool

FlipWeightedCoin returns the result of a weighted random coin flip. If the weight is 0.5, the outcome is equally likely to be true or false. If the weight is 1.0, the outcome is always true, and if the weight is 0.0, the outcome is always false.

Input weights > 1.0 are treated as 1.0.

If the underlying random number generator fails, FlipWeightedCoin still returns a result.

func FormatByteCount

func FormatByteCount(bytes uint64) string

FormatByteCount returns a string representation of the specified byte count in conventional, human-readable format.

func GenerateAuthenticatedDataPackageKeys

func GenerateAuthenticatedDataPackageKeys() (string, string, error)

GenerateAuthenticatedDataPackageKeys generates a key pair be used to sign and verify AuthenticatedDataPackages.

func GenerateHostName

func GenerateHostName() string

func GetCurrentTimestamp

func GetCurrentTimestamp() string

GetCurrentTimestamp returns the current time in UTC as an RFC 3339 formatted string.

func GetInterfaceIPAddresses

func GetInterfaceIPAddresses(interfaceName string) (net.IP, net.IP, error)

GetInterfaceIPAddresses takes an interface name, such as "eth0", and returns the first IPv4 and IPv6 addresses associated with it. Either of the IPv4 or IPv6 address may be nil. If neither type of address is found, an error is returned.

func GetParentContext

func GetParentContext() string

GetParentContext returns the parent function name and source file line number.

func GetStringSlice

func GetStringSlice(value interface{}) ([]string, bool)

GetStringSlice converts an interface{} which is of type []interace{}, and with the type of each element a string, to []string.

func IPAddressFromAddr

func IPAddressFromAddr(addr net.Addr) string

IPAddressFromAddr is a helper which extracts an IP address from a net.Addr or returns "" if there is no IP address.

func Jitter

func Jitter(n int64, factor float64) int64

Jitter returns n +/- the given factor. For example, for n = 100 and factor = 0.1, the return value will be in the range [90, 110].

func JitterDuration

func JitterDuration(
	d time.Duration, factor float64) time.Duration

JitterDuration is a helper function that wraps Jitter.

func MakeSecureRandomBytes

func MakeSecureRandomBytes(length int) ([]byte, error)

MakeSecureRandomBytes is a helper function that wraps crypto/rand.Read.

func MakeSecureRandomInt

func MakeSecureRandomInt(max int) (int, error)

MakeSecureRandomInt is a helper function that wraps MakeSecureRandomInt64.

func MakeSecureRandomInt64

func MakeSecureRandomInt64(max int64) (int64, error)

MakeSecureRandomInt64 is a helper function that wraps crypto/rand.Int, which returns a uniform random value in [0, max).

func MakeSecureRandomPadding

func MakeSecureRandomPadding(minLength, maxLength int) ([]byte, error)

MakeSecureRandomPadding selects a random padding length in the indicated range and returns a random byte array of the selected length. If maxLength <= minLength, the padding is minLength.

func MakeSecureRandomPeriod

func MakeSecureRandomPeriod(min, max time.Duration) (time.Duration, error)

MakeSecureRandomPeriod returns a random duration, within a given range. If max <= min, the duration is min.

func MakeSecureRandomPerm

func MakeSecureRandomPerm(max int) ([]int, error)

MakeSecureRandomPerm returns a random permutation of [0,max).

func MakeSecureRandomRange

func MakeSecureRandomRange(min, max int) (int, error)

MakeSecureRandomRange selects a random int in [min, max]. If max < min, min is returned.

func MakeSecureRandomStringBase64

func MakeSecureRandomStringBase64(byteLength int) (string, error)

MakeSecureRandomStringBase64 returns a base64 encoded random string. byteLength specifies the pre-encoded data length.

func MakeSecureRandomStringHex

func MakeSecureRandomStringHex(byteLength int) (string, error)

MakeSecureRandomStringHex returns a hex encoded random string. byteLength specifies the pre-encoded data length.

func NewAuthenticatedDataPackageReader

func NewAuthenticatedDataPackageReader(
	dataPackage io.ReadSeeker, signingPublicKey string) (io.Reader, error)

NewAuthenticatedDataPackageReader extracts and verifies authenticated data from an AuthenticatedDataPackage stored in the specified file. The package must have been signed with the given key. NewAuthenticatedDataPackageReader does not load the entire package nor the entire data into memory. It streams the package while verifying, and returns an io.Reader that the caller may use to stream the authenticated data payload.

func ReadAuthenticatedDataPackage

func ReadAuthenticatedDataPackage(
	dataPackage []byte, isCompressed bool, signingPublicKey string) (string, error)

ReadAuthenticatedDataPackage extracts and verifies authenticated data from an AuthenticatedDataPackage. The package must have been signed with the given key.

Set isCompressed to false to read packages that are not compressed.

func RegisterHostNameGenerator

func RegisterHostNameGenerator(generator func() string)

func TerminateHTTPConnection

func TerminateHTTPConnection(
	responseWriter http.ResponseWriter, request *http.Request)

TerminateHTTPConnection sends a 404 response to a client and also closes the persistent connection.

func TruncateTimestampToHour

func TruncateTimestampToHour(timestamp string) string

TruncateTimestampToHour truncates an RFC 3339 formatted string to hour granularity. If the input is not a valid format, the result is "".

func WriteAuthenticatedDataPackage

func WriteAuthenticatedDataPackage(
	data string, signingPublicKey, signingPrivateKey string) ([]byte, error)

WriteAuthenticatedDataPackage creates an AuthenticatedDataPackage containing the specified data and signed by the given key. The output conforms with the legacy format here: https://bitbucket.org/psiphon/psiphon-circumvention-system/src/c25d080f6827b141fe637050ce0d5bd0ae2e9db5/Automation/psi_ops_crypto_tools.py

Types

type APIParameterLogFieldFormatter

type APIParameterLogFieldFormatter func(GeoIPData, APIParameters) LogFields

APIParameterLogFieldFormatter is a function that returns formatted LogFields containing the given GeoIPData and APIParameters.

type APIParameterValidator

type APIParameterValidator func(APIParameters) error

APIParameterValidator is a function that validates API parameters for a particular request or context.

type APIParameters

type APIParameters map[string]interface{}

APIParameters is a set of API parameter values, typically received from a Psiphon client and used/logged by the Psiphon server. The values are of varying types: strings, ints, arrays, structs, etc.

type ActivityMonitoredConn

type ActivityMonitoredConn struct {
	net.Conn
	// contains filtered or unexported fields
}

ActivityMonitoredConn wraps a net.Conn, adding logic to deal with events triggered by I/O activity.

When an inactivity timeout is specified, the network I/O will timeout after the specified period of read inactivity. Optionally, for the purpose of inactivity only, ActivityMonitoredConn will also consider the connection active when data is written to it.

When a LRUConnsEntry is specified, then the LRU entry is promoted on either a successful read or write.

When an ActivityUpdater is set, then its UpdateActivity method is called on each read and write with the number of bytes transferred. The durationNanoseconds, which is the time since the last read, is reported only on reads.

func NewActivityMonitoredConn

func NewActivityMonitoredConn(
	conn net.Conn,
	inactivityTimeout time.Duration,
	activeOnWrite bool,
	activityUpdater ActivityUpdater,
	lruEntry *LRUConnsEntry) (*ActivityMonitoredConn, error)

NewActivityMonitoredConn creates a new ActivityMonitoredConn.

func (*ActivityMonitoredConn) GetActiveDuration

func (conn *ActivityMonitoredConn) GetActiveDuration() time.Duration

GetActiveDuration returns the time elapsed between the initialization of the ActivityMonitoredConn and the last Read. Only reads are used for this calculation since writes may succeed locally due to buffering.

func (*ActivityMonitoredConn) GetLastActivityMonotime

func (conn *ActivityMonitoredConn) GetLastActivityMonotime() monotime.Time

GetLastActivityMonotime returns the arbitrary monotonic time of the last Read.

func (*ActivityMonitoredConn) GetStartTime

func (conn *ActivityMonitoredConn) GetStartTime() time.Time

GetStartTime gets the time when the ActivityMonitoredConn was initialized. Reported time is UTC.

func (*ActivityMonitoredConn) IsClosed

func (conn *ActivityMonitoredConn) IsClosed() bool

IsClosed implements the Closer iterface. The return value indicates whether the underlying conn has been closed.

func (*ActivityMonitoredConn) Read

func (conn *ActivityMonitoredConn) Read(buffer []byte) (int, error)

func (*ActivityMonitoredConn) Write

func (conn *ActivityMonitoredConn) Write(buffer []byte) (int, error)

type ActivityUpdater

type ActivityUpdater interface {
	UpdateProgress(bytesRead, bytesWritten int64, durationNanoseconds int64)
}

ActivityUpdater defines an interface for receiving updates for ActivityMonitoredConn activity. Values passed to UpdateProgress are bytes transferred and conn duration since the previous UpdateProgress.

type AuthenticatedDataPackage

type AuthenticatedDataPackage struct {
	Data                   string `json:"data"`
	SigningPublicKeyDigest []byte `json:"signingPublicKeyDigest"`
	Signature              []byte `json:"signature"`
}

AuthenticatedDataPackage is a JSON record containing some Psiphon data payload, such as list of Psiphon server entries. As it may be downloaded from various sources, it is digitally signed so that the data may be authenticated.

type BuildInfo

type BuildInfo struct {
	BuildDate       string          `json:"buildDate"`
	BuildRepo       string          `json:"buildRepo"`
	BuildRev        string          `json:"buildRev"`
	GoVersion       string          `json:"goVersion"`
	GomobileVersion string          `json:"gomobileVersion,omitempty"`
	Dependencies    json.RawMessage `json:"dependencies"`
}

BuildInfo captures relevant build information here for use in clients or servers

func GetBuildInfo

func GetBuildInfo() *BuildInfo

GetBuildInfo returns an instance of the BuildInfo struct

func (*BuildInfo) ToMap

func (bi *BuildInfo) ToMap() *map[string]interface{}

ToMap converts 'BuildInfo' struct to 'map[string]interface{}'

type Closer

type Closer interface {
	IsClosed() bool
}

Closer defines the interface to a type, typically a net.Conn, that can be closed.

type Conns

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

Conns is a synchronized list of Conns that is used to coordinate interrupting a set of goroutines establishing connections, or close a set of open connections, etc. Once the list is closed, no more items may be added to the list (unless it is reset).

func (*Conns) Add

func (conns *Conns) Add(conn net.Conn) bool

func (*Conns) CloseAll

func (conns *Conns) CloseAll()

func (*Conns) Remove

func (conns *Conns) Remove(conn net.Conn)

func (*Conns) Reset

func (conns *Conns) Reset()

type GeoIPData

type GeoIPData struct {
	Country        string
	City           string
	ISP            string
	DiscoveryValue int
}

GeoIPData is type-compatible with psiphon/server.GeoIPData.

type LRUConns

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

LRUConns is a concurrency-safe list of net.Conns ordered by recent activity. Its purpose is to facilitate closing the oldest connection in a set of connections.

New connections added are referenced by a LRUConnsEntry, which is used to Touch() active connections, which promotes them to the front of the order and to Remove() connections that are no longer LRU candidates.

CloseOldest() will remove the oldest connection from the list and call net.Conn.Close() on the connection.

After an entry has been removed, LRUConnsEntry Touch() and Remove() will have no effect.

func NewLRUConns

func NewLRUConns() *LRUConns

NewLRUConns initializes a new LRUConns.

func (*LRUConns) Add

func (conns *LRUConns) Add(conn net.Conn) *LRUConnsEntry

Add inserts a net.Conn as the freshest connection in a LRUConns and returns an LRUConnsEntry to be used to freshen the connection or remove the connection from the LRU list.

func (*LRUConns) CloseOldest

func (conns *LRUConns) CloseOldest()

CloseOldest closes the oldest connection in a LRUConns. It calls net.Conn.Close() on the connection.

type LRUConnsEntry

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

LRUConnsEntry is an entry in a LRUConns list.

func (*LRUConnsEntry) Remove

func (entry *LRUConnsEntry) Remove()

Remove deletes the connection referenced by the LRUConnsEntry from the associated LRUConns. Has no effect if the entry was not initialized or previously removed.

func (*LRUConnsEntry) Touch

func (entry *LRUConnsEntry) Touch()

Touch promotes the connection referenced by the LRUConnsEntry to the front of the associated LRUConns. Has no effect if the entry was not initialized or previously removed.

type LogContext

type LogContext interface {
	Debug(args ...interface{})
	Info(args ...interface{})
	Warning(args ...interface{})
	Error(args ...interface{})
}

LogContext is interface-compatible with the return values from psiphon/server.ContextLogger.WithContext/WithContextFields.

type LogFields

type LogFields map[string]interface{}

LogFields is type-compatible with psiphon/server.LogFields and logrus.LogFields.

type Logger

type Logger interface {
	WithContext() LogContext
	WithContextFields(fields LogFields) LogContext
	LogMetric(metric string, fields LogFields)
}

Logger exposes a logging interface that's compatible with psiphon/server.ContextLogger. This interface allows packages to implement logging that will integrate with psiphon/server without importing that package. Other implementations of Logger may also be provided.

type RateLimits

type RateLimits struct {

	// ReadUnthrottledBytes specifies the number of bytes to
	// read, approximately, before starting rate limiting.
	ReadUnthrottledBytes int64

	// ReadBytesPerSecond specifies a rate limit for read
	// data transfer. The default, 0, is no limit.
	ReadBytesPerSecond int64

	// WriteUnthrottledBytes specifies the number of bytes to
	// write, approximately, before starting rate limiting.
	WriteUnthrottledBytes int64

	// WriteBytesPerSecond specifies a rate limit for write
	// data transfer. The default, 0, is no limit.
	WriteBytesPerSecond int64

	// CloseAfterExhausted indicates that the underlying
	// net.Conn should be closed once either the read or
	// write unthrottled bytes have been exhausted. In this
	// case, throttling is never applied.
	CloseAfterExhausted bool
}

RateLimits specify the rate limits for a ThrottledConn.

type ReloadableFile

type ReloadableFile struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ReloadableFile is a file-backed Reloader. This type is intended to be embedded in other types that add the actual reloadable data structures.

ReloadableFile has a multi-reader mutex for synchronization. Its Reload() function will obtain a write lock before reloading the data structures. The actual reloading action is to be provided via the reloadAction callback, which receives the content of reloaded files and must process the new data (for example, unmarshall the contents into data structures). All read access to the data structures should be guarded by RLocks on the ReloadableFile mutex.

reloadAction must ensure that data structures revert to their previous state when a reload fails.

func NewReloadableFile

func NewReloadableFile(
	fileName string,
	reloadAction func([]byte) error) ReloadableFile

NewReloadableFile initializes a new ReloadableFile

func (*ReloadableFile) LogDescription

func (reloadable *ReloadableFile) LogDescription() string

func (*ReloadableFile) Reload

func (reloadable *ReloadableFile) Reload() (bool, error)

Reload checks if the underlying file has changed and, when changed, invokes the reloadAction callback which should reload the in-memory data structures.

In some case (e.g., traffic rules and OSL), there are penalties associated with proceeding with reload, so care is taken to not invoke the reload action unless the contents have changed.

The file content is loaded and a checksum is taken to determine whether it has changed. Neither file size (may not change when content changes) nor modified date (may change when identical file is repaved) is a sufficient indicator.

All data structure readers should be blocked by the ReloadableFile mutex.

Reload must not be called from multiple concurrent goroutines.

func (*ReloadableFile) WillReload

func (reloadable *ReloadableFile) WillReload() bool

WillReload indicates whether the ReloadableFile is capable of reloading.

type Reloader

type Reloader interface {

	// Reload reloads the data object. Reload returns a flag indicating if the
	// reloadable target has changed and reloaded or remains unchanged. By
	// convention, when reloading fails the Reloader should revert to its previous
	// in-memory state.
	Reload() (bool, error)

	// WillReload indicates if the data object is capable of reloading.
	WillReload() bool

	// LogDescription returns a description to be used for logging
	// events related to the Reloader.
	LogDescription() string
}

Reloader represents a read-only, in-memory reloadable data object. For example, a JSON data file that is loaded into memory and accessed for read-only lookups; and from time to time may be reloaded from the same file, updating the memory copy.

type SubnetLookup

type SubnetLookup []net.IPNet

SubnetLookup provides an efficient lookup for individual IPv4 addresses within a list of subnets.

func NewSubnetLookup

func NewSubnetLookup(CIDRs []string) (SubnetLookup, error)

NewSubnetLookup creates a SubnetLookup from a list of subnet CIDRs.

func NewSubnetLookupFromRoutes

func NewSubnetLookupFromRoutes(routesData []byte) (SubnetLookup, error)

NewSubnetLookupFromRoutes creates a SubnetLookup from text routes data. The input format is expected to be text lines where each line is, e.g., "1.2.3.0\t255.255.255.0\n"

func (SubnetLookup) ContainsIPAddress

func (lookup SubnetLookup) ContainsIPAddress(addr net.IP) bool

ContainsIPAddress performs a binary search on the sorted subnet list to find a network containing the candidate IP address.

func (SubnetLookup) Len

func (lookup SubnetLookup) Len() int

Len implements Sort.Interface

func (SubnetLookup) Less

func (lookup SubnetLookup) Less(i, j int) bool

Less implements Sort.Interface

func (SubnetLookup) Swap

func (lookup SubnetLookup) Swap(i, j int)

Swap implements Sort.Interface

type ThrottledConn

type ThrottledConn struct {
	net.Conn
	// contains filtered or unexported fields
}

ThrottledConn wraps a net.Conn with read and write rate limiters. Rates are specified as bytes per second. Optional unlimited byte counts allow for a number of bytes to read or write before applying rate limiting. Specify limit values of 0 to set no rate limit (unlimited counts are ignored in this case). The underlying rate limiter uses the token bucket algorithm to calculate delay times for read and write operations.

func NewThrottledConn

func NewThrottledConn(conn net.Conn, limits RateLimits) *ThrottledConn

NewThrottledConn initializes a new ThrottledConn.

func (*ThrottledConn) Read

func (conn *ThrottledConn) Read(buffer []byte) (int, error)

func (*ThrottledConn) SetLimits

func (conn *ThrottledConn) SetLimits(limits RateLimits)

SetLimits modifies the rate limits of an existing ThrottledConn. It is safe to call SetLimits while other goroutines are calling Read/Write. This function will not block, and the new rate limits will be applied within Read/Write, but not necessarily until some further I/O at previous rates.

func (*ThrottledConn) Write

func (conn *ThrottledConn) Write(buffer []byte) (int, error)