Documentation
¶
Overview ¶
Package echo is exposing a struct to handle the building and the management of the different tasks coming from the async package. This should be used in the main package only. This package provides a way to build an echo server easily (see https://echo.labstack.com), with a prometheus metrics endpoint and that relies on logrus for logging (see https://github.com/sirupsen/logrus).
Please favor the usage of [app](../app) package to run an echo web server.
Features ¶
- Build and run an echo server with a "/metrics" endpoint.
- Register an API.
- Register a Middleware.
- Serve HTTPS when the flags --web.tls-cert-file and --web.tls-key-file are set (see InitFlag). The certificate is reloaded when the files change. The other flags --web.tls-* configure the TLS versions, the cipher suites, the curves and the client certificates verification (mTLS).
Usage ¶
Instantiate a simple server task :
package my_package
import (
"github.com/perses/common/app"
"github.com/perses/common/echo"
"github.com/prometheus/client_golang/prometheus"
"github.com/sirupsen/logrus"
)
const (
// The address on which the server is listening.
addr = ":8080"
metricNamespace = "my_project"
)
func main() {
builder := echo.NewBuilder().
APIRegistration(echo.NewMetricsAPI(true, prometheus.DefaultRegisterer, prometheus.DefaultGatherer)).
MetricNamespace(metricNamespace)
// Without it, the address is the one of the flag --web.listen-address (see InitFlag), or ":8080".
builder.ListenAddress(addr)
serverTask, err := builder.Build()
if err != nil {
logrus.WithError(err).Fatal("unable to build the HTTP server")
}
// run the HTTP server until the process receives SIGINT or SIGTERM
app.NewRunner().WithTasks(serverTask).Start()
}
Index ¶
- func InitFlag()
- func InitTelemetryPathFlag()
- type Builder
- func (b *Builder) APIRegistration(api Register) *Builder
- func (b *Builder) ActivatePprof(activate bool) *Builder
- func (b *Builder) Build() (async.Task, error)
- func (b *Builder) BuildHandler() (http.Handler, error)
- func (b *Builder) GzipSkipper(skipper middleware.Skipper) *Builder
- func (b *Builder) IPExtractor(extractor echo.IPExtractor) *Builder
- func (b *Builder) IdleTimeout(timeout time.Duration) *Builder
- func (b *Builder) ListenAddress(addr string)
- func (b *Builder) MetricNamespace(namespace string) *Builder
- func (b *Builder) Middleware(mdw echo.MiddlewareFunc) *Builder
- func (b *Builder) OverrideDefaultMiddleware(override bool) *Builder
- func (b *Builder) PreMiddleware(mdw echo.MiddlewareFunc) *Builder
- func (b *Builder) PrometheusRegisterer(r prometheus.Registerer) *Builder
- func (b *Builder) ReadHeaderTimeout(timeout time.Duration) *Builder
- func (b *Builder) ReadTimeout(timeout time.Duration) *Builder
- func (b *Builder) SchemeExtractor(extractor echo.SchemeExtractor) *Builder
- func (b *Builder) WriteTimeout(timeout time.Duration) *Builder
- type Register
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InitTelemetryPathFlag ¶ added in v0.31.0
func InitTelemetryPathFlag()
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
func NewBuilder ¶
func NewBuilder() *Builder
func (*Builder) APIRegistration ¶
APIRegistration must be used to register an HTTP API.
func (*Builder) ActivatePprof ¶ added in v0.7.0
ActivatePprof exposes the pprof endpoints under /debug/pprof. It is disabled by default. These endpoints are not authenticated and expose sensitive information about the process (like the command line arguments, the memory or the goroutine stacks), so only activate them when the server is not reachable by untrusted clients.
Note: this package imports net/http/pprof, which registers the pprof endpoints on http.DefaultServeMux. So, whatever this option is, never serve http.DefaultServeMux (for example with http.ListenAndServe(addr, nil)) to untrusted clients.
func (*Builder) BuildHandler ¶ added in v0.18.0
BuildHandler is creating an http Handler based on the different configuration and attribute set. It can be useful to have it when you want to use the method httptest.NewServer for testing purpose, and you want to have the same setup as the actual http server.
func (*Builder) GzipSkipper ¶ added in v0.21.0
func (b *Builder) GzipSkipper(skipper middleware.Skipper) *Builder
GzipSkipper can be used to provide a function that will tell when to skip the gzip compression. It can be used to avoid gzip to certain URL(s). The Gzip compression is activated on every URL registered in echo when using the default middleware. If you don't use the default middleware, then there is no point of using this method.
func (*Builder) IPExtractor ¶ added in v0.33.0
func (b *Builder) IPExtractor(extractor echo.IPExtractor) *Builder
IPExtractor sets how echo.Context.RealIP gets the IP address of the client. By default, the address of the direct peer (http.Request.RemoteAddr) is used, as the headers X-Forwarded-For and X-Real-IP can be spoofed by any client. When the server is behind proxies, use an extractor that only trusts the headers set by them, for example:
builder.IPExtractor(echo.ExtractIPFromXFFHeader(echo.TrustIPRange(proxyNetwork)))
func (*Builder) IdleTimeout ¶ added in v0.32.0
IdleTimeout sets the maximum amount of time to wait for the next request when keep-alives are enabled (see http.Server.IdleTimeout). The default value is 2m, whatever the ReadTimeout is. A negative value disables the timeout.
func (*Builder) ListenAddress ¶ added in v0.31.0
func (*Builder) MetricNamespace ¶
MetricNamespace is modifying the namespace that will be used next ot prefix every metrics exposed
func (*Builder) Middleware ¶
func (b *Builder) Middleware(mdw echo.MiddlewareFunc) *Builder
Middleware is adding the provided middleware into the Builder Order matters, add the middleware in the order you would like to see them started.
func (*Builder) OverrideDefaultMiddleware ¶
OverrideDefaultMiddleware is setting a flag that will tell if the Builder needs to override the default list of middleware considered by the one provided by the method Middleware. In case the flag is set at false, then the middleware provided by the user will be appended to the default list. Note that the default list is always executed at the beginning (a.k.a, the default middleware will be executed before yours).
func (*Builder) PreMiddleware ¶ added in v0.26.0
func (b *Builder) PreMiddleware(mdw echo.MiddlewareFunc) *Builder
PreMiddleware is adding the provided middleware into the Builder. Each mdw added here, will be executed before the router.
func (*Builder) PrometheusRegisterer ¶ added in v0.19.0
func (b *Builder) PrometheusRegisterer(r prometheus.Registerer) *Builder
PrometheusRegisterer will set a new metric registry for Prometheus, so it won't use the default one. That can be useful for testing purpose since you can't register in the same go instance the same metrics multiple times.
func (*Builder) ReadHeaderTimeout ¶ added in v0.32.0
ReadHeaderTimeout sets the amount of time allowed to read the request headers (see http.Server.ReadHeaderTimeout). It protects the server against clients sending the headers slowly to keep the connections open (Slowloris attack). The default value is 10s, or the ReadTimeout if it is shorter. A negative value disables the timeout.
func (*Builder) ReadTimeout ¶ added in v0.32.0
ReadTimeout sets the maximum duration to read the entire request, including the body (see http.Server.ReadTimeout). There is no timeout by default, as a request body can be large.
func (*Builder) SchemeExtractor ¶ added in v0.33.0
func (b *Builder) SchemeExtractor(extractor echo.SchemeExtractor) *Builder
SchemeExtractor sets how echo.Context.Scheme gets the scheme (http or https) used by the client. By default, the headers like X-Forwarded-Proto are only trusted when the request comes from a loopback, link-local or private network address. When the server is behind a proxy with another address (like a CDN or a cloud load balancer), use an extractor that trusts it, for example:
builder.SchemeExtractor(echo.ExtractSchemeFromHeaders(echo.TrustIPRange(proxyNetwork)))
func (*Builder) WriteTimeout ¶ added in v0.32.0
WriteTimeout sets the maximum duration before timing out the writes of the response (see http.Server.WriteTimeout). There is no timeout by default, as some responses can take a long time (long queries, streaming, CPU profiles, etc.).
type Register ¶
func NewMetricsAPI ¶
func NewMetricsAPI(disableCompression bool, r prometheus.Registerer, gatherer prometheus.Gatherer) Register
NewMetricsAPI returns the API exposing the metrics collected by the gatherer, under the path set by the flag --web.telemetry-path ("/metrics" by default, see InitTelemetryPathFlag). The metrics about the requests of this endpoint are registered with the registerer (the default Prometheus registerer if nil). Set disableCompression to true when the responses are already compressed by a middleware, like the gzip one used by default by the Builder.