[Nexucis]

Upgrade the echo package to echo v5 (v5.4.4). echo v4 only receives bug fixes until 2026-12-31 and security fixes until 2027-12-31.

Stacked on #372 (the builder tests are fixed there). This is the first step of the upgrade of Perses to echo v5.

Breaking changes / how to migrate

• The Builder methods and the --web.* flags don't change, but the types they use are now the echo v5 ones:

  • Register.RegisterRoute(*echo.Echo);
  • Builder.Middleware / PreMiddleware(echo.MiddlewareFunc);
  • Builder.GzipSkipper(middleware.Skipper), which is now a func(*echo.Context) bool.
    In your code: replace echo.Context with *echo.Context and labstack/echo/v4 with labstack/echo/v5, then see API_CHANGES_V5.md (echo.Map is removed, Context.Response() returns an http.ResponseWriter, etc.).

• middleware.Logger / LoggerWithConfig and Metrics.ProcessHTTPRequest return the error of the next handler instead of handling it with c.Error (which doesn't exist in v5). The error is handled once, by the central error handler. The status logged and counted is resolved from the error, so it is the same as before.

• With the default middlewares, the panics are now logged with their stack trace and counted in the access logs and in the metrics, with the status of the response sent: 500, or the status carried by the value of the panic (like panic(echo.NewHTTPError(...))). Before, they were skipped by both. Like before, the panics with http.ErrAbortHandler (used to abort a response, like httputil.ReverseProxy does) are not recovered, so they are still skipped.

• echo v5 changed the defaults of Context.RealIP() and Context.Scheme(), as the forwarding headers can be spoofed by any client:

  • RealIP() returns the address of the peer instead of trusting the X-Forwarded-For / X-Real-IP headers;
  • Scheme() only trusts X-Forwarded-Proto (and the similar headers) when the request comes from a loopback, link-local or private address.

  Behind proxies, use the new Builder.IPExtractor / Builder.SchemeExtractor to trust them, like builder.IPExtractor(echo.ExtractIPFromXFFHeader(echo.TrustIPRange(proxyNetwork))).

Changes

• Lifecycle:
  • The server is started with echo.StartConfig. It gracefully shuts the server down (30s) when the context is canceled, which replaces the goroutine and channel of Execute, and the shutdown in Finalize (which now only returns the error of the graceful shutdown).
  • The startup errors are still returned, with the same message and exit code.
  • echo v5 removed Echo.Server and Echo.TLSServer, so the timeouts are set in BeforeServeFunc. They are set even when they are zero, because echo v5 sets a default ReadTimeout of 30s, which would cut the long requests. The timeouts themselves don't change.
• TLS: the certificate reloader is passed through StartConfig.TLSConfig. StartConfig.StartTLS is not used, because it loads the certificate only once and reads the paths from the working directory.
• Middleware order:
  • The defaults are now Logger → Metrics → Recover → Gzip (before: Recover → Logger → Gzip → Metrics).
  • echo v5's Recover no longer logs the panic: it returns it as an error, logged with its stack by the new central error handler.
  • The central error handler only logs the errors without an HTTP status (panics, unexpected errors). It then renders the same JSON as before ({"message": ...}), without exposing the internal error.
  • An unexpected error is logged as a warning once the response is sent (it cannot change the status anymore), and at the debug level when it is a cancellation caused by the client that went away. The context of the request is saved as received by the server, before any middleware, as the middlewares can replace it (like middleware.ContextTimeout, which cancels its own context).
  • The access log, the metrics and the error log use the method and the escaped path of the request as received, even if a handler rewrites them (like a reverse proxy).
  • Only the stack of the goroutine that panicked is logged: getting the stacks of all the goroutines stops the world.
• Logs: echo v5 logs with log/slog (JSON on stdout by default), so echo is given a slog handler writing with logrus: all its logs have the same format, level and output as the other logs.
  • The address listened is logged with logrus, as http(s) server started on <address> (still hidden with --web.hide-port). echo v4 printed ⇨ http(s) server started on <address> on stdout: the Perses docs showing this line (CONTRIBUTING.md, docs/installation/from-source.md and docs/installation/in-a-container.md) will need an update when Perses is upgraded.
  • The errors of the http.Server are logged with logrus. Most of them are caused by the clients (like the TLS handshake errors and the HTTP/2 protocol errors), so they are logged as warnings, as any client can trigger them. Only the defects of the server (like a panic not recovered by a middleware) are logged as errors.
  • With --log.method-trace, the logs of echo and the errors of the http.Server report the code that logged them as caller (instead of the bridge to logrus). As logrus has no way to read this setting without racing with SetReportCaller, it is read when the server is built: logrus must be configured before, like app.Runner does.
  • Like before, a graceful shutdown timeout is returned by Finalize (server shutdown not properly: ...), so the task reports the failure.
• API:
  • Builder.IPExtractor and Builder.SchemeExtractor configure how Context.RealIP() and Context.Scheme() trust the forwarding headers.
  • middleware.RequestMethod and middleware.RequestPath return the method and the escaped path of the request as logged by the Logger middleware.
• Dependencies: labstack/gommon, valyala/fasttemplate, go-colorable, go-isatty, bytebufferpool and the indirect golang.org/x/crypto, x/net, x/text are removed.

Validation

• make checkformat: passed
• go test -race -count=1 ./...: passed
• golangci-lint run ./...: 0 issues
• New tests:
  • a panic, an unexpected error, HTTP errors and an unknown route → response, access log, metrics and error log;
  • the timeouts override echo's default;
  • the http.Server errors and the listen address are logged with logrus;
  • the shutdown timeout is returned by Finalize;
  • the logs of echo are written with logrus, and the slog handler (levels, attributes, groups);
  • the levels of the unexpected errors (after the response is sent, after the client went away) and of the errors of the http.Server;
  • the caller of the logs of echo and of the errors of the http.Server, and --web.hide-port with a running server;
  • an unexpected error with a middleware canceling its context, a cancellation by the server, and an error not caused by the client that went away;
  • the method rewritten by a handler, and the status and the method logged by the Logger middleware (errors, HTTP errors, panics);
  • the IP and scheme extractors;
  • a panic carrying an HTTP status is logged with its stack.

[Copilot]

🟡 Changes recommended

Graceful shutdown timeouts are not propagated to the task runner, falsely reporting success, while recovered panics carrying HTTP statuses can bypass error and stack-trace logging.

2 open issues

• Propagate graceful shutdown timeout errors from Execute · New
• Status filter skips logging recovered HTTP-error panics · New

What changed in this PR

Upgrades the shared HTTP server package to Echo v5.4.4 as the first step in Perses’ migration. Builder methods and web flags remain unchanged, while their exposed Echo types change.

Changes:

• Replace Echo v4 dependencies and context types with v5 equivalents.
• Adopt StartConfig for server lifecycle and TLS configuration.
• Centralize error handling, update logging and metrics middleware, and add regression tests.

File	Description
go.sum	Update checksums and remove obsolete dependencies.
go.mod	Require Echo v5 and prune unused indirect dependencies.
echo/​timeout_test.go	Check timeout settings stored on the server.
echo/​server.go	Migrate lifecycle, TLS, middleware ordering, and error handling.
echo/​server_test.go	Switch the test import to Echo v5.
echo/​middleware/​metrics.go	Resolve response status and propagate handler errors.
echo/​middleware/​logger.go	Resolve logged status and return errors for central handling.
echo/​middleware/​logger_test.go	Update handlers to use v5 context pointers.
echo/​metrics.go	Switch metrics route registration to Echo v5.
echo/​logging_test.go	Test timeout configuration, server logging, and address visibility.
echo/​error_handler_test.go	Test error responses, panic diagnostics, access logs, and metrics.
echo/​builder_test.go	Update builder tests to use Echo v5 types.

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

The error handler reads the path after handlers may rewrite it, causing error and access logs for the same failure to report different paths.

1 open issue

• Error logs should use the original request path · New

2 resolved since last review

• Propagate graceful shutdown timeout errors from Execute
• Status filter skips logging recovered HTTP-error panics

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

Human judgment is needed to weigh unpublished documentation nits concerning startup logging and HTTP/2 cipher support.

1 open issue

• Error logs should use the original request path

_{Review effort: Max}

[Nexucis]

reviewed by myself, I am moving forward on that topic.