coreutil

Documentation

Overview

Provides core utilities.

Index

• Constants
• Variables
• func Call[M any, R any](address string, msg M) (*R, error)
• func CallWithContext[M any, R any](address string, msg M, ctx context.Context) (*R, error)
• func Consume[M any](address string, handler func(M, CallContext)) func()
• func GetEnvironment() string
• func GetProfileString() string
• func GetSecureRandomString(lengthBytes uint) (string, error)
• func IsTerminal() bool
• func Publish[M any](address string, msg M)
• func SetProfile(profile Profile)
• func StartAndBlock(services ...Service)
• func TimePtrToUnix(t *time.Time) *int64
• func TimeToUnixPtr(t time.Time) *int64
• func ToPtr[V any](v V) *V
• func UnixPtrToTime(u *int64) *time.Time
• func UnixToTimePtr(u int64) *time.Time
• type CallContext
• type Profile
  • func GetProfile() Profile
• type Service

Constants

const (
	// ProfileDebug is the default Profile intended to be used when developing the app.
	ProfileDebug = iota

	// ProfileTest is the Profile intended to be used in unit tests.
	ProfileTest

	// ProfileRelease is the Profile intended to be enabled when the app is distributed in its binary form.
	ProfileRelease
)

Variables

var ErrCallTimeout = errors.New("timeout")

ErrCallTimeout represents an error thrown by Call and CallWithContext when the reply times out.

var ErrMessageSerialization = errors.New("message serialization")

ErrMessageSerialization represents an error thrown by Call and CallWithContext when the middleware fails to perform a type casting of a message.

var ErrNoHandlers = errors.New("no handlers")

ErrNoHandlers represents an error thrown by Call and CallWithContext when there are no consumers on the other side.

Functions

func Call

func Call[M any, R any](address string, msg M) (*R, error)

Call sends a message to the address specified as an argument, and waits for the response.

func CallWithContext

func CallWithContext[M any, R any](address string, msg M, ctx context.Context) (*R, error)

CallWithContext sends a message to the address specified as an argument, and waits for the response.

func Consume

func Consume[M any](address string, handler func(M, CallContext)) func()

Consume registers a consumer for messages sent to the address specified as an argument. Handler is called for each published message inside its own panic-safe goroutine.

func GetEnvironment

func GetEnvironment() string

GetEnvironment returns the environment name. It's taken from "environment" key from the environment variables. The default value is "default".

func GetProfileString

func GetProfileString() string

GetProfileString returns the current Profile value, taken from GetProfile, in its string form.

func GetSecureRandomString

func GetSecureRandomString(lengthBytes uint) (string, error)

GetSecureRandomString generates a cryptographically secure string of given length. Result string is encoded to hex.

func IsTerminal

func IsTerminal() bool

IsTerminal checks whether the app is being run inside an interactive terminal

func Publish

func Publish[M any](address string, msg M)

Publish sends a message to the address specified as an argument.

func SetProfile

func SetProfile(profile Profile)

SetProfile sets the global value of Profile.

func StartAndBlock

func StartAndBlock(services ...Service)

StartAndBlock starts all passed services in their designated goroutines and then blocks the current thread. Thread is unblocked when the process receives SIGINT or SIGTERM signals or one of the Start() functions returns an error. When exiting, StartAndBlock gracefully stops all the services by calling their Stop() functions and waiting for them to exit.

func TimePtrToUnix

func TimePtrToUnix(t *time.Time) *int64

TimePtrToUnix returns a pointer to epoch seconds in UTC timezone represented by given pointer to time.Time

func TimeToUnixPtr

func TimeToUnixPtr(t time.Time) *int64

TimeToUnixPtr returns a pointer to epoch seconds in UTC timezone represented by given time.Time

func ToPtr

func ToPtr[V any](v V) *V

ToPtr converts any value to a pointer

func UnixPtrToTime

func UnixPtrToTime(u *int64) *time.Time

UnixPtrToTime returns a pointer to time.Time by converting pointer to epoch seconds in UTC timezone

func UnixToTimePtr

func UnixToTimePtr(u int64) *time.Time

UnixToTimePtr returns a pointer to time.Time by converting epoch seconds in UTC timezone

Types

type CallContext

type CallContext interface {
	// Reply sends a reply back to caller.
	Reply(reply any)

	// Error sends an error back to caller.
	Error(err error)
}

CallContext is a context passed to an event bus handler. It allows consumers to send replies.

type Profile

type Profile = int

Profile represents a global setting of the application, making changes to its default behaviors.

func GetProfile

func GetProfile() Profile

GetProfile returns the current Profile of the app. It's taken from "profile" key of the environment variables. The default value is ProfileDebug. GetProfile caches the profile value when called for the first time.

type Service

type Service interface {
	// Start is expected to start execution of the service and block
	// If the execution cannot be started, or it fails abruptly, it should return a non-nil error
	Start() error

	// Stop is expected to stop the running service gracefully and unblock the thread used by Start function
	Stop()
}

Service represents concurrent job, that is expected to run in background for the whole lifecycle of the process. Common structs representing Service would be a network server, such as HTTP or gRPC server.