happy

package module
v0.2.4 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2023 License: Apache-2.0 Imports: 22 Imported by: 0

README

Happy Logo

Happy Prototyping Framework and SDK

Package happy is a powerful tool for developers looking to bring their ideas to life through rapid prototyping. With its comprehensive set of resources and modular design, it's easy to create working prototypes or MVPs with minimal technical knowledge or infrastructure planning. Plus, its flexible design allows it to seamlessly integrate into projects with components written in different programming languages. So why wait? Let Happy help you achieve your goals and bring a smile to your face along the way.

⚠ Happy is very early in development phase and is not intended for production use.

PkgGoDev

Creating application

Happy SDK is designed to simplify your development process without introducing any new or additional developer tools. Your applications built with Happy can be used, built, and tested with the standard Go build tools, such as 'go test', 'go build', and 'go run'. With Happy, you have complete control over your development environment, as it will not add any third-party dependencies to your project.

Here's a simple example of how you can use Happy:

// main.go
package main

import (
  "errors"
  "github.com/mkungla/happy"
)

func main() {
  app := happy.New()
  app.Do(func(sess *happy.Session, args happy.Args) error {
    sess.Log().Println("Hello, world!")
    return errors.New("This is just a basic example.")
  })
  app.Main()
}

For more examples, take a look at the examples section and the examples in the ./examples/ directory."

Application api

More details of api read happy Godoc

...
// All the following are optional 
app.Before(/* called always before any command is invoked*/)
app.Do(/* root command Do function */)
app.AfterSuccess(/* called when root cmd or sub command returns without errors */)
app.AfterFailure(/* called when root cmd or sub command returns with errors */)
app.AfterAlways(/* called always when root cmd or sub command returns */)
app.OnTick(/* called while root command is blocking */)
app.OnTock(/* called while root command is blocking after tick*/)
app.OnInstall(/* optional installation step to call when user first uses your app */)
app.OnMigrate(/* optional migrations step to call when user upgrades/downgrades app */)
app.Cron(/* optional cron jobs registered for application */)
app.RegisterService(/* register standalone service to your app. */)
app.AddCommand(/* add sub command to your app. */)
app.AddFlag(/* add global flag to your app. */)
app.Setting(/* add additional, custom user settings to your app */)
...
Commands

happy.Command provides a universal API for attaching sub-commands directly to the application or providing them from an Addon.

...
cmd := happy.NewCommand(
  "my-command",
  happy.Option("usage", "My sub-command"),
)

cmd.Do(/* Main function for the command */)

// Optional:
cmd.Before(/* Called after app.Before and before cmd.Do */)
cmd.AfterSuccess(/* Called when cmd.Do returns without errors */)
cmd.AfterFailure(/* Called when cmd.Do returns with errors */)
cmd.AfterAlways(/* Called always when cmd.Do returns */)
cmd.AddSubCommand(/* Add a sub-command to the command */)
cmd.AddFlag(/* Add a flag for the command */)

app.AddCommand(cmd)
...
Services

The happy.Service API provides a flexible way to add runtime-controllable background services to your application.

...
svc := happy.NewService(
  "my-service",
  happy.Option("usage", "my custom service"),
)

svc.OnInitialize(/* Called when the app starts. */)
svc.OnStart(/* Called when the service is requested to start. */)
svc.OnStop(/* Called when the service is requested to stop. */)
svc.OnEvent(/* Called when a specific event is received. */)
svc.OnAnyEvent(/* Called when any event is received. */)
svc.Cron(/* Scheduled cron jobs to run when the service is running. */)
svc.OnTick(/* Called every tick when the service is running. */)
svc.OnTock(/* Called after every tick when the service is running. */)

app.RegisterService(svc)
...

Addons

Addons provide a simple way to bundle commands and services into a single Go package, allowing for easy sharing between projects.

// main.go
package main

import (
  "github.com/mkungla/happy"
  "helloworld"
)

func main() {
  app := happy.New()
  app.WithAddons(helloworld.Addon())
  app.Main()
}


// helloworld/addon.go
package helloworld

import "github.com/mkungla/happy"

func Addon() *happy.Addon {
  addon := happy.NewAddon(
    "hello-world",
    happy.Option("description", "example addon"),
  )

  // Optional: Set a custom setting
  addon.Setting("greet.msg", "any value", "setting description", /* validation func */)

  // Optional: Register commands provided by the addon
  addon.ProvidesCommand(...)

  // Optional: Register services provided by the addon
  addon.ProvidesService(...)

  // Optional: Make a custom API accessible across the application 
  addon.API = &HelloWorldAPI{}

  // Register all events that the addon may emit
  addon.Emits("event scope", "event key" , "event description", /* example payload */)

  // Optional callback to be called when the addon is registered
  addon.OnRegister(func(sess *happy.Session, opts *happy.Options) error {
    sess.Log().Notice("hello-world addon registered")
    return nil
  })

  return addon
}

examples

hello

most minimal usage

go run ./examples/hello/
go run ./examples/hello/ nickname
# increase verbosity
go run ./examples/hello/ --debug
go run ./examples/hello/ --system-debug
# help
go run ./examples/hello/ -h

kitchensink

main application when no subcommand is provided

go run ./examples/kitchensink/
# increase verbosity
go run ./examples/kitchensink/ --verbose
go run ./examples/kitchensink/ --debug
go run ./examples/kitchensink/ --system-debug

# main application help
go run ./examples/kitchensink/ -h

hello command with flags

go run ./examples/kitchensink/ hello --name me --repeat 10 
# or shorter
go run ./examples/kitchensink/ hello -n me -r 10 

# help for hello command
go run ./examples/kitchensink/ hello -h

Credits

GitHub contributors

Happy banner design.
Happy banner was designed by Egon Elbre egonelbre.com

Documentation

Overview

Package happy provides a modular framework for rapid prototyping in Go. With this SDK, developers of all levels can easily bring their ideas to life. Whether you're a hacker or a creator, Package happy has everything you need to tackle your domain problems and create working prototypes or MVPs with minimal technical knowledge and infrastructure planning.

Its modular design enables you to package your commands and services into reusable addons, so you're not locked into any vendor tools. It also fits well into projects where different components are written in different programming languages.

Let Package happy help you bring your projects from concept to reality and make you happy along the way.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrApplication      = errors.New("application error")
	ErrCommand          = errors.New("command error")
	ErrCommandFlags     = errors.New("command flags error")
	ErrCommandAction    = errors.New("command action error")
	ErrInvalidVersion   = errors.New("invalid version")
	ErrEngine           = errors.New("engine error")
	ErrSessionDestroyed = errors.New("session destroyed")
	ErrService          = errors.New("service error")
	ErrHappy            = errors.New("not so happy")
	ErrAddon            = errors.New("addon error")
)
View Source 
var (
	ErrOption           = errors.New("option error")
	ErrOptionReadOnly   = fmt.Errorf("%w: readonly option", ErrOption)
	ErrOptionValidation = fmt.Errorf("%w: validation failed", ErrOption)
)
View Source 
var OptionValidatorNotEmpty = func(key string, val vars.Value) error {
	if val.Len() == 0 {
		return fmt.Errorf("%w: %s value can not be empty", ErrOption, key)
	}
	return nil
}

Functions

func GetAPI added in v0.1.5 

func GetAPI[A API](sess *Session, addonName string) (api A, err error)

Types

type API 

type API interface {
	Get(key string) vars.Variable
}

type Action added in v0.1.5 

type Action func(sess *Session) error

type ActionMigrate added in v0.2.0 

type ActionMigrate func(ver Version, sess *Session) error

type ActionTick added in v0.1.5 

type ActionTick func(sess *Session, ts time.Time, delta time.Duration) error

ActionTickFunc is operation set in given minimal time frame it can be executed. You can throttle tick/tocks to cap FPS or for [C|G]PU throttling.

Tock is helper called after each tick to separate logic processed in tick and do post processing on tick. Tocks are useful mostly for GPU ops which need to do post proccessing of frames rendered in tick.

type ActionTock added in v0.1.5 

type ActionTock func(sess *Session, delta time.Duration, tps int) error

type ActionWithArgs added in v0.1.5 

type ActionWithArgs func(sess *Session, args Args) error

type ActionWithEvent added in v0.1.5 

type ActionWithEvent func(sess *Session, ev Event) error

type ActionWithOptions added in v0.2.0 

type ActionWithOptions func(sess *Session, opts *Options) error

type Addon 

type Addon struct {
	API API
	// contains filtered or unexported fields
}

func NewAddon added in v0.2.0 

func NewAddon(name string, opts ...OptionArg) *Addon

func (*Addon) Emits added in v0.2.0 

func (addon *Addon) Emits(scope, key, description string, example *vars.Map)

func (*Addon) EmitsEvent added in v0.2.0 

func (addon *Addon) EmitsEvent(event Event)

func (*Addon) OnRegister added in v0.2.0 

func (addon *Addon) OnRegister(action ActionWithOptions)

func (*Addon) ProvidesCommand added in v0.2.0 

func (addon *Addon) ProvidesCommand(cmd *Command)

func (*Addon) ProvidesService added in v0.2.0 

func (addon *Addon) ProvidesService(svc *Service)

func (*Addon) Setting added in v0.2.0 

func (addon *Addon) Setting(key string, value any, description string, validator OptionValueValidator)

type AddonInfo 

type AddonInfo struct {
	Name        string
	Description string
	Version     version.Version
}

type Application 

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

func New added in v0.1.5 

func New(opts ...OptionArg) *Application

New returns new happy application instance. It panics if there is critical internal error or bug.

func (*Application) AddCommand added in v0.1.5 

func (a *Application) AddCommand(cmd *Command)

func (*Application) AddFlag added in v0.1.5 

func (a *Application) AddFlag(f varflag.Flag)

func (*Application) AfterAlways added in v0.1.5 

func (a *Application) AfterAlways(action Action)

func (*Application) AfterFailure added in v0.1.5 

func (a *Application) AfterFailure(action func(s *Session, err error) error)

func (*Application) AfterSuccess added in v0.1.5 

func (a *Application) AfterSuccess(action Action)

func (*Application) Before added in v0.1.5 

func (a *Application) Before(action ActionWithArgs)

func (*Application) Cron added in v0.1.5 

func (a *Application) Cron(setup func(schedule CronScheduler))

func (*Application) Do added in v0.1.5 

func (a *Application) Do(action ActionWithArgs)

func (*Application) Main 

func (a *Application) Main()

func (*Application) OnInstall added in v0.2.0 

func (a *Application) OnInstall(action Action)

func (*Application) OnMigrate added in v0.2.0 

func (a *Application) OnMigrate(ver string, up, down ActionMigrate)

func (*Application) OnTick added in v0.1.5 

func (a *Application) OnTick(action ActionTick)

func (*Application) OnTock added in v0.1.5 

func (a *Application) OnTock(action ActionTock)

func (*Application) RegisterService 

func (a *Application) RegisterService(svc *Service)

func (*Application) Setting added in v0.2.0 

func (a *Application) Setting(key string, value any, description string, validator OptionValueValidator)

func (*Application) WithAddons added in v0.1.5 

func (a *Application) WithAddons(addon ...*Addon)

type Args added in v0.1.5 

type Args interface {
	Arg(i uint) vars.Value
	ArgDefault(i uint, value any) (vars.Value, error)
	ArgVarDefault(i uint, key string, value any) (vars.Variable, error)
	Args() []vars.Value
	Flag(name string) varflag.Flag
}

type Assets added in v0.1.5 

type Assets interface{}

type Command 

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

func NewCommand added in v0.1.5 

func NewCommand(name string, options ...OptionArg) *Command

func (*Command) AddFlag added in v0.1.5 

func (c *Command) AddFlag(f varflag.Flag)

func (*Command) AddSubCommand added in v0.1.5 

func (c *Command) AddSubCommand(cmd *Command)

func (*Command) AfterAlways added in v0.1.5 

func (c *Command) AfterAlways(action func(s *Session) error)

func (*Command) AfterFailure added in v0.1.5 

func (c *Command) AfterFailure(action func(s *Session, err error) error)

func (*Command) AfterSuccess added in v0.1.5 

func (c *Command) AfterSuccess(action func(s *Session) error)

func (*Command) Before added in v0.1.5 

func (c *Command) Before(action ActionWithArgs)

func (*Command) Description 

func (c *Command) Description() string

func (*Command) Do added in v0.1.5 

func (c *Command) Do(action ActionWithArgs)

func (*Command) Err 

func (c *Command) Err() error

func (*Command) Name added in v0.1.5 

func (c *Command) Name() string

func (*Command) Usage added in v0.1.5 

func (c *Command) Usage() string

type Cron 

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

func (*Cron) Job added in v0.1.5 

func (cs *Cron) Job(expr string, cb Action)

func (*Cron) Start added in v0.1.5 

func (cs *Cron) Start() error

func (*Cron) Stop added in v0.1.5 

func (cs *Cron) Stop() error

type CronScheduler 

type CronScheduler interface {
	Job(expr string, cb Action)
}

type Engine 

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

type Event 

type Event interface {
	Key() string
	Scope() string
	Payload() *vars.Map
	Time() time.Time
}

func NewEvent added in v0.1.5 

func NewEvent(scope, key string, payload *vars.Map, err error) Event

func StartServicesEvent added in v0.1.5 

func StartServicesEvent(svcs ...string) Event

func StopServicesEvent added in v0.1.5 

func StopServicesEvent(svcs ...string) Event

type EventListener 

type EventListener interface {
	OnEvent(scope, key string, cb ActionWithEvent)
	OnAnyEvent(ActionWithEvent)
}

type Level added in v0.2.0 

type Level int8

type LogLevel added in v0.2.0 

type LogLevel int
const (
	// Happy Log Levels
	LogLevelSystemDebug    LogLevel = LogLevel(slog.LevelDebug - 1)
	LogLevelDebug          LogLevel = LogLevel(slog.LevelDebug)
	LogLevelInfo           LogLevel = LogLevel(slog.LevelInfo)
	LogLevelTask           LogLevel = LogLevel(slog.LevelInfo + 1)
	LogLevelOk             LogLevel = LogLevel(slog.LevelInfo + 2)
	LogLevelNotice         LogLevel = LogLevel(slog.LevelInfo + 3)
	LogLevelWarn           LogLevel = LogLevel(slog.LevelWarn)
	LogLevelNotImplemented LogLevel = LogLevel(slog.LevelWarn + 1)
	LogLevelDeprecated     LogLevel = LogLevel(slog.LevelWarn + 2)
	LogLevelIssue          LogLevel = LogLevel(slog.LevelWarn + 3)
	LogLevelError          LogLevel = LogLevel(slog.LevelError)
	LogLevelCritical       LogLevel = LogLevel(slog.LevelError + 1)
	LogLevelAlert          LogLevel = LogLevel(slog.LevelError + 2)
	LogLevelEmergency      LogLevel = LogLevel(slog.LevelError + 3)
	LogLevelBUG            LogLevel = 1000
	LogLevelAlways         LogLevel = math.MaxInt32
)

type OptionArg added in v0.2.0 

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

Option is used to define option and apply given key value to options.

func Option added in v0.1.5 

func Option(key string, value any) OptionArg

Opt creates option for given key value pair which can be applied to any Options set.

type OptionKind added in v0.1.5 

type OptionKind uint
const (
	ReadOnlyOption OptionKind
	SettingsOption
	ConfigOption
)

type OptionValueValidator added in v0.1.5 

type OptionValueValidator func(key string, val vars.Value) error

OptionValueValidator is callback function to validate given value, it recieves copy of value for validation. It MUST return error if validation fails, returned boolean indicates shoulkd that option be marked as radonly if validation succeeds.

type Options 

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

Options is general collection of settings attached to specific application component.

func NewOptions added in v0.1.5 

func NewOptions(name string, defaults []OptionArg) (*Options, error)

NewOptions returns new named options with optiona validator when provided.

func (*Options) Accepts added in v0.1.5 

func (opts *Options) Accepts(key string) bool

Accepts reports whether given option key is accepted by Options.

func (*Options) Get added in v0.1.5 

func (opts *Options) Get(key string) vars.Variable

func (*Options) Has added in v0.1.5 

func (opts *Options) Has(key string) bool

Has reports whether options has given key

func (*Options) Load added in v0.1.5 

func (opts *Options) Load(key string) (vars.Variable, bool)

func (*Options) Name added in v0.1.5 

func (opts *Options) Name() string

Name is name for this Option collection.

func (*Options) Set added in v0.1.5 

func (opts *Options) Set(key string, value any) error

type Service 

type Service struct {
	EventListener
	TickerFuncs
	// contains filtered or unexported fields
}

func NewService added in v0.1.5 

func NewService(name string, opts ...OptionArg) *Service

NewService cretes new draft service which you can compose before passing it to applciation or providing it from addon.

func (*Service) Cron added in v0.1.5 

func (s *Service) Cron(setupFunc func(schedule CronScheduler))

Cron scheduled cron jobs to run when the service is running.

func (*Service) OnAnyEvent added in v0.1.5 

func (s *Service) OnAnyEvent(cb ActionWithEvent)

OnAnyEvent called when any event is received.

func (*Service) OnEvent added in v0.1.5 

func (s *Service) OnEvent(scope, key string, cb ActionWithEvent)

OnEvent is called when a specific event is received.

func (*Service) OnInitialize 

func (s *Service) OnInitialize(action Action)

OnInitialize is called when app is preparing runtime and attaching services.

func (*Service) OnStart 

func (s *Service) OnStart(action Action)

OnStart is called when service is requested to be started. For instace when command is requiring this service or whenever service is required on runtime via sess.RequireService call.

Start can be called multiple times in case of service restarts. If you do not want to allow service restarts you should implement your logic in OnStop when it's called first time and check that state OnStart.

func (*Service) OnStop 

func (s *Service) OnStop(action Action)

OnStop is called when runtime request to stop the service is recieved.

func (*Service) OnTick added in v0.1.5 

func (s *Service) OnTick(action ActionTick)

OnTick when set will be called every application tick when service is in running state.

func (*Service) OnTock added in v0.1.5 

func (s *Service) OnTock(action ActionTock)

OnTock is called after every tick.

type ServiceInfo added in v0.1.5 

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

func (*ServiceInfo) Addr added in v0.1.5 

func (s *ServiceInfo) Addr() *address.Address

func (*ServiceInfo) Errs added in v0.1.5 

func (s *ServiceInfo) Errs() map[time.Time]error

func (*ServiceInfo) Failed added in v0.1.5 

func (s *ServiceInfo) Failed() bool

func (*ServiceInfo) Name added in v0.1.5 

func (s *ServiceInfo) Name() string

func (*ServiceInfo) Running added in v0.1.5 

func (s *ServiceInfo) Running() bool

func (*ServiceInfo) StartedAt added in v0.1.5 

func (s *ServiceInfo) StartedAt() time.Time

func (*ServiceInfo) StoppedAt added in v0.1.5 

func (s *ServiceInfo) StoppedAt() time.Time

type ServiceLoader 

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

func NewServiceLoader added in v0.1.5 

func NewServiceLoader(sess *Session, svcs ...string) *ServiceLoader

func (*ServiceLoader) Err 

func (sl *ServiceLoader) Err() error

func (*ServiceLoader) Load added in v0.1.5 

func (sl *ServiceLoader) Load() <-chan struct{}

type Session 

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

func (*Session) API added in v0.1.5 

func (s *Session) API(addonName string) (API, error)

func (*Session) Config added in v0.2.0 

func (s *Session) Config() *vars.Map

func (*Session) Deadline added in v0.1.5 

func (s *Session) Deadline() (deadline time.Time, ok bool)

Deadline returns the time when work done on behalf of this context should be canceled. Deadline returns ok==false when no deadline is set. Successive calls to Deadline return the same results.

func (*Session) Destroy 

func (s *Session) Destroy(err error)

func (*Session) Dispatch 

func (s *Session) Dispatch(ev Event)

func (*Session) Done added in v0.1.5 

func (s *Session) Done() <-chan struct{}

Done enables you to hook into chan to know when application exits however DO NOT use that for graceful shutdown actions. Use Application.AddExitFunc instead.

func (*Session) Err added in v0.1.5 

func (s *Session) Err() error

Err returns session error if any or nil If Done is not yet closed, Err returns nil. If Done is closed, Err returns a non-nil error explaining why: Canceled if the context was canceled or DeadlineExceeded if the context's deadline passed. After Err returns a non-nil error, successive calls to Err return the same error.

func (*Session) Get 

func (s *Session) Get(key string) vars.Variable

func (*Session) Has added in v0.1.5 

func (s *Session) Has(key string) bool

func (*Session) Log 

func (s *Session) Log() *hlog.Logger

func (*Session) Ready 

func (s *Session) Ready() <-chan struct{}

Ready returns channel which blocks until session considers application to be ready. It is ensured that Ready closes before root or command Do function is called.

func (*Session) RuntimeOpts added in v0.2.0 

func (s *Session) RuntimeOpts() *vars.Map

func (*Session) ServiceInfo added in v0.1.5 

func (s *Session) ServiceInfo(svcurl string) (*ServiceInfo, error)

func (*Session) Set added in v0.1.5 

func (s *Session) Set(key string, val any) error

func (*Session) Settings 

func (s *Session) Settings() *vars.Map

func (*Session) String added in v0.1.5 

func (s *Session) String() string

func (*Session) Value added in v0.1.5 

func (s *Session) Value(key any) any

Value returns the value associated with this context for key, or nil

func (*Session) X added in v0.2.4 

func (s *Session) X() bool

X Returns true when session expects that commands executed would be printed. To set this true run application with -x flag

type TickerFuncs 

type TickerFuncs interface {
	// OnTick enables you to define func body for operation set
	// to call in minimal timeframe until session is valid and
	// service is running.
	OnTick(ActionTick)

	// OnTock is helper called right after OnTick to separate
	// your primary operations and post prossesing logic.
	OnTock(ActionTick)
}

type Version 

type Version string

Source Files

View all Source files

Directories

Path Synopsis
examples
hello
kitchensink
pkg
address
Package address provides functions for working with "happy" addresses, which are URL-like strings that define the location of a resource in the "happy" system.
 Package address provides functions for working with "happy" addresses, which are URL-like strings that define the location of a resource in the "happy" system.
hlog
Package hlog is experimental logging packages which provides Custom handlerer for golang.org/x/exp/slog used within Happy.
 Package hlog is experimental logging packages which provides Custom handlerer for golang.org/x/exp/slog used within Happy.
hlog/internal/buffer
Package buffer provides a pool-allocated byte buffer.
 Package buffer provides a pool-allocated byte buffer.
varflag
Package varflag implements command-line flag parsing into compatible with package https://github.com/mkungla/happy/pkg/vars.
 Package varflag implements command-line flag parsing into compatible with package https://github.com/mkungla/happy/pkg/vars.
vars
Package vars provides the API to parse variables from various input formats/kinds to common key value pair.
 Package vars provides the API to parse variables from various input formats/kinds to common key value pair.
version
sdk
cli
Package cli provides utilities for happy command line interfaces.
 Package cli provides utilities for happy command line interfaces.
commands
Package commands provides commonly used commands which you can simply plug into your application.
 Package commands provides commonly used commands which you can simply plug into your application.
sarg
Package sarg is providing some common slog.Attr to use in your logging.
 Package sarg is providing some common slog.Attr to use in your logging.
testutils

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.