util

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2025 License: Apache-2.0 Imports: 39 Imported by: 25

Documentation

Index

Constants

View Source 
const BUFFER_SIZE = 65536

Variables

View Source 
var (
	MaxResultsSliceSize     = 1_000 // 0 for limitless
	ResultsStreamBufferSize = 100
)

Functions

func BytesToString 

func BytesToString(bytes []byte) string

This conversion *does not* copy data. Note that converting via "(string)([]byte)" *does* copy data. Also note that you *should not* change the byte slice after conversion, because Go strings are treated as immutable. This would cause a segmentation violation panic.

func ContextualRead 

func ContextualRead(context contextpkg.Context, reader io.Reader, p []byte) (int, error)

func CopySSH 

func CopySSH(host string, port int, username string, key string, reader io.Reader, targetPath string, permissions *int64) error

func CreateRSAX509Certificate 

func CreateRSAX509Certificate(organization string, host string, rsaBits int, duration time.Duration) (*rsa.PrivateKey, *x509.Certificate, error)

Generates a random RSA key pair and uses it to sign a X.509 certificate with a random serial number.

If host is empy it will default to "localhost". If rsaBits is 0 it will default to 2048. If duration is 0 it will default to one year.

func CreateSelfSignedTLSConfig 

func CreateSelfSignedTLSConfig(organization string, host string, rsaBits int, duration time.Duration) (*tls.Config, error)

Creates a TLS config with a single X.509 certificate signed with a new RSA key pair.

If rsaBits is 0 it will default to 2048. If duration is 0 it will default to one year.

func CreateTLSConfig 

func CreateTLSConfig(certificate []byte, key []byte) (*tls.Config, error)

func DoesFileExist 

func DoesFileExist(path string) (bool, error)

func DumpIPAddress 

func DumpIPAddress(address any)

func ExecSSH 

func ExecSSH(host string, port int, username string, key string, stdin io.Reader, command ...string) (string, error)

func Exit 

func Exit(code int)

func ExitOnSignal 

func ExitOnSignal(signal os.Signal, exitCode int)

func ExitOnSignals 

func ExitOnSignals()

func Fail 

func Fail(message string)

func FailOnError 

func FailOnError(err error)

func Failf 

func Failf(f string, args ...any)

func FixTarballEntryPath 

func FixTarballEntryPath(path string) string

func FromBase64 

func FromBase64(b64 string) ([]byte, error)

func GatherResults 

func GatherResults[E any](results Results[E]) ([]E, error)

func GetFileHash 

func GetFileHash(path string) (string, error)

func GetGoBin 

func GetGoBin() (string, error)

func GetGoPath 

func GetGoPath() (string, error)

func IPAddressPortWithoutZone 

func IPAddressPortWithoutZone(address string) string

func InitializeCPUProfiling 

func InitializeCPUProfiling(path string)

func InitializeColorization 

func InitializeColorization(colorize string)

Attempts to enable colorization for os.Stdout and os.Stderr according to the colorize argument. If cleanup is required, will set register it with OnExit. Errors will Fail.

The colorize argument can be:

  • "true", "TRUE", "True", "t", "T", "1": Attempts to enable colorization if os.Stdout and os.Stdout support it. If it succeeds will set [ColorizeStdout], [StdoutStylist], [ColorizeStderr], and [StderrStylist] accordingly.
  • "false", "FALSE", "False", "f", "F", "0": Does nothing.
  • "force": Sets [ColorizeStdout], [StdoutStylist], [ColorizeStderr], and [StderrStylist] as if coloriziation were enabled.

Other colorize values will Fail.

See terminal.InitializeColorization.

func IsFileExecutable 

func IsFileExecutable(mode fs.FileMode) bool

func IsFileHidden 

func IsFileHidden(path string) bool

func IsFloat 

func IsFloat(value any) bool

Returns true if value is a float64 or float32.

func IsIPv6 

func IsIPv6(address string) bool

Returns true if the IP address string representation is IPv6.

Note that this function does no validation and assumes the argument is already a valid IPv6 or IPv4 address.

func IsInteger 

func IsInteger(value any) bool

Returns true if value is an int64, int32, int16, int8, int, uint64, uint32, uint16, uint8, or uint.

func IsNumber 

func IsNumber(value any) bool

Returns true if value is an int64, int32, int16, int8, int, uint64, uint32, uint16, uint8, uint, float64, or float32.

func IsUDPAddrEqual 

func IsUDPAddrEqual(a *net.UDPAddr, b *net.UDPAddr) bool

Returns true if the two UDP addresses are equal.

func IterateResults 

func IterateResults[E any](results Results[E], iterate IterateResultsFunc[E]) error

func JoinIPAddressPort 

func JoinIPAddressPort(address string, port int) string

Returns "[address]:port" for IPv6 and "address:port" for IPv4.

Meant to satisfy the unfortunate requirement of many APIs to provide an address (or hostname) and port with a single string argument.

func JoinIPAddressZone 

func JoinIPAddressZone(address string, zone string) string

If the zone is not empty returns "address%zone". It is expected that the argument does not already have a zone.

For IPv6 address string representations only, see: https://en.wikipedia.org/wiki/IPv6_address#Scoped_literal_IPv6_addresses_(with_zone_index)

func JoinQuote 

func JoinQuote(strings []string, separator string) string

func JoinQuoteL 

func JoinQuoteL(strings []string, separator string, lastSeparator string, coupleSeparator string) string

func NewContextualReadCloser 

func NewContextualReadCloser(context contextpkg.Context, reader io.ReadCloser) io.ReadCloser

Creates a io.ReadCloser

func NewContextualReader 

func NewContextualReader(context contextpkg.Context, reader io.Reader) io.Reader

func NewMockLocker 

func NewMockLocker() sync.Locker

func NewX509Certificate 

func NewX509Certificate(organization string, host string, duration time.Duration, rsa bool, ca bool) (*x509.Certificate, error)

Initializes a X.509 certificate with a random serial number.

If duration is 0 it will default to one year.

func ParseX509CertificatePool 

func ParseX509CertificatePool(bytes []byte) (*x509.CertPool, error)

func ParseX509Certificates 

func ParseX509Certificates(bytes []byte) ([]*x509.Certificate, error)

func RandomSerialNumber 

func RandomSerialNumber() (*big.Int, error)

func ReaderSize 

func ReaderSize(reader io.Reader) (int64, error)

func ResetAdHocLocks 

func ResetAdHocLocks()

func SanitizeFilename 

func SanitizeFilename(name string) string

func SetFlagsFromEnvironment 

func SetFlagsFromEnvironment(prefix string)

func SetupSignalHandler 

func SetupSignalHandler() <-chan struct{}

Registers handlers for SIGINT and (on Posix systems) SIGTERM. The returned channel will be closed when either signal is sent.

func SignX509Certificate 

func SignX509Certificate(certificate *x509.Certificate, privateKey any, publicKey any) (*x509.Certificate, error)

Signs a X.509 certificate.

For RSA, privateKey should be *rsa.PrivateKey and publicKey should be *rsa.PublicKey.

func SplitIPAddressPort 

func SplitIPAddressPort(addressPort string) (string, int, bool)

func StringToBytes 

func StringToBytes(string_ string) (bytes []byte)

This conversion *does not* copy data. Note that converting via "([]byte)(string)" *does* copy data. Also note that you *should not* change the byte slice after conversion, because Go strings are treated as immutable. This would cause a segmentation violation panic.

func ToBase64 

func ToBase64(bytes []byte) string

func ToBroadcastIPAddress 

func ToBroadcastIPAddress(address string) (string, error)

The argument is validated as being a multicast address, e.g. "ff02::1" (IPv6) or "239.0.0.1" (IPv4). For IPv6, if it does not include a zone, a valid zone will be added by enumerating the active local interfaces, chosing one arbitrarily.

func ToBytes 

func ToBytes(content any) []byte

func ToDromedaryCase 

func ToDromedaryCase(name string) string

func ToFloat64 

func ToFloat64(value any) (float64, bool)

Converts any number type to float64.

Support types are int64, int32, int16, int8, int, uint64, uint32, uint16, uint8, uint, float64, and float32.

Precision may be lost.

func ToInt64 

func ToInt64(value any) (int64, bool)

Converts any number type to int64.

Supported types are int64, int32, int16, int8, int, uint64, uint32, uint16, uint8, uint, float64, and float32.

Precision may be lost.

func ToKebabCase 

func ToKebabCase(name string) string

func ToRawTerminal 

func ToRawTerminal(f func() error)

func ToReachableIPAddress 

func ToReachableIPAddress(address string) (string, error)

Always returns a specified address. If the argument is already a specified address, returns it as is. Otherwise (when it's "::" or "0.0.0.0") will attempt to find a specified address by enumerating the active local interfaces, chosing one arbitrarily, with a preference for a global unicast address.

The IP version of the returned address will match that of the argument, IPv6 for "::" and IPv4 for "0.0.0.0".

Note that a returned IPv6 address may include a zone (when not a global unicast).

func ToSnakeCase 

func ToSnakeCase(name string) string

func ToString 

func ToString(value any) string

Converts any value to a string.

Will use the fmt.Stringer interface if implemented.

Will use the [error] interface if implemented.

nil will become "nil". []byte will become a string. Primitive types will use strconv. Any other type will use fmt.Sprintf("%+v").

func ToStrings 

func ToStrings(values []any) []string

Calls ToString on all slice elements.

func ToUInt64 

func ToUInt64(value any) (uint64, bool)

Converts any number type to uint64.

Support types are int64, int32, int16, int8, int, uint64, uint32, uint16, uint8, uint, float64, and float32.

Precision may be lost.

func Touch 

func Touch(path string, permissions fs.FileMode, dirPermissions fs.FileMode) error

func WriteBytesToChannel 

func WriteBytesToChannel(ch chan []byte, p []byte, copy bool) (int, error)

Sends the byte slice to a channel and returns its length.

When copy is true will copy the byte slice before sending it to the channel. This is necessary for ensuring that the submitted data is indeed the data that will be received, even if the underlying array changes after this call.

func WriteNewline 

func WriteNewline(writer io.Writer) error

func WriteTLSCertificatePEM 

func WriteTLSCertificatePEM(writer io.Writer, certificate *tls.Certificate) error

func WriteTLSRSAKeyPEM 

func WriteTLSRSAKeyPEM(writer io.Writer, certificate *tls.Certificate) error

Types

type BufferedWriter 

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

func NewBufferedWriter 

func NewBufferedWriter(writer io.Writer, size int, copy bool) *BufferedWriter

Creates a thread-safe io.WriterCloser that separates the acceptance of byte slices via BufferedWriter.Write from the actual writing of the data to the underlying io.Writer, which occurs on a separate goroutine.

The size argument is for the internal channel, referring to the maximum number of write submissions to be buffered (not the number of bytes). If the buffering channel is full then BufferedWriter.Write will return an error. The actual write errors are ignored.

When copy is true the implementation copies the byte slice before sending it to the separate goroutine. This ensures that the submitted data is indeed the data that will be written, even if the underlying array changes after submission.

func (*BufferedWriter) Close 

func (self *BufferedWriter) Close() error

(io.Closer interface)

func (*BufferedWriter) Write 

func (self *BufferedWriter) Write(p []byte) (int, error)

(io.Writer interface)

type ChannelReader 

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

func NewChannelReader 

func NewChannelReader(ch chan []byte) *ChannelReader

Creates an io.Reader that reads bytes from a channel. This works via a separate goroutine that pipes (via io.Pipe) the channel data.

func (*ChannelReader) Read 

func (self *ChannelReader) Read(p []byte) (n int, err error)

(io.Reader interface)

type ChannelWriter 

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

func NewChannelWriter 

func NewChannelWriter(ch chan []byte, copy bool) *ChannelWriter

Creates an io.Writer that writes bytes to a channel. The expectation is that something else will be receiving from the channel and processing the bytes. Writing is non-blocking: if the channel is full then ChannelWriter.Write will return an error.

When copy is true the implementation copies the byte slice before sending it to the channel. This ensures that the submitted data is indeed the data that will be received, even if the underlying array changes after submission.

func (*ChannelWriter) Write 

func (self *ChannelWriter) Write(p []byte) (int, error)

(io.Writer interface)

type ContextualReadCloser 

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

Creates a io.ReadCloser that allows cancellation of reading via a provided context. Note that cancellation is not guaranteed because the underlying reader is called in-thread. At best we can guarantee that subsequent calls to ContextualReadCloser.Read will fail after cancellation.

func (ContextualReadCloser) Close 

func (self ContextualReadCloser) Close() error

(io.Closer interface)

func (*ContextualReadCloser) Read 

func (self *ContextualReadCloser) Read(p []byte) (int, error)

(io.Reader interface)

type ContextualReader 

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

Creates a io.Reader that allows cancellation of reading via a provided context. Note that cancellation is not guaranteed because the underlying reader is called in-thread. At best we can guarantee that subsequent calls to ContextualReader.Read will fail after cancellation.

func (*ContextualReader) Read 

func (self *ContextualReader) Read(p []byte) (int, error)

(io.Reader interface)

type CoordinatedWork 

type CoordinatedWork struct {
	sync.Map
}

func NewCoordinatedWork 

func NewCoordinatedWork() *CoordinatedWork

func (*CoordinatedWork) Start 

func (self *CoordinatedWork) Start(context contextpkg.Context, key string) (Promise, bool)

type Executor 

type Executor[T any] interface {
	Queue(task T)
	Wait() []error
	Close()
}

type ExitFunctionHandle 

type ExitFunctionHandle int

func OnExit 

func OnExit(exitFunction func()) ExitFunctionHandle

func OnExitError 

func OnExitError(exitFunction func() error) ExitFunctionHandle

func (ExitFunctionHandle) Cancel 

func (self ExitFunctionHandle) Cancel()

type FilterIPFunc 

type FilterIPFunc func(ip net.IP) bool

type FilterInterfaceFunc 

type FilterInterfaceFunc func(interface_ net.Interface) bool

type ForceHTTPSRoundTripper 

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

func NewForceHTTPSRoundTripper 

func NewForceHTTPSRoundTripper(roundTripper http.RoundTripper) *ForceHTTPSRoundTripper

func (*ForceHTTPSRoundTripper) RoundTrip 

func (self *ForceHTTPSRoundTripper) RoundTrip(request *http.Request) (*http.Response, error)

http.RoundTripper interface

type GetResults 

type GetResults[E any] func(offset uint) (Results[E], error)

type IPAddressCollector 

type IPAddressCollector struct {
	// If nil, will call net.Interfaces().
	Interfaces []net.Interface

	// Which IP version to accept.
	IPv6 bool

	// Include IPv6 zone in returned addresses.
	WithZone bool

	// Return true to accept an interface (can be nil).
	FilterInterface FilterInterfaceFunc

	// Return true to accept an IP (can be nil).
	// Note that the argument's address (ip.String()) does not include the IPv6 zone.
	FilterIP FilterIPFunc
}

func (*IPAddressCollector) Collect 

func (self *IPAddressCollector) Collect() ([]string, error)

type IPStack 

type IPStack string
const (
	DualStack IPStack = "dual"
	IPv6Stack IPStack = "ipv6"
	IPv4Stack IPStack = "ipv4"
)

func (IPStack) ClientBind 

func (self IPStack) ClientBind(address string) IPStackBind

func (IPStack) Level2Protocol 

func (self IPStack) Level2Protocol() string

func (IPStack) ServerBinds 

func (self IPStack) ServerBinds(address string) []IPStackBind

func (IPStack) StartServers 

func (self IPStack) StartServers(address string, start IPStackStartServerFunc) error

func (IPStack) Validate 

func (self IPStack) Validate(name string) error

type IPStackBind 

type IPStackBind struct {
	Level2Protocol string
	Address        string
}

type IPStackStartServerFunc 

type IPStackStartServerFunc func(level2protocol string, address string) error

type IterateResultsFunc 

type IterateResultsFunc[E any] func(entity E) error

type LockType 

type LockType int
const (
	DefaultLock LockType = 0
	SyncLock    LockType = 1
	DebugLock   LockType = 2
	MockLock    LockType = 3
)

type LockableEntity 

type LockableEntity interface {
	GetEntityLock() RWLocker
}

type MockLocker 

type MockLocker struct{}

func (MockLocker) Lock 

func (self MockLocker) Lock()

(sync.Locker interface)

func (MockLocker) Unlock 

func (self MockLocker) Unlock()

(sync.Locker interface)

type MockRWLocker 

type MockRWLocker struct {
	MockLocker
}

func (MockRWLocker) RLock 

func (self MockRWLocker) RLock()

(RWLocker interface)

func (MockRWLocker) RLocker 

func (self MockRWLocker) RLocker() sync.Locker

(RWLocker interface)

func (MockRWLocker) RUnlock 

func (self MockRWLocker) RUnlock()

(RWLocker interface)

type NamedPipe 

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

func NewTempNamedPipe 

func NewTempNamedPipe(writer io.Writer, mode uint32) (*NamedPipe, error)

Creates a named pipe using syscall.Mkfifo in the OS temp directory. Currently only supported on Linux.

func (*NamedPipe) Close 

func (self *NamedPipe) Close() error

(io.Closer interface)

func (*NamedPipe) Write 

func (self *NamedPipe) Write(p []byte) (int, error)

(io.Writer interface)

type ParallelExecutor 

type ParallelExecutor[T any] struct {
	PanicAsError string // when non-empty, wil capture panics as errors under this name
	// contains filtered or unexported fields
}

func NewParallelExecutor 

func NewParallelExecutor[T any](bufferSize int, processor func(task T) error) *ParallelExecutor[T]

func (*ParallelExecutor[T]) Close 

func (self *ParallelExecutor[T]) Close()

(Executor interface)

func (*ParallelExecutor[T]) Queue 

func (self *ParallelExecutor[T]) Queue(task T)

(Executor interface)

func (*ParallelExecutor[T]) Start 

func (self *ParallelExecutor[T]) Start(workers int)

func (*ParallelExecutor[T]) Wait 

func (self *ParallelExecutor[T]) Wait() []error

(Executor interface)

type Promise 

type Promise chan struct{}

func NewPromise 

func NewPromise() Promise

func (Promise) Release 

func (self Promise) Release()

func (Promise) Wait 

func (self Promise) Wait(context contextpkg.Context) error

type RWLocker 

type RWLocker interface {
	sync.Locker
	RLock()
	RUnlock()
	RLocker() sync.Locker
}

func GetAdHocLock 

func GetAdHocLock(pointer any, type_ LockType) RWLocker

Warning: Because pointers can be re-used after the resource is freed, there is no way for us to guarantee ad-hoc locks would not be reused Thus this facililty should only be used for objects with a known and managed life span.

func GetEntityLock 

func GetEntityLock(entity any) RWLocker

From LockableEntity interface.

func NewDebugRWLocker 

func NewDebugRWLocker() RWLocker

func NewDefaultRWLocker 

func NewDefaultRWLocker() RWLocker

func NewMockRWLocker 

func NewMockRWLocker() RWLocker

func NewRWLocker 

func NewRWLocker(type_ LockType) RWLocker

func NewSyncRWLocker 

func NewSyncRWLocker() RWLocker

type Results 

type Results[E any] interface {
	Next() (E, error) // can return io.EOF
	Release()
}

func CombineResults 

func CombineResults[E any](get GetResults[E]) Results[E]

type ResultsSlice 

type ResultsSlice[E any] struct {
	// contains filtered or unexported fields
}

func NewResult 

func NewResult[E any](entity E) *ResultsSlice[E]

func NewResultsSlice 

func NewResultsSlice[E any](entities []E) *ResultsSlice[E]

func (*ResultsSlice[E]) Next 

func (self *ResultsSlice[E]) Next() (E, error)

(Results interface)

func (*ResultsSlice[E]) Release 

func (self *ResultsSlice[E]) Release()

(Results interface)

type ResultsStream 

type ResultsStream[E any] struct {
	// contains filtered or unexported fields
}

func NewResultsStream 

func NewResultsStream[E any](release func()) *ResultsStream[E]

func (*ResultsStream[E]) Close 

func (self *ResultsStream[E]) Close(err error)

Special handling for nil and io.EOF

func (*ResultsStream[E]) Next 

func (self *ResultsStream[E]) Next() (E, error)

(Results interface)

func (*ResultsStream[E]) Release 

func (self *ResultsStream[E]) Release()

(Results interface)

func (*ResultsStream[E]) Send 

func (self *ResultsStream[E]) Send(info E)

type RuneReader 

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

func NewRuneReader 

func NewRuneReader(runes []rune) *RuneReader

func (*RuneReader) ReadRune 

func (self *RuneReader) ReadRune() (rune, int, error)

(io.RuneReader interface)

type SyncedWriter 

type SyncedWriter struct {
	Writer io.Writer
	// contains filtered or unexported fields
}

func NewSyncedWriter 

func NewSyncedWriter(writer io.Writer) *SyncedWriter

Creates a thread-safe io.WriterCloser that synchronizes all the SyncedWriter.Write calls via a mutex.

If the underlying writer does not support io.Closer then SyncedWriter.Close will do nothing.

func (*SyncedWriter) Close 

func (self *SyncedWriter) Close() error

(io.Closer interface)

func (*SyncedWriter) Write 

func (self *SyncedWriter) Write(p []byte) (int, error)

(io.Writer interface)

type TarEncoder 

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

func NewTarEncoder 

func NewTarEncoder(reader io.Reader, name string, size int64) *TarEncoder

func (*TarEncoder) Drain 

func (self *TarEncoder) Drain()

func (*TarEncoder) Encode 

func (self *TarEncoder) Encode() io.Reader

type TarballEntryReader 

type TarballEntryReader struct {
	TarballReader *TarballReader
}

func NewTarballEntryReader 

func NewTarballEntryReader(tarballReader *TarballReader) *TarballEntryReader

func (*TarballEntryReader) Close 

func (self *TarballEntryReader) Close() error

(io.Closer interface)

func (*TarballEntryReader) Read 

func (self *TarballEntryReader) Read(p []byte) (n int, err error)

(io.Reader interface)

type TarballReader 

type TarballReader struct {
	TarReader         *tar.Reader
	ArchiveReader     io.ReadCloser
	CompressionReader io.ReadCloser
}

func NewTarballReader 

func NewTarballReader(reader *tar.Reader, archiveReader io.ReadCloser, compressionReader io.ReadCloser) *TarballReader

func (*TarballReader) Close 

func (self *TarballReader) Close() error

(io.Closer interface)

func (*TarballReader) Has 

func (self *TarballReader) Has(path string) (bool, error)

func (*TarballReader) Iterate 

func (self *TarballReader) Iterate(f func(*tar.Header) bool) error

func (*TarballReader) Open 

func (self *TarballReader) Open(path string) (*TarballEntryReader, error)

type TestLogWriter 

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

func NewTestLogWriter 

func NewTestLogWriter(t *testing.T) *TestLogWriter

func (*TestLogWriter) Write 

func (self *TestLogWriter) Write(p []byte) (n int, err error)

(io.Writer interface)

Source Files

View all Source files

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.