misc

Documentation

Index

• Constants
• Variables
• func Decrypt(filePath string, key string) (content []byte, err error)
• func DecryptIfNecessary(key string, filePaths ...string) (decryptedContent [][]byte, isEncrypted []bool, err error)
• func EditKeyValue(filePath, key, value string) error
• func Encrypt(filePath string, key string) error
• func GetLatestStats() string
• func IsEncrypted(filePath string) (content []byte, encrypted bool, err error)
• func PipeConn(logger *lalog.Logger, autoClose bool, ioTimeout time.Duration, bufLen int, ...) error
• func ProbePort(maxDuration time.Duration, host string, port int) bool
• func RandomBytes(n int) []byte
• func ReadAllUpTo(r io.Reader, upTo int) (ret []byte, err error)
• func SplitIntoSlice(in string, maxElemLen, maxOverallLen int) (ret []string)
• func TriggerEmergencyKill()
• func TriggerEmergencyLockDown()
• func TriggerEmergencyStop()
• func TweakTCPConnection(conn *net.TCPConn, firstTransferTimeout time.Duration)
• type Periodic
  • func (p *Periodic) Start(ctx context.Context) error
  • func (p *Periodic) Stop()
  • func (p *Periodic) WaitForErr() error
• type ProgramStats
  • func GetLatestDisplayValues() ProgramStats
• type Stats
  • func NewStats(displayFormat StatsDisplayFormat) *Stats
  • func (s *Stats) Count() int
  • func (s *Stats) DisplayValue() StatsDisplayValue
  • func (s *Stats) Format() string
  • func (s *Stats) Trigger(qty float64)
• type StatsDisplayFormat
• type StatsDisplayValue

Constants

const (
	/*
		  EncryptionIVSizeBytes is the number of random bytes to use in an encrypted file as initialisation vector.
			According to AES implementation, the IV length must be equal to block size.
	*/
	EncryptionIVSizeBytes = aes.BlockSize
	// EncryptionFileHeader is a piece of plain text prepended to encrypted files as a clue to file readers.
	EncryptionFileHeader = "encrypted-by-laitos-software"
)

const (
	// EnvironmentDecryptionPassword is a name of environment variable, the value of which supplies decryption password
	// to laitos program when it is started using encrypted config file (and or data files).
	EnvironmentDecryptionPassword = "LAITOS_DECRYPTION_PASSWORD"
)

const StatsSumaryFormat = "%%.%df/%%.%df/%%.%df,%%.%df(%%d)"

Variables

var (
	// StartTime is the timestamp captured when this program started.
	StartupTime = time.Now()
	// ConfigFilePath is the absolute path to JSON configuration file that was used to launch this program.
	ConfigFilePath string

	// EnableAWSIntegration is a program-global flag that determines whether to integrate with various AWS services for the normal operation of laitos,
	// an example of such integration feature is to send incoming store&forward message to kinesis firehose.
	EnableAWSIntegration bool
	// EnablePrometheusIntegration is a program-global flag that determines whether to enable integration with prometheus by collecting and
	// serving metrics readings.
	EnablePrometheusIntegration bool
	// EmergencyLockDown is a flag checked by features and daemons, they should stop functioning or refuse to serve when the flag is true.
	EmergencyLockDown bool
	// ErrEmergencyLockDown is returned by some daemons to inform user that lock-down is in effect.
	ErrEmergencyLockDown = errors.New("LOCKED DOWN")

	// ProgramDataDecryptionPassword is the password string used to decrypt program data that was previously encrypted by
	// laitos' "datautil" encryption routine, protecting files such as configuration file and TLS certificate key.
	// The main function will collect this password from the channel of ProgramDataDecryptionPasswordInput.
	// The password will then be used for initialising daemons, starting them, etc.
	// In addition, when the supervisor recovers main program from an incidental crash, the supervisor will feed this password
	// to the standard input of the restarted main program.
	ProgramDataDecryptionPassword string

	// ProgramDataDecryptionPasswordInput is a synchronous channel that accepts a password string for decryption of program config and data.
	// It can be fed by a number of potential sources, such as standard input, AWS lambda handler, etc.
	// The main function will receive the supplied password and store it in ProgramDataDecryptionPassword string variable for further use.
	// Normally, only one source will send a password to this channel, but over here the channel is defined as a buffered to be on the defensive
	// side of programming mistakes.
	ProgramDataDecryptionPasswordInput = make(chan string, 10)
)

var (
	AutoUnlockStats     = NewStats(daemonStatsDisplayFormat)
	CommandStats        = NewStats(daemonStatsDisplayFormat)
	DNSDStatsTCP        = NewStats(daemonStatsDisplayFormat)
	DNSDStatsUDP        = NewStats(daemonStatsDisplayFormat)
	HTTPDStats          = NewStats(daemonStatsDisplayFormat)
	HTTPProxyStats      = NewStats(daemonStatsDisplayFormat)
	TCPOverDNSStats     = NewStats(daemonStatsDisplayFormat)
	PlainSocketStatsTCP = NewStats(daemonStatsDisplayFormat)
	PlainSocketStatsUDP = NewStats(daemonStatsDisplayFormat)
	SerialDevicesStats  = NewStats(daemonStatsDisplayFormat)
	SimpleIPStatsTCP    = NewStats(daemonStatsDisplayFormat)
	SimpleIPStatsUDP    = NewStats(daemonStatsDisplayFormat)
	SMTPDStats          = NewStats(daemonStatsDisplayFormat)
	SNMPStats           = NewStats(daemonStatsDisplayFormat)
	SOCKDStatsTCP       = NewStats(daemonStatsDisplayFormat)
	SOCKDStatsUDP       = NewStats(daemonStatsDisplayFormat)
	TelegramBotStats    = NewStats(daemonStatsDisplayFormat)

	// OutstandingMailBytes is the total size of all outstanding mails waiting to be delivered.
	OutstandingMailBytes int64
)

var (
	// ErrInputReaderNil is
	ErrInputReaderNil       = errors.New("input reader is nil")
	ErrInputCapacityInvalid = errors.New("input capacity is invalid")
)

var DefaultStatsDisplayFormat = StatsDisplayFormat{
	DivisionFactor: 1,
	NumDecimals:    9,
}

Functions

func Decrypt

func Decrypt(filePath string, key string) (content []byte, err error)

Decrypt decrypts the input file and returns its content. The entire operation is conducted in memory.

func DecryptIfNecessary

func DecryptIfNecessary(key string, filePaths ...string) (decryptedContent [][]byte, isEncrypted []bool, err error)

DecryptIfNecessary uses the input key to decrypt each of the possibly encrypted input files and returns their content. If an inpuit file is not encrypted, its content is simply read and returned.

func EditKeyValue

func EditKeyValue(filePath, key, value string) error

EditKeyValue modifies or inserts a key=value pair into the specified file.

func Encrypt

func Encrypt(filePath string, key string) error

Encrypt encrypts the input file in-place via AES. The entire operation is conducted in memory, hence it is most suited for important yet small files, such as configuration files and certificate keys.

func GetLatestStats

func GetLatestStats() string

GetLatestStats returns statistic information from all front-end daemons in a piece of multi-line, formatted text.

func IsEncrypted

func IsEncrypted(filePath string) (content []byte, encrypted bool, err error)

IsEncrypted returns true only if the input file is encrypted by laitos program.

func PipeConn

func PipeConn(logger *lalog.Logger, autoClose bool, ioTimeout time.Duration, bufLen int, src, dest net.Conn) error

PipeConn continuously reads data from the source net connection in blocks of no more than the specified buffer length, and writes them to the destination connection.

func ProbePort

func ProbePort(maxDuration time.Duration, host string, port int) bool

ProbePort makes at most 100 attempts at contacting the TCP server specified by its host and port, for up to specified maximum duration. If the TCP server accepts a connection, the connection will be immediately closed and the function will return true. If after the maximum duration the TCP server still has not accepted a connection, the function will return false and print a warning log message.

func RandomBytes

func RandomBytes(n int) []byte

RandomBytes returns a slice of bytes with crypto-grade random content.

func ReadAllUpTo

func ReadAllUpTo(r io.Reader, upTo int) (ret []byte, err error)

ReadAllUpTo reads data from input reader until the limited capacity is reached or reader is exhausted (EOF).

func SplitIntoSlice

func SplitIntoSlice(in string, maxElemLen, maxOverallLen int) (ret []string)

SplitIntoSlice truncates the input string into maxOverallLen and then splits it into a slice of strings up to maxElemLen each,

func TriggerEmergencyKill

func TriggerEmergencyKill()

TriggerEmergencyKill wipes as much data as possible from all storage attached to this computer, and then crash the program. This is a very dangerous operation!

func TriggerEmergencyLockDown

func TriggerEmergencyLockDown()

TriggerEmergencyLockDown turns on EmergencyLockDown flag, so that features and daemons will immediately (or very soon) stop functioning or refuse to serve more requests. The program process will keep running (i.e. not going to crash). Once the function is called, there is no way to cancel lock-down status other than restarting the program.

func TriggerEmergencyStop

func TriggerEmergencyStop()

TriggerEmergencyStop crashes the program with an abort signal in 10 seconds.

func TweakTCPConnection

func TweakTCPConnection(conn *net.TCPConn, firstTransferTimeout time.Duration)

TweakTCPConnection sets various TCP options on the connection to improve its responsiveness.

Types

type Periodic

type Periodic struct {
	// LogActorName is a string used in log messages. These messages are rare.
	LogActorName string
	// Interval between each invocation.
	Interval time.Duration
	// MaxInt determines the upper bound range of the integer value given
	// to the invoked function.
	// If the function does not use this integer, then set this field to 1.
	MaxInt int
	// Func is the function to be invoked at regular interval. With each
	// invocation, the function will receive:
	// - A context, which may be cancelled.
	// - Current round number starting with 0. A round is completed after the
	//   function has been invoked with all of [0,MaxInt).
	// - An integer in the range of [0,MaxInt).
	// If the function returns a non-nil error, then the periodic invocation
	// will stop entirely. The function's error can be retrieved by calling
	// WaitForErr function.
	Func func(context.Context, int, int) error
	// RandomInt determines whether each invocation of the function will receive
	// a randomly chosen integer within the range of [0,MaxInt).
	// Otherwise, each consecutive invocation will receive the next integer in
	// sequence, which wraps around after reaching MaxInt-1.
	// Caller of Start function should seed the default PRNG.
	RandomOrder bool
	// StableInterval lines up the start of each invocation of the function to
	// the interval.
	// Otherwise, the interval between consecutive invocations of the function
	// will always be the fixed duration.
	StableInterval bool
	// RapidFirstRound causes the first round of invocations (that is Func
	// invoked with all of [0,MaxInt)) to be invoked in rapid succession, without
	// having to wait for the interval in between.
	RapidFirstRound bool
	// contains filtered or unexported fields
}

Periodic invokes a function continuously with a regular interval in between.

func (*Periodic) Start

func (p *Periodic) Start(ctx context.Context) error

Start invoking the periodic function continuously at regular interval. The function does not block caller. Optionally, use WaitForErr to block-wait for the periodic function to return an error, in which case the periodic invocations will stop entirely.

func (*Periodic) Stop

func (p *Periodic) Stop()

Stop the periodic invocation of the function. The result of the final invocation can be discovered from the return value of Wait function.

func (*Periodic) WaitForErr

func (p *Periodic) WaitForErr() error

Wait for the periodically invoked function or its context to return an error, and then return the error to the caller. The function blocks caller.

type ProgramStats

type ProgramStats struct {
	AutoUnlock         StatsDisplayValue
	DNSOverTCP         StatsDisplayValue
	DNSOverUDP         StatsDisplayValue
	HTTP               StatsDisplayValue
	HTTPProxy          StatsDisplayValue
	TCPOverDNS         StatsDisplayValue
	PlainSocketTCP     StatsDisplayValue
	PlainSocketUDP     StatsDisplayValue
	SimpleIPServiceTCP StatsDisplayValue
	SimpleIPServiceUDP StatsDisplayValue
	SMTP               StatsDisplayValue
	SockdTCP           StatsDisplayValue
	SockdUDP           StatsDisplayValue
	TelegramBot        StatsDisplayValue

	OutgoingMailBytes int64
}

ProgramStats has the comprehensive collection of program-wide stats counters in a human-readable format.

func GetLatestDisplayValues

func GetLatestDisplayValues() ProgramStats

GetProgramStats returns the latest program-wide stats counters in a human-readable format.

type Stats

type Stats struct {
	DisplayFormat StatsDisplayFormat
	// contains filtered or unexported fields
}

Stats collect counter and aggregated numeric data from a stream of triggers.

func NewStats

func NewStats(displayFormat StatsDisplayFormat) *Stats

NewStats returns an initialised stats structure.

func (*Stats) Count

func (s *Stats) Count() int

Count returns the verbatim counter value, that is the number of times some action has triggered.

func (*Stats) DisplayValue

func (s *Stats) DisplayValue() StatsDisplayValue

DisplayValue returns the human-readable display values of the raw stats counter instance.

func (*Stats) Format

func (s *Stats) Format() string

Format returns all stats formatted into a single line of string after the numbers (excluding counter) are divided by the factor.

func (*Stats) Trigger

func (s *Stats) Trigger(qty float64)

Trigger increases counter by one and places the input quantity into numeric statistics.

type StatsDisplayFormat

type StatsDisplayFormat struct {
	DivisionFactor float64
	NumDecimals    int
}

StatsDisplayFormat determines the human-readable scale and formatting of an instance of stats counter.

type StatsDisplayValue

type StatsDisplayValue struct {
	Lowest  float64
	Average float64
	Highest float64
	Total   float64
	Count   uint64
	Summary string
}

StatsDisplayValue is the human-readable transformation of an instance of stats counter.