README
¶
Core of helpers for darvaza.org projects
This package contains simple mechanisms used by other darvaza-proxy projects. It's not allowed to have dependencies outside of Go' Standard Library, and if something should be on a subdirectory, it shouldn't be here.
Network
- GetInterfacesNames
- ParseAddr/ParseNetIP
- SplitHostPort/SplitAddrPort
- AddrPort
- AddrFromNetIP
- GetIPAddresses/GetNetIPAddresses/GetStringIPAddresses
Generics
- Zero/IsZero
- Coalesce/IIf
- SliceContains/SliceContainsFn
- SliceMinus/SliceMinusFn
- SliceUnique/SliceUniqueFn
- SliceUniquify/SliceUniquifyFn
- SliceReplaceFn/SliceCopyFn
- SliceRandom
- ListContains/ListContainsFn
- ListForEach/ListForEachElement
- ListForEachBackward/ListForEachBackwardElement
- MapContains
- MapListContains/MapListContainsFn
- MapListForEach/MapListForEachElement
- MapListInsert/MapListAppend
- MapListInsertUnique/MapListInsertUniqueFn
- MapListAppendUnique/MapListAppendUniqueFn
- MapAllListContains/MapAllListContainsFn
- MapAllListForEach/MapAllListForEachElement
- NewContextKey
Errors
-
Wrap/Unwrappable
-
Errors/CompoundError
-
CoalesceError
-
AsRecovered/Recovered
-
Catcher
-
PanicError
-
Panic/Panicf/PanicWrap
-
WaitGroup/ErrGroup
-
Frame/Stack
-
Here/StackFrame/StackTrace
-
CallStacker
-
ErrNotImplemented/ErrTODO
-
ErrExists/ErrNotExists
-
ErrInvalid/ErrUnknown
See also
Documentation
¶
Overview ¶
Package core provides fundamental helpers for darvaza.org projects
Index ¶
- Constants
- Variables
- func AddrFromNetIP(addr net.Addr) (netip.Addr, bool)
- func AddrPort(v any) (netip.AddrPort, bool)
- func Coalesce[T any](opts ...T) T
- func CoalesceError(errs ...error) error
- func GetIPAddresses(ifaces ...string) ([]netip.Addr, error)
- func GetInterfacesNames(except ...string) ([]string, error)
- func GetNetIPAddresses(ifaces ...string) ([]net.IP, error)
- func GetStringIPAddresses(ifaces ...string) ([]string, error)
- func IIf[T any](cond bool, yes, no T) T
- func IsZero(vi any) bool
- func ListContains[T comparable](l *list.List, val T) bool
- func ListContainsFn[T any](l *list.List, val T, eq func(T, T) bool) bool
- func ListForEach[T any](l *list.List, fn func(v T) bool)
- func ListForEachBackward[T any](l *list.List, fn func(v T) bool)
- func ListForEachBackwardElement(l *list.List, fn func(*list.Element) bool)
- func ListForEachElement(l *list.List, fn func(*list.Element) bool)
- func MapAllListContains[K comparable, T comparable](m map[K]*list.List, v T) bool
- func MapAllListContainsFn[K comparable, T any](m map[K]*list.List, match func(v T) bool) bool
- func MapAllListForEach[K comparable, T any](m map[K]*list.List, fn func(v T) bool)
- func MapAllListForEachElement[K comparable](m map[K]*list.List, fn func(*list.Element) bool)
- func MapContains[K comparable](m map[K]any, key K) bool
- func MapListAppend[K comparable, T any](m map[K]*list.List, key K, v T)
- func MapListAppendUnique[K comparable, T comparable](m map[K]*list.List, key K, v T)
- func MapListAppendUniqueFn[K comparable, T any](m map[K]*list.List, key K, v T, eq func(T, T) bool)
- func MapListContains[K comparable, T comparable](m map[K]*list.List, key K, v T) bool
- func MapListContainsFn[K comparable, T any](m map[K]*list.List, key K, v T, eq func(T, T) bool) bool
- func MapListForEach[K comparable, T any](m map[K]*list.List, key K, fn func(v T) bool)
- func MapListForEachElement[K comparable](m map[K]*list.List, key K, fn func(el *list.Element) bool)
- func MapListInsert[K comparable, T any](m map[K]*list.List, key K, v T)
- func MapListInsertUnique[K comparable, T comparable](m map[K]*list.List, key K, v T)
- func MapListInsertUniqueFn[K comparable, T any](m map[K]*list.List, key K, v T, eq func(va, vb T) bool)
- func Panic(payload any)
- func PanicWrap(err error, format string, args ...any)
- func Panicf(format string, args ...any)
- func ParseAddr(s string) (addr netip.Addr, err error)
- func ParseNetIP(s string) (ip net.IP, err error)
- func SliceContains[T comparable](a []T, v T) bool
- func SliceContainsFn[T any](a []T, v T, eq func(T, T) bool) bool
- func SliceCopyFn[T any](s []T, fn func(partial []T, before T) (after T, replace bool)) []T
- func SliceMinus[T comparable](a []T, b []T) []T
- func SliceMinusFn[T any](a, b []T, eq func(T, T) bool) []T
- func SliceRandom[T any](a []T) (T, bool)
- func SliceReplaceFn[T any](s []T, fn func(partial []T, before T) (after T, replace bool)) []T
- func SliceUnique[T comparable](a []T) []T
- func SliceUniqueFn[T any](a []T, eq func(T, T) bool) []T
- func SliceUniquify[T comparable](ptr *[]T) []T
- func SliceUniquifyFn[T any](ptr *[]T, eq func(T, T) bool) []T
- func SplitAddrPort(addrPort string) (addr netip.Addr, port uint16, err error)
- func SplitHostPort(hostPort string) (host, port string, err error)
- func Wrap(err error, format string, args ...any) error
- func Zero[T any](_ *T) T
- type CallStacker
- type Catcher
- type CompoundError
- type ContextKey
- type ErrGroup
- func (eg *ErrGroup) Cancel(cause error) bool
- func (eg *ErrGroup) Cancelled() <-chan struct{}
- func (eg *ErrGroup) Context() context.Context
- func (eg *ErrGroup) Done() <-chan struct{}
- func (eg *ErrGroup) Err() error
- func (eg *ErrGroup) Go(run func(context.Context) error, shutdown func() error)
- func (eg *ErrGroup) GoCatch(run func(context.Context) error, catch func(context.Context, error) error)
- func (eg *ErrGroup) IsCancelled() bool
- func (eg *ErrGroup) OnError(fn func(error))
- func (eg *ErrGroup) SetDefaults()
- func (eg *ErrGroup) Wait() error
- type Errors
- type Frame
- type PanicError
- type Recovered
- type Stack
- type Unwrappable
- type WaitGroup
- type WrappedError
Constants ¶
const (
// MaxDepth is the maximum depth we will go in the stack.
MaxDepth = 32
)
Variables ¶
var ( // ErrNotImplemented indicates something hasn't been implemented yet ErrNotImplemented = errors.New("not implemented") // ErrTODO is like ErrNotImplemented but used especially to // indicate something needs to be implemented ErrTODO = Wrap(ErrNotImplemented, "TODO") // ErrExists indicates something already exists ErrExists = errors.New("already exists") // ErrNotExists indicates something doesn't exist ErrNotExists = errors.New("does not exist") // ErrInvalid indicates an argument isn't valid ErrInvalid = errors.New("invalid argument") // ErrUnknown indicates something isn't recognized ErrUnknown = errors.New("unknown") )
Functions ¶
func AddrFromNetIP ¶
AddrFromNetIP attempts to convert a net.Addr into a netip.Addr
func CoalesceError ¶ added in v0.9.5
CoalesceError returns the first non-nil error argument. error isn't compatible with Coalesce's comparable generic type.
func GetIPAddresses ¶
GetIPAddresses returns a list of netip.Addr bound to the given interfaces or all if none are given
func GetInterfacesNames ¶
GetInterfacesNames returns the list of interfaces, considering an optional exclusion list
func GetNetIPAddresses ¶
GetNetIPAddresses returns a list of net.IP addresses bound to the given interfaces or all if none are given
func GetStringIPAddresses ¶
GetStringIPAddresses returns a list of text IP addresses bound to the given interfaces or all if none are given
func IsZero ¶ added in v0.9.8
IsZero checks if a given value is zero, either using the IsZero() bool interface or reflection
func ListContains ¶
func ListContains[T comparable](l *list.List, val T) bool
ListContains checks if a container/list contains an element
func ListContainsFn ¶
ListContainsFn checks if a container/list contains an element that satisfies a given function
func ListForEach ¶
ListForEach calls a function for each value until told to stop
func ListForEachBackward ¶
ListForEachBackward calls a function for each value until told to stop
func ListForEachBackwardElement ¶
ListForEachBackwardElement calls a function for each element until told to stop
func ListForEachElement ¶
ListForEachElement calls a function for each element until told to stop
func MapAllListContains ¶
func MapAllListContains[K comparable, T comparable](m map[K]*list.List, v T) bool
MapAllListContains check if a value exists on any entry of the map
func MapAllListContainsFn ¶
MapAllListContainsFn check if a value exists on any entry of the map using a match function
func MapAllListForEach ¶
func MapAllListForEach[K comparable, T any](m map[K]*list.List, fn func(v T) bool)
MapAllListForEach calls a function for each value on all map entries until told to stop
func MapAllListForEachElement ¶
MapAllListForEachElement calls a function for each element on all map entries until told to stop
func MapContains ¶
func MapContains[K comparable](m map[K]any, key K) bool
MapContains tells if a given map contains a key. this helper is intended for switch/case conditions
func MapListAppend ¶
func MapListAppend[K comparable, T any](m map[K]*list.List, key K, v T)
MapListAppend adds a value at the end of the list of a map entry
func MapListAppendUnique ¶
func MapListAppendUnique[K comparable, T comparable](m map[K]*list.List, key K, v T)
MapListAppendUnique adds a value at the end of the list of a map entry if it's not already there
func MapListAppendUniqueFn ¶
func MapListAppendUniqueFn[K comparable, T any](m map[K]*list.List, key K, v T, eq func(T, T) bool)
MapListAppendUniqueFn adds a value at the end of the list of a map entry if it's not already there using a function to compare values
func MapListContains ¶
func MapListContains[K comparable, T comparable](m map[K]*list.List, key K, v T) bool
MapListContains checks if the list.List on a map contains an element
func MapListContainsFn ¶
func MapListContainsFn[K comparable, T any](m map[K]*list.List, key K, v T, eq func(T, T) bool) bool
MapListContainsFn checks if the list.List on a map contains an element using a match functions
func MapListForEach ¶
func MapListForEach[K comparable, T any](m map[K]*list.List, key K, fn func(v T) bool)
MapListForEach calls a function for each value on a map entry until told to stop
func MapListForEachElement ¶
MapListForEachElement calls a function for each element on a map entry until told to stop
func MapListInsert ¶
func MapListInsert[K comparable, T any](m map[K]*list.List, key K, v T)
MapListInsert adds a value at the front of the list of a map entry
func MapListInsertUnique ¶
func MapListInsertUnique[K comparable, T comparable](m map[K]*list.List, key K, v T)
MapListInsertUnique adds a value at the front of the list of a map entry if it's not already there
func MapListInsertUniqueFn ¶
func MapListInsertUniqueFn[K comparable, T any](m map[K]*list.List, key K, v T, eq func(va, vb T) bool)
MapListInsertUniqueFn adds a value at the front of the list of a map entry if it's not already there using a function to compare values
func PanicWrap ¶
PanicWrap emits a PanicError wrapping an annotated error, optionally formatted. %w is expanded.
func ParseNetIP ¶
ParseNetIP turns a string into a net.IP
func SliceContains ¶
func SliceContains[T comparable](a []T, v T) bool
SliceContains tells if a slice contains a given element
func SliceContainsFn ¶
SliceContainsFn tells if a slice contains a given element according to the callback eq
func SliceCopyFn ¶
SliceCopyFn conditionally copies a slice allowing modifications of the items
func SliceMinus ¶
func SliceMinus[T comparable](a []T, b []T) []T
SliceMinus returns a new slice containing only the elements of one slice not present on the second
func SliceMinusFn ¶
SliceMinusFn returns a new slice containing only elements of slice A that aren't on slice B according to the callback eq
func SliceRandom ¶ added in v0.9.2
SliceRandom returns a random element from a slice if the slice is empty it will return the zero value of the slice type and false
func SliceReplaceFn ¶
SliceReplaceFn replaces or skips entries in a slice
func SliceUnique ¶
func SliceUnique[T comparable](a []T) []T
SliceUnique returns a new slice containing only unique elements
func SliceUniqueFn ¶
SliceUniqueFn returns a new slice containing only unique elements according to the callback eq
func SliceUniquify ¶
func SliceUniquify[T comparable](ptr *[]T) []T
SliceUniquify returns the same slice, reduced to only contain unique elements
func SliceUniquifyFn ¶
SliceUniquifyFn returns the same slice, reduced to only contain unique elements according to the callback eq
func SplitAddrPort ¶ added in v0.10.1
SplitAddrPort splits a string containing an IP address and an optional port, and validates it.
func SplitHostPort ¶
SplitHostPort is like net.SplitHostPort but doesn't fail if the port isn't part of the string and it validates it if present. SplitHostPort will also validate the host is a valid IP or name
Types ¶
type CallStacker ¶
type CallStacker interface {
CallStack() Stack
}
CallStacker represents an object with a method CallStack() returning a Stack
type Catcher ¶
type Catcher struct {
// contains filtered or unexported fields
}
Catcher is a runner that catches panics
type CompoundError ¶ added in v0.9.1
type CompoundError struct {
Errs []error
}
A CompoundError can contain more that one error
func (*CompoundError) AppendError ¶ added in v0.9.1
func (w *CompoundError) AppendError(err error)
AppendError adds an error to the collection, unwrapping other implementers of the Errors interface when possible
func (*CompoundError) AsError ¶ added in v0.9.1
func (w *CompoundError) AsError() error
AsError returns itself as an `error` when there are errors stored, and nil when there aren't
func (*CompoundError) Error ¶ added in v0.9.1
func (w *CompoundError) Error() string
func (*CompoundError) Errors ¶ added in v0.9.1
func (w *CompoundError) Errors() []error
Errors returns the contained slice of errors
func (*CompoundError) Ok ¶ added in v0.9.1
func (w *CompoundError) Ok() bool
Ok tells when there are no errors stored
type ContextKey ¶
type ContextKey[T any] struct { // contains filtered or unexported fields }
ContextKey is a type-safe key for a context.Context value
func NewContextKey ¶
func NewContextKey[T any](name string) *ContextKey[T]
NewContextKey creates a new ContextKey bound to the specified type and friendly name
func (*ContextKey[T]) Get ¶
func (ck *ContextKey[T]) Get(ctx context.Context) (T, bool)
Get attempts to extract a value bound to this key in a context.Context For convenience this method will safely operate over a nil receiver.
func (*ContextKey[T]) GoString ¶
func (ck *ContextKey[T]) GoString() string
GoString renders this key in Go syntax for %v
type ErrGroup ¶ added in v0.11.0
ErrGroup handles a group of workers where all are canceled once one fails. As it's based on WaitGroup it also catches panics.
func (*ErrGroup) Cancel ¶ added in v0.11.0
Cancel initiates a shutdown of the group. The returned value indicates if it was the first time.
func (*ErrGroup) Cancelled ¶ added in v0.11.0
func (eg *ErrGroup) Cancelled() <-chan struct{}
Cancelled returns a channel marker to know when the Group has been cancelled and the shutdown has been initiated.
Cancelled() doesn't indicate all workers have finished, for that call ErrGroup.Wait or ErrGroup.Done.
func (*ErrGroup) Context ¶ added in v0.11.0
Context returns the cancellable context used with the workers
func (*ErrGroup) Done ¶ added in v0.11.1
func (eg *ErrGroup) Done() <-chan struct{}
Done returns a channel that gets closed when all workers have finished.
func (*ErrGroup) Go ¶ added in v0.11.0
Go spawns a worker and an optional shutdown routine to be invoked when the ErrGroup is cancelled, otherwise the provided context needs to be monitored and shutdown called.
func (*ErrGroup) GoCatch ¶ added in v0.11.0
func (eg *ErrGroup) GoCatch(run func(context.Context) error, catch func(context.Context, error) error)
GoCatch runs a worker on the Group, with a custom error handler.
func (*ErrGroup) IsCancelled ¶ added in v0.11.0
IsCancelled tells the ErrGroup has been cancelled
func (*ErrGroup) OnError ¶ added in v0.11.0
OnError sets a helper that will be called when a worker returns an error or panics
func (*ErrGroup) SetDefaults ¶ added in v0.11.0
func (eg *ErrGroup) SetDefaults()
SetDefaults fills gaps in the config and initializes the internal structure.
type Frame ¶
type Frame struct {
// contains filtered or unexported fields
}
Frame represents a function call on the call Stack. This implementation is heavily based on github.com/pkg/errors.Frame but all parts are resolved immediately for later consumption.
func Here ¶
func Here() *Frame
Here returns the Frame corresponding to where it was called, or nil if it wasn't possible
func StackFrame ¶
StackFrame returns the Frame skip levels above from where it was called, or nil if it wasn't possible
func (Frame) FileLine ¶
FileLine returns File name and Line separated by a colon, or only the filename if the Line isn't known
func (Frame) Format ¶
Format formats the frame according to the fmt.Formatter interface. * * %s source file * %d source line * %n function name * %v equivalent to %s:%d * * Format accepts flags that alter the printing of some verbs, as follows: * * %+s function name and path of source file relative to the compile time * GOPATH separated by \n\t (<funcname>\n\t<path>) * %+n full package name followed by function name * %+v equivalent to %+s:%d
func (Frame) FuncName ¶ added in v0.9.10
FuncName returns the name of the function, without the package name
func (Frame) Line ¶
Line returns the file number on the source code corresponding to this Frame, or zero if unknown.
type PanicError ¶
type PanicError struct {
// contains filtered or unexported fields
}
PanicError is an error to be sent via panic, ideally to be caught using slog.Recover()
func NewPanicError ¶
func NewPanicError(skip int, payload any) *PanicError
NewPanicError creates a new PanicError with arbitrary payload
func NewPanicErrorf ¶
func NewPanicErrorf(skip int, format string, args ...any) *PanicError
NewPanicErrorf creates a new PanicError annotated with a string, optionally formatted. %w is expanded.
func NewPanicWrap ¶
func NewPanicWrap(skip int, err error, format string, args ...any) *PanicError
NewPanicWrap creates a new PanicError wrapping a given error annotated, optionally formatted. %w is expanded.
func (*PanicError) CallStack ¶
func (p *PanicError) CallStack() Stack
CallStack returns the call stack associated to this panic() event
func (*PanicError) Error ¶
func (p *PanicError) Error() string
Error returns the payload as a string
func (*PanicError) Recovered ¶
func (p *PanicError) Recovered() any
Recovered returns the payload of the panic
func (*PanicError) Unwrap ¶
func (p *PanicError) Unwrap() error
Unwrap returns the payload if it's and error
type Recovered ¶
Recovered is an error caught from a panic call
func AsRecovered ¶
AsRecovered receives the value from recover() and wraps it as a Recovered error
type Stack ¶
type Stack []Frame
Stack is an snapshot of the call stack in the form of an array of Frames.
func StackTrace ¶
StackTrace returns a snapshot of the call stack starting skip levels above from where it was called, on an empty array if it wasn't possible
type Unwrappable ¶
Unwrappable represents an error that can be Unwrap() to get the cause
type WaitGroup ¶
type WaitGroup struct {
// contains filtered or unexported fields
}
WaitGroup is a safer way to run workers
func (*WaitGroup) Done ¶ added in v0.11.1
func (wg *WaitGroup) Done() <-chan struct{}
Done returns a channel that gets closed when all workers have finished.
func (*WaitGroup) GoCatch ¶
GoCatch spawns a supervised goroutine, and uses a given function to intercept the returned error
type WrappedError ¶
type WrappedError struct {
// contains filtered or unexported fields
}
WrappedError is an annotated error that can be Unwrapped
func (*WrappedError) Error ¶
func (w *WrappedError) Error() string
func (*WrappedError) Unwrap ¶
func (w *WrappedError) Unwrap() error
Source Files