Documentation
¶
Overview ¶
Package app is exposing a struct to handle the building and the management of the different tasks coming from the package async. This should be used in the main package only.
A quite straightforward usage of this package is when you are implementing an HTTP API and want to expose it. In that case you can use the following example (see ExampleNewRunner): register the flags with InitFlag and parse them, create the Runner with WithDefaultLogrusBuilder and WithDefaultHTTPServer, register your API on HTTPServerBuilder, then call Start.
You can also add custom tasks to the runner using WithTasks, WithTimerTasks and WithCronTasks.
Index ¶
- func InitFlag()
- type Runner
- func (r *Runner) HTTPServerBuilder() *echo.Builder
- func (r *Runner) LogrusBuilder() *commonLogrus.Builder
- func (r *Runner) OTeLProviderBuilder() *commonOtel.Builder
- func (r *Runner) SetBanner(banner string) *Runner
- func (r *Runner) SetTimeout(timeout time.Duration) *Runner
- func (r *Runner) Start()
- func (r *Runner) WithCronTasks(cronSchedule string, t ...any) *Runner
- func (r *Runner) WithDefaultHTTPServer(metricNamespace string) *Runner
- func (r *Runner) WithDefaultHTTPServerAndPrometheusRegisterer(metricNamespace string, registerer prometheus.Registerer, ...) *Runner
- func (r *Runner) WithDefaultLogrusBuilder() *Runner
- func (r *Runner) WithTaskHelpers(t ...taskhelper.Helper) *Runner
- func (r *Runner) WithTasks(t ...any) *Runner
- func (r *Runner) WithTimerTasks(duration time.Duration, t ...any) *Runner
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner starts the tasks of an application (like the HTTP server and the timer or cron tasks), and stops them gracefully when one of them stops the application or when the process receives SIGINT or SIGTERM.
func NewRunner ¶
func NewRunner() *Runner
NewRunner creates a Runner that waits up to 30s for the tasks to stop when the application stops (see SetTimeout).
Example ¶
This example is only compiled, because Start blocks until the application is stopped.
package main
import (
"context"
"flag"
"time"
"github.com/labstack/echo/v5"
"github.com/perses/common/app"
)
type nightlyTask struct{}
func (t *nightlyTask) String() string {
return "nightly task"
}
func (t *nightlyTask) Execute(_ context.Context, _ context.CancelFunc) error {
return nil
}
type api struct{}
func (a *api) RegisterRoute(e *echo.Echo) {
e.GET("/api/v1/hello", func(c *echo.Context) error {
return c.String(200, "hello")
})
}
// This example is only compiled, because Start blocks until the application is stopped.
func main() {
// register the flags configuring the logs and the HTTP server, then parse them
app.InitFlag()
flag.Parse()
runner := app.NewRunner().
WithDefaultLogrusBuilder().
WithDefaultHTTPServer("your_api_name").
WithTimerTasks(30*time.Second, &nightlyTask{}).
WithCronTasks("0 2 * * *", &nightlyTask{})
// register your api
runner.HTTPServerBuilder().APIRegistration(&api{})
// start the application
runner.Start()
}
Output:
func (*Runner) HTTPServerBuilder ¶
HTTPServerBuilder returns the Builder of the HTTP server, to register your APIs and your middlewares for example. If no HTTP server has been created with WithDefaultHTTPServer or WithDefaultHTTPServerAndPrometheusRegisterer, it creates one without any API (not even the metrics one). Once the Builder exists, the runner builds and starts the HTTP server, so at least one API must be registered on it, otherwise the runner fails to start.
func (*Runner) LogrusBuilder ¶ added in v0.31.0
func (r *Runner) LogrusBuilder() *commonLogrus.Builder
LogrusBuilder returns the Builder of the logrus configuration, and creates it if it doesn't exist yet. The global logrus logger is configured with it when the runner starts. The settings that are not set on the Builder come from the flags (see logrus.InitFlag).
func (*Runner) OTeLProviderBuilder ¶ added in v0.15.0
func (r *Runner) OTeLProviderBuilder() *commonOtel.Builder
OTeLProviderBuilder returns the Builder of the OpenTelemetry tracer provider, and creates it if it doesn't exist yet. Once this Builder exists, the runner builds the provider with it, registers it globally when it starts, and shuts it down when it stops. A resource or a provider must be set on the Builder, otherwise the runner fails to start.
func (*Runner) SetBanner ¶ added in v0.4.0
SetBanner is setting a string (ideally the logo of the project) that would be printed when the runner is started. Additionally, you can also print the Version, the BuildTime and the Commit. You just have to add '%s' in your banner where you want to print each information (one '%s' per additional information). If set, then the main header won't be printed. The main header is printing the Version, the Commit and the BuildTime.
func (*Runner) SetTimeout ¶
SetTimeout is setting the time to wait before killing the application once it received a cancellation order.
func (*Runner) Start ¶
func (r *Runner) Start()
Start will start the application. It is a blocking method and will give back the end once every tasks handled are done. If the application is stopped by a task that failed (like the HTTP server that cannot listen on its address), the process exits with the status code 1 once every task is stopped. The application is gracefully stopped when it receives SIGINT or SIGTERM. If another one is received while it is stopping (like a second Ctrl+C), the process is killed right away.
func (*Runner) WithCronTasks ¶
WithCronTasks is the way to add different tasks that will be executed according to the cron schedule. See taskhelper.NewCron for the syntax of the schedule.
func (*Runner) WithDefaultHTTPServer ¶
WithDefaultHTTPServer is here to create a default HTTP server with already the metrics API setup. The metrics are registered in and gathered from the default Prometheus registry. To use another registry, use WithDefaultHTTPServerAndPrometheusRegisterer.
func (*Runner) WithDefaultHTTPServerAndPrometheusRegisterer ¶ added in v0.24.0
func (r *Runner) WithDefaultHTTPServerAndPrometheusRegisterer(metricNamespace string, registerer prometheus.Registerer, gatherer prometheus.Gatherer) *Runner
WithDefaultHTTPServerAndPrometheusRegisterer is here to create a default HTTP server with already the metrics API setup. Usually you will use it as follows:
promRegistry := prometheus.NewRegistry() app.NewRunner().WithDefaultHTTPServerAndPrometheusRegisterer(metricNamespace, promRegistry, promRegistry)
func (*Runner) WithDefaultLogrusBuilder ¶ added in v0.31.0
WithDefaultLogrusBuilder is just initializing the logrus builder without returning it. Use this one if you are configuring logrus through the flag. Then don't forget to call logrus.InitFlag before parsing the flag. If you want to configure manually logrus, call LogrusBuilder instead.
func (*Runner) WithTaskHelpers ¶ added in v0.5.0
func (r *Runner) WithTaskHelpers(t ...taskhelper.Helper) *Runner
WithTaskHelpers is the way to add tasks already wrapped in a taskhelper.Helper. They are started with the other tasks.