app

package
v0.34.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 14 Imported by: 5

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func InitFlag added in v0.31.0

func InitFlag()

InitFlag is initializing the flag for logrus config and for the echo server This is an opinionated function, use it only if you are using logrus and echo server.

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()
}

func (*Runner) HTTPServerBuilder

func (r *Runner) HTTPServerBuilder() *echo.Builder

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

func (r *Runner) SetBanner(banner string) *Runner

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

func (r *Runner) SetTimeout(timeout time.Duration) *Runner

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

func (r *Runner) WithCronTasks(cronSchedule string, t ...any) *Runner

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

func (r *Runner) WithDefaultHTTPServer(metricNamespace string) *Runner

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

func (r *Runner) WithDefaultLogrusBuilder() *Runner

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.

func (*Runner) WithTasks

func (r *Runner) WithTasks(t ...any) *Runner

WithTasks is the way to add different tasks that will be executed asynchronously. If a task ended with no error, it won't necessarily stop the whole application. It will mainly depend on how the task is managing the context passed in parameter.

func (*Runner) WithTimerTasks added in v0.23.1

func (r *Runner) WithTimerTasks(duration time.Duration, t ...any) *Runner

WithTimerTasks is the way to add different tasks that will be executed periodically at the frequency defined with the duration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL