Proposal for v5 and community feedback

[aldas]

Dear community member, this is a proposal for Echo v5, we seek your feedback of these proposed changes.

---

NOTE: non-constructive feedback will be hidden/deleted. Negative criticism is welcome if it comes with arguments. Be
professional, respect others time reading/deciphering your point of view, this is not Twitter or any other informal chatroom.

Be professional

---

v5 will be mostly maintenance release to clean up APIs (remove and/or move things around, fix API inconsistencies,
fix internally maintenance pain-points, prepare more extendable router). Minimal amount of fancy new features or
performance gains/regressions - just annoying API changes for the unprepared :)

If you are not starting with new application you do not need to upgrade to v5.

We support both v4 and v5 for some time (ala 1year) so current users would not be affected by our
"busywork" with APIs. From maintainers perspective it seems doable as we do not have (huge/many) changes often.
And from library/framework user perspective it should be positive as you are not forced/rushed to upgrade without
actual benefits for you.

Schedule:

• TBA

Update 06.01.2022:

• Instead of release v5 on first week we will postpone it and tag v5.0.0-alpha at the end of January along with echo-contrib@v5.0.0-alpha. This is mainly because we did not prepare documentation and there have been couple of small changes. As this release does not bring much groundbreaking new things we are not in that hurry to release half-baked product.

---

Branch for v5 proposal: https://github.com/labstack/echo/tree/v5_proposal_public

NOTE: there will be force pushes, squashing of commits etc in that branch before the release.

---

TLDR: noticeable/biggest breaking changes

• (Context interface) removed method Logger() - we encourage you to use your favourite Logging libraries (Log/Logrus/Zap/Zerolog etc).

  Your options are now:

  • create middleware that adds your logger instance to Context with c.Store("logger", myLogger) and in handler
    access it logger := c.Get("logger").(*zerolog.Logger)
  • create "controller"like structs with dependency injected logger and have your handlers as methods

  func main() {
    e := echo.New()
    users := users{log: log.New(os.Stdout, "userCntrl", 0)}
    e.GET("/", users.welcome)
  }
  
  type users struct {
    log *log.Logger
  }
  
  func (u *users) welcome(c echo.Context) error {
    u.log.Println("welcome called")
    return c.String(http.StatusOK, "Hello, World!")
  }

  • use globals? (you can but do not do it)

• (Context interface) renamed method Param("id") to PathParam("id")
  Reasoning for that is: Method name Param is too ambiguous. Context interface already has methods like:

  QueryParam(name string) string
  FormValue(name string) string
  

  which explicitly describe where that *Param or *Value data comes/originates from. Name PathParam is explicit as those methods.

    e.POST("/product/:id", func(c echo.Context) error {
      lang := c.QueryParam("lang")
      name := c.FormValue("name")
      id := c.PathParam("id") // <-- now
      // id := c.Param("id")  // <-- previously
      return c.String(http.StatusOK, "Hello, World!")
    })

• (echo instance) moved all fields,methods related running of the http(s) server to different struct

• (echo instance) methods like e.GET(...) now returns immutable Route object. Route name can not be changed with that object anymore.

	// Previously naming of route was done with:
	e.GET("/users/:id", func(c echo.Context) error {
		return c.String(http.StatusOK, "OK")
	}).Name = "get-user"

	// now route name must be provided before/when route is added
	e.AddRoute(echo.Route{
		Method: http.MethodGet,
		Path:   "/users/:id",
		Handler: func(c echo.Context) error {
			return c.String(http.StatusOK, "OK")
		},
		Name: "get-user",
	})
	
	// `e.GET` returns now `RouteInfo`
	// `e.AddRoute` returns `RouteInfo, error`. RouteInfo is immutable.

  r, _ := e.Router().Routes().FindByMethodPath(http.MethodGet, "/users/:id")
  log.Println(r.Name()) // prints "get-user"

• (echo instance/middleware) function fields that have echo.Context as an argument have it as a first argument. Most notable is
  default error handler signature change:

  type HTTPErrorHandler func(err error, c Context) // <-- previously
  type HTTPErrorHandler func(c Context, err error) // <-- now

• (middleware) Timeout middleware will be removed - this middleware has data races, unnecessarily complex for benefits it brings
  and prone to be misused by users for use-cases where there are better/proper solutions.
  • If you want to execute business logic in handler asynchronously and return early (or when deadline is met) then just
    spin a coroutine in your handler and wait some time it to finish.
  • If you want to limit handler execution time then replace request context with context with timeout. Or rely on
    basic functionality to timeout proxied requests that Nginx/Apache/HaProxy etc already have.

---

Undecided, but worth the discussion:

• should we move all middlewares out of core to echo-middlewares package (one package for all) and version it from
  5.0.0 and leave out semantic versioning for that repo. Breaking changes are done in minor versions but not in
  patch versions. so all Echo v5 stuff would be ala echo-middlewares@v5.15.0. Some people would probably complain
  about unnecessary dependencies (same as echo-contrib) but Go modules does not actually compile module dependencies
  that are not used in your app and as of Go 1.17 dependencies that are not used are not even downloaded.
  So if there are external dependencies in that repo it should be ok. Allowing breaking changes in minor version is
  a little bit more convenient for user as he/she does not need to update packages on version
  bump (with go mod major version bump means new package import paths but minor version does not generate new path).

As Go 1.18 probably brings us generics which maybe use for Echo, we may have soon v6. So middleware relocation, if it seems
reasonable idea for the community, could be held back to that version.

---

General

• Bumped minimal Go version to 1.16 as fs.FS filesystem was introduced in that version as we use it for field
  echo.Filesystem that is used in methods e.File() and e.Static().

• Changed function fields that have echo.Context as an argument have it as a first argument. Most notable is
  default error handler signature change:

  type HTTPErrorHandler func(err error, c Context) // <-- previously
  type HTTPErrorHandler func(c Context, err error) // <-- now

  This is to normalize of callback function are defined. Previously Context was sometimes first sometimes at some other
  place.

• changed how type definitions are written from

  type (
    // Binder is the interface that wraps the Bind method.
    Binder interface {
      Bind(i interface{}, c Context) error
    }
  )

  to

  // Binder is the interface that wraps the Bind method.
  type Binder interface {
    Bind(c Context, i interface{}) error
  }

  This is because in that way it is easier to copy/paste Echo code when there are multiple definitions in one () block.
  From personal perspective: have done this because it was quite inconvenient to paste code for echox documentation.

Error handling

• Removed echo.HTTPError.SetInternal() method as it allowed to mutate global errors. Use HTTPError.WithInternal(err) instead.
• Added: echo.NewHTTPErrorWithInternal() to help creating errors with internal error.
• Changed echo.NotFoundHandler to private. Replaced placed where it was called with actual error. 404 (echo.ErrNotFound) should now be handled in global error handler.
• Changed echo.MethodNotAllowedHandler to private. Replaced placed where it was called with actual error. 405 (echo.ErrMethodNotAllowed) should now be handled in global error handler.
• Changed default error handler signature:

  type HTTPErrorHandler func(err error, c echo.Context) // <-- previously
  type HTTPErrorHandler func(c echo.Context, err error) // <-- now

echo.Echo struct

• Added field Echo.NewContextFunc func(pathParamAllocSize int) EditableContext function called to create new context instance. Allows creation of custom context implementations

• Added field Echo.Filesystem fs.FS is used by context.File(), echo.File() and echo.Static() to serve files from given filesystem (embedded or not). Defaults to os.DirFS(".") current directory.

• Removed field Echo.ListenerNetwork. Now part of echo.StartConfig as field ListenerNetwork

• Removed field Echo.HidePort. Now part of echo.StartConfig as field HidePort

• Removed field Echo.HideBanner. Now part of echo.StartConfig as field HideBanner

• Removed field Echo.DisableHTTP2. Now part of echo.StartConfig as field DisableHTTP2

• Removed field Echo.AutoTLSManager. AutoTLS is now started with echo.StartConfig.StartAutoTLS(). Can not be directly passed anymore. Create custom http.Server to have same functionality.

• Removed field Echo.TLSListener. Now part of echo.StartConfig. TLS can be configured with StartConfig.TLSConfigFunc callback

• Removed field Echo.Listener. Replaced with echo.StartConfig implementation. Can not be directly passed anymore. Create custom http.Server to have same functionality.

• Removed field Echo.TLSServer. Replaced with echo.StartConfig implementation. Can not be directly passed anymore. Create custom http.Server to have same functionality.

• Removed field Echo.Server. Replaced with echo.StartConfig implementation. Can not be directly passed anymore.

• Removed field Echo.notFoundHandler.

• Removed field Echo.colorer. No colored logger messages anymore. Removed as it is not useful in production env.

• Removed field Echo.StdLogger . Now part of echo.StartConfig

• Removed field Echo.startupMutex. Removed as server functionality is in echo.StartConfig struct now.

• Changed Echo.Router() returns now Router interface instead of *Router struct.

• Changed Echo.Routers() returns now map[string]Router instead of map[string]*Router.

• Added Echo.RouterFor(host string) Router to get vhost Router instance by its hostname.

• Added Echo.ResetRouterCreator(creator func(e *Echo) Router) to allow users set custom callback to use/create custom
  Router implementations. This allows you to change router that Echo is using.

• Moved Echo method Echo.DefaultHTTPErrorHandler(err error, c Context) to be separate function that is created with DefaultHTTPErrorHandler(exposeError bool) HTTPErrorHandler function. Note functionility that e.Debug provided is now available with exposeError bool argument.

• Changed Echo route adding method signatures to return immutable RouteInfo instead of reference to added route.
  Now only way to add route with predefined name is:

    route := echo.Route{
      Method:      http.MethodGet,
      Path:        "/users",
      Handler:     handler,
      Middlewares: []echo.MiddlewareFunc{middleware.Logger()},
      Name:        "my_users",
    }
    e.AddRoute(route) // ignore returned values
    ri, err := e.AddRoute(route) // or check for error

  • Echo.CONNECT returns now RouteInfo instead of *Route. Now: CONNECT(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.DELETE returns now RouteInfo instead of *Route. Now: DELETE(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.GET returns now RouteInfo instead of *Route. Now: GET(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.HEAD returns now RouteInfo instead of *Route. Now: HEAD(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.OPTIONS returns now RouteInfo instead of *Route. Now: OPTIONS(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.PATCH returns now RouteInfo instead of *Route. Now: PATCH(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.POST returns now RouteInfo instead of *Route. Now: POST(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.PUT returns now RouteInfo instead of *Route. Now: PUT(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.TRACE returns now RouteInfo instead of *Route. Now: TRACE(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.Any returns now []RouteInfo instead of []*Route. Now: Any(path string, h HandlerFunc, m ...MiddlewareFunc) []RouteInfo
  • Echo.Match returns now []RouteInfo instead of []*Route. Now: Match(path string, h HandlerFunc, m ...MiddlewareFunc) []RouteInfo
  • Echo.File returns now RouteInfo instead of *Route. Now: File(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Echo.Add returns now RouteInfo instead of *Route. Now: Add(method, path string, handler HandlerFunc, middleware ...MiddlewareFunc) RouteInfo

• Added Echo.AddRoute(route Routable) (RouteInfo, error) which allows adding route using echo.Route structure or Routable interface
  and to handle invalid routes with error instead of panic as other method do.

• Changed Echo.Static returns RouteInfo and change to accept middlewares as arguments. NOW: Static(prefix, root string, middleware ...MiddlewareFunc) RouteInfo

• Added echo.StaticDirectoryHandler(root string, disablePathUnescaping bool) to allow creating custom static assets serving paths.
  These two are identical:

  e.Static("/assets", "./", middleware.Logger())
  e.GET("/assets*", echo.StaticDirectoryHandler("./", false), middleware.Logger())

  Handler uses echo.Context.File() to serve files and therefore echo.Echo.Filesystem field is used.

• Removed Echo.Routes() []*Route. Equivalent is e.Router().Routes()

• Removed Echo.Reverse(name string, params ...interface{}) string. Equivalent is e.Router().Routes().Reverse("routeName", 123)

• Removed Echo.URI(handler HandlerFunc, params ...interface{}) string. Equivalent same as Reverse

• Removed Echo.URL(h HandlerFunc, params ...interface{}) string. Equivalent same as Reverse

All method related to starting http.Server have been moved new implementation echo.StartConfig struct

• Removed Echo.Shutdown(ctx stdContext.Context) error. When using StartConfig started server it can be shutdown with StartConfig.GracefulShutdown struct that can have context.Context which closing will close server.

• Removed Echo.Close() error. When using StartConfig started server it can be shutdown with StartConfig.GracefulShutdown struct that can have context.Context which closing will close server.

• Removed Echo.TLSListenerAddr() net.Addr. To get listener address when StartConfig is started use callback StartConfig.ListenerAddrFunc func(addr net.Addr) which allows to access listener before server is started.

• Removed Echo.ListenerAddr() net.Addr. To get listener address when StartConfig is started use callback StartConfig.ListenerAddrFunc func(addr net.Addr) which allows to access listener before server is started.

• Removed Echo.StartServer(s *http.Server) (err error). Equivalent would be using callback StartConfig.BeforeServeFunc func(s *http.Server) error and starting server with StartConfig.Start(e) or using http.Server directly.

• Removed Echo.StartH2CServer(address string, h2s *http2.Server) (err error), replace with StartConfig.StartH2CServer(e *Echo, h2s *http2.Server) error

• Removed Echo.StartAutoTLS(address string) error, replaced with StartConfig.StartAutoTLS(e *Echo) error

• Removed Echo.StartTLS(address string, certFile, keyFile interface{}) (err error), replace with StartConfig.StartTLS(e *Echo, certFile, keyFile interface{}) error

• Only Echo.Start(address string) error was left in place for creating short demos/poc/examples.

  • Internally calls StartConfig.Start()
  • Supports now ctrl-c to shutdown the server (note: Echo.Shutdown is removed)

• Echo supports serving requests with custom echo.Context implementations. Setup context creation callback with Echo.NewContextFunc and when
  request is being served and context being borrowed from the context pool, then context will be created by that callback.
  Note: Using custom context is slightly slower than default context as cast to interface is slightly slower than to struct.

• Removed support for custom tcpKeepAliveListener for setting TCP keep-alive timeouts. From Go 1.13 this can be configured as:

  func main() {
    e := echo.New()
  
    e.GET("/", func(c echo.Context) error {
      return c.String(http.StatusOK, "OK")
    })
  
    server := &http.Server{Handler: e}
  
    lc := net.ListenConfig{KeepAlive: 15 * time.Second}
    ln, err := lc.Listen(context.Background(), "tcp", ":8080")
    if err != nil {
      panic(err)
    }
    defer ln.Close()
  
    if err := server.Serve(ln); err != http.ErrServerClosed {
      log.Fatalln(err)
    }
  }

echo.Group has similar changes as echo.Echo

• Changed route adding method signatures to return error instead of added route reference
  • Group.CONNECT returns now RouteInfo instead of *Route. Now: CONNECT(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.DELETE returns now RouteInfo instead of *Route. Now: DELETE(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.GET returns now RouteInfo instead of *Route. Now: GET(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.HEAD returns now RouteInfo instead of *Route. Now: HEAD(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.OPTIONS returns now RouteInfo instead of *Route. Now: OPTIONS(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.PATCH returns now RouteInfo instead of *Route. Now: PATCH(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.POST returns now RouteInfo instead of *Route. Now: POST(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.PUT returns now RouteInfo instead of *Route. Now: PUT(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.TRACE returns now RouteInfo instead of *Route. Now: TRACE(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo
  • Group.Any returns now []RouteInfo instead of []*Route. Now: Any(path string, h HandlerFunc, m ...MiddlewareFunc) []RouteInfo
  • Group.Match returns now []RouteInfo instead of []*Route. Now: Match(path string, h HandlerFunc, m ...MiddlewareFunc) []RouteInfo
  • Group.Add returns now RouteInfo instead of *Route. Now: Add(method, path string, handler HandlerFunc, middleware ...MiddlewareFunc) RouteInfo
• Added Group.AddRoute(route Routable) (RouteInfo, error) which allows adding route using echo.Route structure or Routable interface.
• Changed Group.Static returns error and change to accept middlewares as arguments. NOW: Static(prefix, root string, middleware ...MiddlewareFunc) RouteInfo
• Changed Group.File returns error and change to accept middlewares as arguments. NOW: File(path, file string, middleware ...MiddlewareFunc) RouteInfo

echo.Context interface has multiple breaking changes.

• Added RouteMatchType() RouteMatchType which helps middlewares to understand if this handler chain execution has handler at the end of something else (404/405). For Pre middleware this value
  returns always "unknown" as Pre middleware is executed before router tries to match the request.
  Basically enum with values: "route match/not found/method not allowed/unknown"

• Added RouteInfo() RouteInfo to return route info to which this request was matched to. As RouteInfo is interface then users can create custom implementation
  that can be added to router through echo.Echo.AddRoute(Routable) method. Routable is interface that is responsible of creating RouteInfo inside router when route is being added.

• Renamed Param(name string) string to PathParam(name string) string.

• Renamed ParamNames() []string to PathParams() PathParams

• Renamed SetParamNames(names ...string) to SetPathParams(params PathParams)

  Reasoning for that is: Method name Param is too ambiguous. Context interface already has methods like:

  QueryParam(name string) string
  FormValue(name string) string

  which explicitly describe where that *Param or *Value data comes/originates from. PathParam is explicit as those methods.

• Removed ParamValues() []string as PathParams result contains both name and value in PathParam struct

• Removed Logger() Logger. Usage of Echo own logger is disgouraged and use whatever logger library you choose and if needed put it into context with e.Set() and fetch with e.Get()

• Removed SetLogger(l Logger)

• Removed Handler() method.

• Removed SetHandler() method.

Move to echo.EditableContext

• SetParamValues(values ...string)
• SetHandler(h HandlerFunc)

Note: EditableContext interface is only for Echo internal usage to setup Context after route match has been found, just before handler chain will be called. Contains setters that should not be touched in middleware or handler.

Note: internally Context now 2 distinct fields to hold path parameters. context.pathParams lifecycle (allocation) is handled by Echo to reduce allocation. This field is not directly accessible to user. context.currentParams is meant for cases when middlewares are mutating path params and get copy of pathParams values on first usage. This field is settable for user.

echo.context struct.

• context.File(file string) now uses echo.Filesystem to serve file. So now you can use embedded Fs to serve files.
• context.FsFile(file string, filesystem fs.FS) error can be used to serve file from filesystem.

Router

Route(r) interfaces

Introduced interface for router. This will allow using custom router implementations with Echo.

// Router is interface for routing requests to registered routes.
type Router interface {
	// Add registers Routable with the Router and returns registered RouteInfo
	Add(routable Routable) (RouteInfo, error)
	// Remove removes route from the Router
	Remove(method string, path string) error
	// Routes returns information about all registered routes
	Routes() Routes

	// Match searches Router for matching route and applies it to result fields.
	Match(req *http.Request, params *PathParams) RouteMatch
}

Routable is interface for registering Route with Router. During route registration process the Router will convert
Routable to RouteInfo with ToRouteInfo method. By creating custom implementation of Routable additional information
about registered route can be stored in Routes (i.e. privileges used with route etc.)

// Routable is interface for registering Route with Router. During route registration process the Router will
// convert Routable to RouteInfo with ToRouteInfo method. By creating custom implementation of Routable additional
// information about registered route can be stored in Routes (i.e. privileges used with route etc.)
type Routable interface {
	// ToRouteInfo converts Routable to RouteInfo
	//
	// This method is meant to be used by Router after it parses url for path parameters, to store information about
	// route just added.
	ToRouteInfo(params []string) RouteInfo
	// ToRoute converts Routable to Route which Router uses to register the method handler for path.
	//
	// This method is meant to be used by Router to get fields (including handler and middleware functions) needed to
	// add Route to Router.
	ToRoute() Route
	// ForGroup recreates routable with added group prefix and group middlewares it is grouped to.
	//
	// Is necessary for Echo.Group to be able to add/register Routable with Router and having group prefix and group
	// middlewares included in actually registered Route.
	ForGroup(pathPrefix string, middlewares []MiddlewareFunc) Routable
}

RouteInfo interface:

// RouteInfo describes registered route base fields.
// Method+Path pair uniquely identifies the Route. Name can have duplicates.
type RouteInfo interface {
	Method() string
	Path() string
	Name() string

	Params() []string
	Reverse(params ...interface{}) string

	// NOTE: handler and middlewares are not exposed because handler could be already wrapping middlewares and therefore
	// it is not always 100% known if handler function already wraps middlewares or not. In Echo handler could be one
	// function or several functions wrapping each other.
}

So when you add route with Echo.AddRoute(route Routable) error that route is added to router with Add(routable Routable) and RouteInfo of that
route (which is created by Routable.ToRouteInfo() method) is accessible from router.Routes(). This all means that you can pass in your own custom types
(than can have extra information about route included in that type) and you are able to have your own routeinfo implementations when you access
ask for route list with e.Router().Routes().

Other router changes

• added: RouterConfig.unescapePathParamValues will instruct DefaultRouter to unescape path parameter values for matched route. People did this with middlewares and possible messed up maxParams size with that.
• added: RouterConfig.allowOverwritingRoute will instruct DefaultRouter (not to) to generate error when duplicate route (method+path) is added
• changed: It is now possible to add same path with different params names i.e. GET /users/:id and POST /users/:userID
• changed: any arbitrary http method type is now supported.

    e.Add("PROPPATCH", "/users", func(c echo.Context) error { return c.String(200, "OK") })
    // or
    e.AddRoute(echo.Route{
      Method:  "PROPPATCH",
      Path:    "/users",
      Handler: func(c echo.Context) error { return c.String(200, "OK") },
    })

Logger

Logger is trimmed down and used only for logging Echo internal stuff and/or used as http.Server.Errorlog field for capturing
http server logged errors. For logging in handlers/middlewares use logger library of your own choosing.

// Logger defines the logging interface that Echo uses internally in few places.
// For logging in handlers use your own logger instance (dependency injected or package/public variable) from logging framework of your choice.
type Logger interface {
	// Write provides writer interface for http.Server `ErrorLog` and for logging startup messages.
	// `http.Server.ErrorLog` logs errors from accepting connections, unexpected behavior from handlers,
	// and underlying FileSystem errors.
	// `logger` middleware will use this method to write its JSON payload.
	Write(p []byte) (n int, err error)
	// Error logs the error
	Error(err error)
}

Starting http server with Echo

All http server related methods and fields are moved from echo.Echo struct to separate implementation echo.StartConfig

Which has the following methods to replace ones that were removed from echo.Echo:

• StartTLS(e *Echo, certFile, keyFile interface{}) error
• StartAutoTLS(e *Echo) error

Quick example:

func main() {
	e := echo.New()

	// only start* method that was left to `e` instance. Shorthand for demos/examples/proof-of-concepts
	if err := e.Start(":8080"); err != http.ErrServerClosed {
		log.Fatal(err)
	}

	sc := echo.StartConfig{ // `StartConfig` contains now fields related to running server
		Address: ":8080",
	}
	// functionally identical to `e.Start(":8080")`
	if err := sc.Start(e); err != http.ErrServerClosed {
		log.Fatal(err)
	}
	
	// `e.StartTLS(address string, certFile, keyFile interface{})`  replacement would be:
	if err := sc.StartTLS(e, certFile, keyFile); err != http.ErrServerClosed {
		log.Fatal(err)
	}

	// `e.StartAutoTLS(address string)` replacement would be:
	autoTLSManager := autocert.Manager{
		Prompt: autocert.AcceptTOS,
		Cache:  autocert.DirCache("/var/www/.cache"),
	}
	sc = echo.StartConfig{
		Address: ":443",
		TLSConfigFunc: func(tlsConfig *tls.Config) {
			tlsConfig.GetCertificate = autoTLSManager.GetCertificate
			tlsConfig.NextProtos = []string{acme.ALPNProto}
		},
	}
	if err := sc.Start(e); err != http.ErrServerClosed {
		log.Fatal(err)
	}

	// `e.StartH2CServer(address string, h2s *http2.Server)`  replacement would be:
	sc = echo.StartConfig{
		Address: ":8080",
		BeforeServeFunc: func(s *http.Server) error {
			h2s := &http2.Server{
				MaxConcurrentStreams: 250,
				MaxReadFrameSize:     1048576,
				IdleTimeout:          10 * time.Second,
			}
			s.Handler = h2c.NewHandler(e, h2s)
			return nil
		},
	}
}

New config struct fields are following:

// StartConfig is for creating configured http.Server instance to start serve http(s) requests with given Echo instance
type StartConfig struct {
	// Address for the server to listen on (if not using custom listener)
	Address string

	// ListenerNetwork allows setting listener network (see net.Listen for allowed values)
	// Optional: defaults to "tcp"
	ListenerNetwork string

	// CertFilesystem is file system used to load certificates and keys (if certs/keys are given as paths)
	CertFilesystem fs.FS

	// DisableHTTP2 disables supports for HTTP2 in TLS server
	DisableHTTP2 bool

	// HideBanner does not log Echo banner on server startup
	HideBanner bool

	// HidePort does not log port on server startup
	HidePort bool

	// GracefulContext is context that completion signals graceful shutdown start
	GracefulContext stdContext.Context

	// GracefulTimeout is period which server allows listeners to finish serving ongoing requests. If this time is exceeded process is exited
	// Defaults to 10 seconds
	GracefulTimeout time.Duration

	// OnShutdownError allows customization of what happens when (graceful) server Shutdown method returns an error.
	// Defaults to calling e.logger.Error(err)
	OnShutdownError func(err error)

	// TLSConfigFunc allows modifying TLS configuration before listener is created with it.
	TLSConfigFunc func(tlsConfig *tls.Config)

	// ListenerAddrFunc allows getting listener address before server starts serving requests on listener. Useful when
	// address is set as random (`:0`) port.
	ListenerAddrFunc func(addr net.Addr)

	// BeforeServeFunc allows customizing/accessing server before server starts serving requests on listener.
	BeforeServeFunc func(s *http.Server) error
}

Binder

• e.Bind() and DefaultBinder to be precise do not clear values when binding for base types (ints, bool, float). See Empty string turns into "false" bool during binding  #1521

    type SearchOpts struct {
      ID       int    `query:"id"`
    }
  
    opts := SearchOpts{
      Length:   100,
    }
    err := c.Bind(&opts)

  Previously opts.Length would be 0 after bind if that field did not exists in query. Now it stays 100 (value is not touched).

Middlewares

General

• Introduced interface for creating middleware functions without panics on configuration errors

  type MiddlewareConfigurator interface {
    ToMiddleware() (MiddlewareFunc, error)
  }

  All middleware configuration structs now implement that interface and allow you to create middleware function and check if there are errors.
  Existing creator functions stay as they are - same signature and panicing on invalid configuration.

BasicAuth

• Removed DefaultBasicAuthConfig struct. Middleware creator func will set now default values.
• Added BasicAuthConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create basic auth middleware without panics.

BodyDump

• Removed DefaultBodyDumpConfig struct. Middleware creator func will set now default values.
• Added BodyDumpConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create body dump middleware without panics.

BodyLimit

• Removed DefaultBodyLimitConfig struct. Middleware creator func will set now default values.
• Changed BodyLimitConfig.LimitBytes from string to int64 (allowed size in bytes).
• Added BodyLimitConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create body limit middleware without panics.

Gzip

• Removed DefaultGzipConfig struct. Middleware creator func will set now default values.
• Added GzipConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create Gzip middleware without panics.

CORS

• Added CORSConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create CORS middleware without panics.

CSRF

• Added CSRFConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create CSRF middleware without panics.

Decompress

• Removed DefaultDecompressConfig struct. Middleware creator func will set now default values.
• Added DecompressConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create decompress middleware without panics.

JWT

JWT middleware was refactored not to depend any JWT library. To use JWT user must provide own token extraction method.

• Changed all methods that extract raw token from request to support returning multiple values. To support cases when
  browser sends multiple authorization headers (ala request has basic auth + bearer headers). Previously whatever was
  first was extracted which could be not intended value to be parsed as JWT token.

• Changed cases when no token was found/extracted (ErrJWTMissing) to return http.StatusUnauthorized 401 status code instead of http.StatusBadRequest 400

• Renamed ErrorHandlerWithContext to ErrorHandler. Signatures is JWTErrorHandlerWithContext func(error, echo.Context) error

• Changed middleware to resume handler chain execution next(c) when developer provided JWTConfig.ErrorHandler() callback decides to swallow the given error
  This is Useful in cases when portion of your site/api is publicly accessible and has extra features for authorized users.
  In that case you can use ErrorHandler to set default public token to request and continue with handler chain by returning no error.

• Removed configuration fields related to specific JWT token parsing implementations

  • Removed JWTConfig.SigningKey field.
  • Removed JWTConfig.SigningKeys field.
  • Removed JWTConfig.SigningMethod field.
  • Removed JWTConfig.Claims field.

  Added example in jwt_external_test.go how to use JWT library with golang-jwt/jwt library.
  Middleware is to be created as:

  // see `jwt_external_test.go` for `CreateJWTGoParseTokenFunc` implementation
  e.Use(middleware.JWTWithConfig(middleware.JWTConfig{
      ParseTokenFunc: CreateJWTGoParseTokenFunc([]byte("secret"), nil), 
  }))
  e.Use(middleware.JWT(CreateJWTGoParseTokenFunc([]byte("secret"), nil))) // or shorter way

• Added JWTConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create JWT middleware without panics.

KeyAuth

• Removed KeyAuthConfig.AuthScheme field. Use KeyAuthConfig.KeyLookup = "header:Authorization:Bearer " instead (NB: space at the end is important).
• Changed KeyAuthConfig.KeyLookup to support additional extraction sources:

    // Possible values:
    // - "header:<name>:<value prefix>"
    // - "query:<name>"
    // - "param:<name>"
    // - "cookie:<name>"
    // - "form:<name>"

• Changed all methods that extract raw token from request to support returning multiple values. To support cases when
  browser sends multiple authorization headers (ala request has basic auth + bearer headers). Previously whatever was
  first was extracted which could be not intended value to be checked/validated as key auth.
• Added KeyAuthConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create key auth middleware without panics.

Logger

• Removed coloring support.
• Changed middleware not to call c.Error() and return error to be handled up in caller chain (or global error handler)
• Added LoggerConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create logger middleware without panics.

MethodOverride

• Added MethodOverrideConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create method override middleware without panics.

Proxy

• Added ProxyConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create proxy middleware without panics.

RateLimiter

• Added RateLimiterConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create rate limiter middleware without panics.

Recover

• Removed RecoverConfig.LogLevel field.
• Changed middleware not to call c.Error() and c.Logger(). Recovered error/value will bubble up and be handled
  eventually in global error handler.
• Added RecoverConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create recover middleware without panics.

RequestID

• Removed DefaultRequestIDConfig struct
• Added RequestIDConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create request ID middleware without panics.

Redirect

• Added RedirectConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create redirect middleware without panics.

Rewrite

• Added RewriteConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create redirect middleware without panics.

Secure

• Added SecureConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create secure middleware without panics.

(Add/Remove)trailing slash

• Changed TrailingSlashConfig to AddTrailingSlashConfig and RemoveTrailingSlashConfig
• Added AddTrailingSlashConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create add trailing slash middleware without panics.
• Added RemoveTrailingSlashConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create remove trailing slash middleware without panics.

Static

• Added StaticConfig.Filesystem field which will be fs.FS used to serve file. Defaults to echo.Echo.Filesystem value.
• Added StaticConfig.DisablePathUnescaping field disable path escaping when serving the file.
• Added StaticConfig.DirectoryListTemplate field to allow developer to specify custom html template for directory listings.
• Added StaticConfig.ToMiddleware() (echo.MiddlewareFunc, error) to create static middleware without panics.

Timeout

TODO: propose to delete this middleware.

Benchmarks

TODO: paste benchstats results

[aldas]

reserved

[fixotech]

HTTPError or NewHTTPError does not exists in V5?

"type echo.Context has no field or method HTTPError"
"type echo.Context has no field or method NewHTTPError"

[ganigeorgiev]

@fixotech both echo.HTTPError and echo.NewHTTPError() exists in v5.
You could check the upgrade guide for changes to the error handling and Context- https://echo.labstack.com/v5/guide/upgrading-to-v5/#error-and-handling-of-errors.

[aldas]

reserved

[zxysilent]

Consider using echo.Config instead of echo.StartConfig

[aldas]

I agree that StartConfig may not be best choice but Config alone would be too ambiguous.

The reasoning for something longer than echo.Config is that Config alone does not convey the meaning of configuring something related to the starting/running of server. For me it would cause confusion with echo.Echo instance configuration and the fact that it is not about that object at all. Using library provided helpers to run http.Server is completely optional as h := http.Server{Handler: e} is perfectly fine.

At some point I used ServerConfig but renamed it as it is not configuring the server - it is more about configuring how server starts and less about server itself.

[justinruggles]

I would be very glad to see the middleware packages move to a separate Go module (or modules).

(These proposed changes look great, btw)

[aldas]

@justinruggles and everyone who have upvoted this comment or are reading this at the moment and want to voice their thoughts - please respond in #2000 (comment) thread

Why it would be beneficial for you to have middlewares separated?
How concerned you are usually about API changes? I think we have had quite few them in 4.x
Single repo for all middlewares or each their own?
Which versioning schema would be less confusing - bumping major versions (semantic versioning) or bumping minor versions?

[boosh]

Just came to check whether logging was more configurable now. That looks like the most important change IMO, thanks!

[serdar-irmak]

v5 seems perfect imho, good job

[deefdragon]

I just encountered #1744 (et-all) and didn't see it at first read through on the list of stuff being done here. Is that still intended to be addressed for V5?

To explain my reasoning for having different params as that seemed to be a question, TLDR I have a many2one relationship.

Specifically, GET /version/:id retrieves the specified version that is requested, whereas POST /version/:base is for creating a NEW version for :base. Its not the most elegant solution, but I honestly could not come up with a better scheme that meshed with the rest of the API and separated things logically.

[aldas]

This requirement: same path, different methods, different param names is covered. Test covering this requirement can be seen here

echo/router_test.go

Line 2115 in 6ef5f77

func TestRouter_Match_DifferentParamNamesForSamePlace(t *testing.T) {

Please see if it satisfies your requirements.

[deefdragon]

That looks like it covers it. Thank you!

[da4z]

Remove Context c.Error(), use return err uniformly

[aldas]

I personally agree with you on this idea.

Currently in v5 all c.Error(err) usages have been removed (except from timeout middleware) but Error method is still in Context interface.

Probably only reasonable usecase for c.Error would be when you are dealing with coroutines and want to call global error handler to write error response to the client. This is what for Error is used in timeout middleware. But from timeout middleware I have learned that you writing data race free coroutines with echo.Context is quite complex (it not possible at all).

If someone reads this comment and knows valid reason why/when returning the err from middleware function is not suitable and calling c.Error(err) is preferred - please write here.

[da4z]

@aldas

1. c.Error() causes the logger middleware not to record errors, which is difficult to debug
2. Broken middleware call chain

[aldas]

Just a note. Use-case for echo.Context.Error() is when you are dealing (wrapping you handler func inside them) with Go standard library http handlers http.Handler.ServeHTTP(ResponseWriter, *Request) and want to send error to the client through global error handler.

[da4z]

Middleware is not recommended to be divided into separate packages, otherwise core upgrades, these sub-packages will not be maintained in time

[aldas]

Middlewares depend on echo.Context which changes rarely. Reason to break out middlewares from core repository is so we can version and iterate them separately from the core. I would say that most of changes are related to middlewares and it is impossible due semantic versioning scheme we are supporting. So if we would change in non backwards compatible way some middleware API we should create new version of this repo and this would mean that echo import path would change every where. You would need to change "github.com/labstack/echo/v4" to "github.com/labstack/echo/v5" etc everywhere even if you do not use middleware that created version bump.

From usability point of view it is very good that we are bound with semantic versioning as it slows down the change and therefore maintenance costs for library users - you do not need to update import paths because of changes that you do not need or care about.

concerns that we have are:

From user perspective:

• need to iterate middleware APIs (modify/remove configuration fields and their types). ala Rate limiter and Limit type comes to mind as first thing.
• need to keep breaking changes minimal, especially import path changes - as it is maintenance burden for all Echo users
• it is simpler to use middleware when you need go get only one package and not core + 1 or more packages.

From maintainers perspective:

• to be able to change middlewares - for example change from github.com/dgrijalva/jwt-go to github.com/golang-jwt/jwt was very painful and was actually breaking change which we were forced into eventually after holding it back for 6 months.
• having too many repositories to keep eye on is a burden - atm labstack/echo-contrib does not get that much attention and labstack/gommon is almost derelict (in v5 core does not depend anymore on gommon).

So the proposal was something between:

should we move all middlewares out of core to echo-middlewares package (one package for all) and version it from
5.0.0 and leave out semantic versioning for that repo. Breaking changes are done in minor versions but not in
patch versions. so all Echo v5 stuff would be ala echo-middlewares@v5.15.0. Some people would probably complain
about unnecessary dependencies (same as echo-contrib) but Go modules does not actually compile module dependencies
that are not used in your app and as of Go 1.17 dependencies that are not used are not even downloaded.
So if there are external dependencies in that repo it should be ok. Allowing breaking changes in minor version is
a little bit more convenient for user as he/she does not need to update packages on version
bump (with go mod major version bump means new package import paths but minor version does not generate new path).

Personally today I would be totally fine if we do not do anything about middlewares location in v5. Biggest pain point was dgrijalva/jwt-go and everything else is quite minor. Last 6 months or so has been quite quiet. But version change to v5 is the time we can do these radical changes and there will not be v6 probably in couple of years (unless Go 1.18 and generics open some amazing possibilities for us)

@lammel your thoughts?

[lammel]

From my point of view I think we should do both. There are middlewares that should be closely maintained with the core of echo, especially those without external dependencies (3rd party) and common use cases. For others we should rethink moving them out of echo core to echo-contrib. I can't think of any contrib modules that should be moved to core currently.

Reasons to move a middleware out of core echo are:

• the middleware depends on 3rd-party packages (here the jwt-go chaos comes to mind)
• the middleware is hard to maintain
• the middleware has a very limited usecase (e.g. timeout middleware)

The echo-contrib project might need renaming and improved documentation to clarify the relation and should also use the same major version as the core echo project.

So currently I see the middlewares jwt and timeout as candidates to move to echo-contrib with v5.

Feedback and objections welcome ;-)

[bytejedi]

Middleware is not recommended to be divided into separate packages, otherwise core upgrades, these sub-packages will not be maintained in time

I agree with you @da4z I mean keep Middleware as a sub package not a independent git repository. Mainly to reduce maintenance costs and user just import github.com/labstack/echo/v5/middleware

[aldas]

@bytejedi have you tried sub package inside main app/library repo? How does it play out with version bumping and stuff like that? I have not - I probably should try to create some small example repo and bump it to v2 and try different situations with go get etc.

[bytejedi]

@bytejedi have you tried sub package inside main app/library repo? How does it play out with version bumping and stuff like that? I have not - I probably should try to create some small example repo and bump it to v2 and try different situations with go get etc.

import github.com/labstack/echo/v4/middleware
it works on v4.

I think v5 should also works.

[smithyj]

maybe keep timeout middleware is good option

[smithyj]

v6 release date have plan？

[aldas]

no, @smithyj is there a feature or thing that you like Echo to have?

From user perspective it would be better if we do not iterate versions too quickly and take time as upgrading libraries is quite painful if you have business value to deliver. Probably everyone has experienced insane amount of work it takes to keep up Javascript libraries changes - sometimes it feels it is easier to write new app than to start resolving all breaking changes/dependencies with upgraded libraries. In that sense of Go and its ecosystem pace is a blessing.

[stellirin]

The v5 proposal looks good, I don't mind the minor breaking changes to make the code more consistent.

Regarding middleware, I do see the pros and cons of both approaches, my personal preference would be to keep the middleware in the main package.

If/when I upgrde a major version of Echo then I would be uncertain if any external middleware also need to be upgraded. I would expect any middleware in the main package to be always compatible, but there's less of a guarantee that external middleware would remain compatible. Because of that I would probably spend more time researching the middleware repositories and running tests to check if they really are still compatible than if I 'only' had to do a search and replace to change the imports in my code.

[liaohongxing]

JWT

Changed Signatures type JWTSuccessHandler func(c echo.Context) to JWTSuccessHandler func(c echo.Context) error

[aldas]

This would be simple change.

Workaround for it at the moment is that you just add another middleware after JWT which will do the SuccessHandler actions.

	e.Use(middleware.JWTWithConfig(...))
	e.Use(func(next echo.HandlerFunc) echo.HandlerFunc { // this is pretty much same as `SuccessHandler` with error
		return func(c echo.Context) error {
			return echo.ErrUnauthorized
		}
	})

[devholic]

v4 DefaultBinder provides scoped binding methods (e.g. BindQueryParams, BindPathParams), is there any plans to update Binder interface in v5?

[aldas]

At the moment no - we have not seen that as a need. But we have not had much thought on v5 and Binder interface to be honest.

Are you having troubles with

echo/bind.go

Line 118 in 4fffee2

if c.Request().Method == http.MethodGet || c.Request().Method == http.MethodDelete {

part? It would be very helpful if you describe your use-case for using those methods instead of Bind.

Currently these methods are accessible through - which is probably awkward to use

var payload User
if err := (&DefaultBinder{}).BindQueryParams(c, &payload); err != nil {
	return c.JSON(http.StatusBadRequest, Map{"error": err})
}

note to self: related Issues/PR https://github.com/labstack/echo/search?q=BindQueryParams&type=issues

[devholic]

In our use-case:

// `PATCH /api/user/:name`
type request struct {
	Name string `param:"name"`
}

We are trying to bind this request struct to get path parameter. But if we send following json payload,

{
  "name": "Ryan"
}

request.Name will be overridden by name in json payload, since Binder processes in order of 1) path params 2) query params 3) request body.

This might can be done with

• Custom JSON deserializer, which ignores field without json tag while deserializing

• Explicitly setting - tag to request field like below

  // `PATCH /api/user/:name`
  type request struct {
      Name string `param:"name" json:"-"`
  }

I think following approach might resolves this issue:

type request struct {
    params struct {
        Name string `param:"name"`
    }
}

var req request
c.BindPathParams(&req.params)

[aldas]

Just looked at v5 bind code. Seems that I have made some of those private methods global functions and Binder has not been touched.

So you would have

echo.BindBody(c Context, i interface{}) error
echo.BindPathParams(c Context, i interface{}) error
echo.BindQueryParams(c Context, i interface{}) error
echo.BindHeaders(c Context, i interface{}) error

which can be used as

var payload User
if err := echo.BindQueryParams(c, &payload); err != nil {
	return c.JSON(http.StatusBadRequest, Map{"error": err})
}

Note: we have both in v4 and v5 addition to c.Bind() another way of binding. See https://echo.labstack.com/guide/binding/#fast-binding-with-dedicated-helpers

Example:

// url =  "/api/search?active=true&id=1&id=2&id=3&length=25"
var opts struct {
  IDs []int64
  Active bool
}
length := int64(50) // default length is 50

// creates query params binder that stops binding at first error
err := echo.QueryParamsBinder(c).
  Int64("length", &length).
  Int64s("ids", &opts.IDs).
  Bool("active", &opts.Active).
  BindError() // returns first binding error

[devholic]

Thanks for let me know! 🙂

[jwendel]

For the CSRF middleware, it would be nice to support both Form and Query with a single config. Right now it's set up to only support one or the other, and it would nice to have the CSRF module would check both locations to see if the token is passed down.

[aldas]

Looking at CSRF code (even in v4) it would possible to take code related to Lookup in JWT or KeyAuth middleware and use it in CSRF and have it support multiple sources.

[jwendel]

Looking back at my fork of the middleware, I wanted header and query support (not form and query), but the same applies.

To support it today, would the middleware have to be installed twice (I don't think that would work, as one or the other would reject the request)? Right now, you can only set TokenLookup to be "header", "form", or "query", but not a mix of them. (code: https://github.com/labstack/echo/blob/master/middleware/csrf.go#L118-L125). I would like to be able to, depending on the URL (or maybe just globally), look for the CSRF TokenLookup in multiple places. I don't see how that could be done without code changes. I agree it wouldn't need to be a backwards-compatibility breaking change (maybe taking a comma separated list for TokenLookup?).

[zuozhehao]

Great, we've upgraded from v4 to v5 with only minor modifications.

[ganigeorgiev]

@aldas About "Removed field Echo.Server. Replaced with echo.StartConfig implementation. Can not be directly passed anymore."

In that case, what is the expected/recommend way of setting for example the server timeouts - through BeforeServeFunc? Feels a little cumbersome doing it this way.

[aldas]

You do not need to use BeforeServeFunc

Using custom http.Server is easier if you do it like that (this is same in v4 and v5)

func main() {
	e := echo.New()

	s := &http.Server{
		Addr:         ":8080",
		ReadTimeout:  5 * time.Second,
		WriteTimeout: 5 * time.Second,
		Handler:      e,
	}
	if err := s.ListenAndServe(); err != http.ErrServerClosed {
		log.Fatal(err)
	}
}

in comparison to v4 and echo.Start* methods

func main() {
   e := echo.New()

   s := &http.Server{
      Addr:         ":8080",
      ReadTimeout:  5 * time.Second,
      WriteTimeout: 5 * time.Second,
   }
   if err := e.StartServer(s); err != http.ErrServerClosed {
      log.Fatal(err)
   }
}

and v5

func main() {
   e := echo.New()

   sc := echo.StartConfig{
      Address: ":8080",
      BeforeServeFunc: func(s *http.Server) error {
         s.ReadTimeout = 5 * time.Second
         s.WriteTimeout = 5 * time.Second
         return nil
      },
   }
   if err := sc.Start(e); err != http.ErrServerClosed {
      log.Fatal(err)
   }
}

All those fields Server/TLSServer Listener/TLSListener/AutoTLSManager related fields are removed from Echo instance as it assumes the relationship between Echo and Server/Listener in wrong way. Echo can be used to handle multiple servers/listeners request and can be started in different times. Relation Echo->Server/Listener is limiting and correct is Server->Echo.

As for those old methods StartServer, Start* etc and new echo.StartConfig - these are better suited for simplistic cases and most likely in more complex situation you resort to creating http.Server instance and setting Echo has handler.

In heavy customization or multiple server situation Echo.Server* methods are quite useless as http.Server.Handler is all you actually need and gives you most flexibility.

[fritterhoff]

Is there some sort of timeframe for the release of version v5?

[johnoldham33]

Any estimate for when this will be released? So psyched for this! Looks amazing

[m1x0n]

Hi! It would be nice to have a possibility of customizing operation name in https://github.com/labstack/echo-contrib/blob/master/jaegertracing/jaegertracing.go#L141 via configuration option.

TraceConfig might extended with following property:

OperationNameFn func(c echo.Context) string

The use-case I'm facing is replacing uri path params with their names or predefined placeholders per http request.
E.g. /api/cats/1/breed -> /api/cats/:catID/breed

I would like to contribute such a patch if it looks reasonable.

[aldas]

This does not need to wait for v5. Just create a pull request to echo-contrib and I'll review it.

p.s. I think OperationNameFunc would align better with other names.

[jamesli2021]

Anything else we need to test before finalize v5? It's worth to have a tentative release date to encourage faster adoptions and fix issues at once as most devs tend to wait for the stable release.

[jamesli2021]

When compare benchmark between 1.18.5 and 1.19.0, the latter seem to have less throughput than 1.18.5 on Echo v4, is it the same for pre-v5?

[reinkrul]

Would be useful if exported structs implement a defined interface. E.g. the v4 echo.Echo struct is simple to use, but impossible to mock (e.g. when unit testing application lifecycle or route registration). We solved this by defining an EchoServer (for lifecycle funcs) and EchoRouter interface in our application, but would be nice if v5 were to provide this out of the box.

[aldas]

In go there is a proverb "Accept interfaces, return structs". There are plenty of blog posts and thread explaining these principles.
For example: https://www.reddit.com/r/golang/comments/dfe1qr/who_first_said_accept_interfaces_and_return/

In regards of having interfaces for Echo own instance or group - this would create too much problems as we would not be able to add methods without bumping major version. Also - in Go you are encouraged to create interfaces places where structs are consumed. In this way you would create interface with only methods that you use. If it would be other-way - interfaces are defined where code that is consumed resides then you would have huge interfaces (like echo.Context has 20+ methods I think) that are pain to implement (mock for example) and hard to change (backwards compatibility).

In that sense when you compare Gin to Echo - Gin has much more flexibility by their context not being interface and adding a new method is way-way easier and does not break library users code. Which would be the case when we would change Echo context interface and your implementations now are not compiling/failing because you no longer fully implement that interface.

In v5 we have interface for Router but this is only because we want to open Echo to different router implementations and use-cases. For example current router is not safe to be mutated after server has been started - but why not allowing users to embed our default router with struct containing RWmutex + methods using it to call embedded router and now you can add/remove routes at runtime safely. Or another usecase/idea I had - during startup choose router implementation that only implements features that you use. ala router that only knows static routes (no any/param routes), does not do backtracking etc - being extremely lightweight.

[reinkrul]

I understand the reasoning. For v5, I think it helps that Router gets its own generic interface (which is awesome) and the different Start funcs are getting refactored to 1. So the interfaces we have to define ourselves are manageable small (generally only Start and Shutdown).

[Kamandlou]

I think now we can delete HTTP methods constancies in echo.go to officially deprecate

[Kamandlou]

In my opinion, it is better to end the support of Golang version 16
It's can help us to develop the Echo

[FeldrinH]

I like the idea of the proposed logger changes, however, I am a bit confused about the proposed logger interface. How should it be implemented if I use structured logging?

The Write method matching io.Writer seems to imply that I should just pipe the bytes through to wherever my logs should output to, but then Echo internal logs won't follow the correct structured logging format and will break my log parsing.

[ex-tag]

I do not think developers should be spending time configuring features like the banners hideBanner, if ports are displayed hidePort, putting it into debug mode - or any other look and feel of Echo.

Just enable these features by default for development mode, and provide a isProductionMode boolean to disable them.

[vuhoanghiep1993]

I think echo should apply to become a CNCF project , it make echo more trustworthy with users

[serdar-irmak]

+1 16 Ekim 2022 Pazar tarihinde, 13:26 saatinde, vuhoanghiep1993 şöyle yazmış:

…

I think echo should apply to become a CNCF project , it make echo more trustworthy with users — Reply to this email directly, view it on GitHub <#2000 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AURNX25ANASKOR5BRCA2TADWDPJ6DANCNFSM5FGRJIZQ>. You are receiving this because you commented.Message ID: ***@***.***>

[mei-rune]

Can generics support?

type Context[Data any] interface {
.............

UserData() Data
}

[aldas]

I have to try how generics it would look but I am personally not very convinced that it would be a good idea. The reasoning is that people would abuse that and write their handlers into spaghetti code where context serves as some kind of business oriented service. If you want to write maintainable code you need to have borders/layers/"separation of concerns" and not one big ball of mud.

Currently v4 context.Get and context.Set allows you to pass any object you desire down the middleware chain into the handler. And is not particularly longer to write.

In v5 we allow using your own structs that implement echo.Context interface or embed echo.DefaultContext to be used as context but with that you would need still cast in your handler to be able to access your custom methods on your struct.

[sp71]

Release date for v5?

[aldas]

Probably not in the near future, at least couple of months.

If there are features you would like to use and these do not require breaking changes, just create an issue.