basics

type AutoStart interface {
	AutoStart()
}

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

type Catcher interface {
	// WithSignals declares a set of signals which can be caught with
	// application processing logics.
	//
	// An empty call means the default set will be applying:
	//
	//	signals = []os.Signal{os.Interrupt, os.Kill, syscall.SIGTERM, syscall.SIGHUP}
	//
	// These signals are hard-coded.
	WithSignals(signals ...os.Signal) Catcher
	// WithCloseHandlers gives the extra Peripheral's a chance
	// with safely shutting down.
	//
	// The better way is registering them with env.Closers().RegisterPeripheral(p).
	// All registered peripherals will be released/closed in the ending of Wait.
	WithCloseHandlers(onFinish ...Peripheral) Catcher
	// WithPrompt show a message before entering main loop.
	//
	// While many messages given, the final one will be used.
	// Use an empty call like WithPrompt() to request a default
	// prompt line.
	//
	// If you dislike printing anything, do Wait() directly
	// without WithPrompt call.
	WithPrompt(msg ...string) Catcher
	// WithOnSignalCaught setups handlers while any os signals caught by app.
	WithOnSignalCaught(cb ...OnSignalCaught) Catcher
	// WithOnLoop setups OnLooper handlers.
	//
	// Generally, the OnLooper handlers can be sent to Wait(...) while invoked.
	// But you can always register some looper(s) before Wait(a-main-looper).
	//
	// For example:
	//
	//	is.Signals().Catch().
	//	    WithOnLoop(redisStarter, etcdStarter, mongoStarter, dbStarter).
	//	    Wait(func(stopChan chan<- os.Signal, wgDone *sync.WaitGroup) {
	//	        // pop3server.Debug("entering looper's loop...")
	//
	//	        // setup handler: close catcher's waiting looper while 'pop3server' shut down
	//	        pop3server.WithOnShutdown(func(err error, ss net.Server) { wgShutdown.Done() })
	//
	//	        go func() {
	//	            err := pop3server.ListenAndServe(ctx, nil)
	//	            if err != nil {
	//	                pop3server.Error("server serve failed", "err", err)
	//	                panic(err)
	//	            }
	//	        }()
	//	    })
	WithOnLoop(cb ...OnLooper) Catcher
	// WithVerboseFn gives a change to log he catcher's internal state.
	WithVerboseFn(cb func(msg string, args ...any)) Catcher
	// Wait get the current thread blocked on reading 'done' channel
	// till an os signal break it.
	//
	// Each OnLooper must call wgDone.Done() to notify the looper was done.
	//
	// An optional way by sending os.Interrupt to stopChan could stop
	// catcher Wait loop programmatically, if necessary.
	Wait(stopperHandler OnLooper)
}

type Closable interface {
	// Close provides a closer to cleanup the peripheral gracefully
	Close()
}

type Closer interface {
	Close() error // = io.Closer
}

type Infrastructure interface {
	Peripheral

	// Open does initializing stuffs
	Open(ctx context.Context) (err error)
}

type OldInfra interface {
	Open() error
}

type OnLooper func(stopChan chan<- os.Signal, wgDone *sync.WaitGroup) // callback while get into waiting loop

type OnSignalCaught func(sig os.Signal, wgShutdown *sync.WaitGroup) // callback while an OS signal caught

type Peripheral interface {
	// Close provides a closer to cleanup the peripheral gracefully
	Close()
}