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?).

[jamesleeht]

I'd love for binder and validator to be combined into a convenience function so we don't have to call both bind() and validate() in the same handler.

#1105 goes into details of the issue and I've also added an example of a custom binder that supports this function.

[siyul-park]

How about removing the router from the echo instance and letting the router be used through middleware?

There are a lot of bugs included here, but there is a fork that seems to be working https://github.com/partialize/echo-slim

[siyul-park]

In my case, I was writing an API-Gateway where users should be able to modify routes dynamically through HTTP APIs. In that case, adding a route was the main domain of my project, and I needed to add certain features that were not common to the router function.

I don't think there will be many developers like me. However, for those who start a application for the first time, if you need a router, you will first look for the router function provided by first-party and learn it. We will use another router only if the first-party router is not satisfied. Of course, converting the router in use to another router where the interface is not unified will require a lot of changes. However, third-party router developers who are smart enough will try to unify the interface with other routers, and only modify the interface if they cannot. And while changes to the router may require a lot of modifications to the existing code, just like when updating the echo to the latest version, I think it's a problem for developers to properly isolate external dependencies. If the router function itself is a major domain handled by the application like me, I think there may be less points of change.

[aldas]

modify routes dynamically through HTTP APIs

This was one of the reason for v5 Router interfaces - so you could create/compose Router that is go-routine safe - current Router is not.

but would it not be easier for echo-slim to define interface for Router and modify echo.Echo fields/methods to that? In that case you could set/use Router that is made go-routine safe and have less head-ache merging back changes from Echo project.

I needed to add certain features that were not common to the router function

Could you list those and explain how are you using these. Maybe we are missing something from Echo atm.

[siyul-park]

Could you list those and explain how are you using these. Maybe we are missing something from Echo atm.

I had to be able to write the route recursively.

For example, all requests coming into /a/* had to be able to be delivered to sub-routers with sub-paths /a/a and /a/b after going through certain middleware. And all of these routes and middleware had to be dynamically modifiable.

/a/* -> middleware -> /a/a -> middleware -> ...
                   |> /a/b -> middleware -> ...

[aldas]

but how it is different from Group or just considering "subrouter" a collection of routes with same prefix. I think there are more nuances here that you at the moment did not mention. For example 404 handling (although this can be done in latest Echo releases)?

At the moment the biggest show stopper seems to be go-routine safe router and ability to remove routes runtime. Current Echo is not designed to be modified during runtime.

[siyul-park]

The difference from the existing group was that the group can also occur recursively. (/a/* -> /a/b/* -> /a/b/c). The difference between "subrouter" a collection of routes with same-prefix is likely to be a difference in that each route group must go through separate middleware before entering the handler. (Of course, with "subrouter" a collection of routes with same prefix, it seems possible to implement the requirements themselves.)

For example 404 handling (although this can be done in latest Echo releases)?

If the appropriate handler for the route was not found, all remaining middleware was executed, and if the response status was the same as the initial value, it was set to 404.

[aldas]

Hi everyone!

TLDR: I was distracted with real life and did not feel that v5 was ready.

So this thread has been quite quiet from our part. I feel embarrassed for it.
2022 Echo had couple of minor releases, bugs were fixed. As v5 did not feel quite "ready" I did what I have learned from personal
experience - when you are not really sure about ideas and have time to spare - just put these things on hold and have them "marinate" at the background in you thoughts.

I strongly believe that we should not try to move too quickly. I think many can relate the burnout from constant change in Javascript framework ecosystem. Changing things every 6 months could be fun for first couple of times but gets soul crushing as years go by.

Main things that concerned me about v5:

• are the new Router interfaces justified and/or reasonable?
• how are we going to do echo-contrib middleware and related repo version bumps?
• are there enough changes (in addition to router) to justify major release?

For:
1 - I think we I need to do some simplification here. Router interface itself is probably OK but Route interface is maybe overkill.
2 - As we released new JWT middleware I think we have plan for version bumps in related repos.
3 - next 2 posts are about changes that probably justify major release

I will cover some bigger changes in next to posts below to allow separate discussion for them.

[aldas]

So one radical idea that 2022 gave me is: we should drop echo.Context interface and move back to echo.Context struct (as it was struct in ye olde times v3).

Reasoning for it is:

• We can add new methods without major releases. It has PROs and CONs but for longevity of v5 I think it would be good thing.
• Using struct is very slightly more performant that interface. This is more apparent when you do casts to interface and that interface is huge as current echo.Context is - as you need to do check for existence of every method. This is not a thing when it comes to handler but for example in ServeHTTP we could do this cast. I write it here only to convince performance junkies - for ordinary mortals (like me) you would not notice the difference.
• echo.Context interface has 50+ methods - really would like to hear from someone how had willpower to reimplement all those for own custom context - for testing or some other purposes. Because of this cast I know that no one is using own Context in production.

How change from interface to struct would look like

1. Handler signature changes from func(c echo.Context) error { to func(c *echo.Context) error { - only new thing is here asterisk.
2. We would not expose (request,response etc) fields as public. These will be accessed through methods like before. Reasoning here is that with methods you can create your own small interfaces that echo.Context satisfies. And by not changing visibility - your existing code does not need to change.

Your thoughts?

[aldas]

Checking if something is internally called is maybe too white box testing especially if that call result already leads to different test results that can be actually asserted/checked.

I use testify mock.Mock a lot to test interfaces but I have never felt need for doing something extra for echo.Context to results I expect. Usually httptest.NewRequest and httptest.NewRecorder that is passed to the context is enough and rarely custom writer to check how response is written.

But this is my own biased experience.

This is interesting - apart from counting calls - is there something in context that can no be set in test preparation part requires overwriting that context method (new behavior that modifies/replaces return value)?

[ganigeorgiev]

Yes, I agree, the tests could be done differently and not so focused on the handler internal implementation.

is there something in context that can no be set in test preparation part requires overwriting that context method (new behavior that modifies/replaces return value)?

Often we use mocks for Validate, Bind, FormFile, etc. to emulate more easily specific return values or errors, but I guess to some extend this could be also achieved by mocking for example the Binder or Validator fields of the echo struct.

I have no strong opinion on the suggested change, just sharing my experience in case the use case is similar to what other users do.

[lammel]

so limiting factor here is handler function signature func(c echo.Context) error which means that you need to cast/convert that context into different type in each handler.

I admit that I have not done much research in generics - could it allow us to have solution for generic handler function that works with middlewares etc. As at some point it felt that allowing to much flexibility with what context is, leads to abuse and spaghetti code. (yep, I am opinionated here)

I'm neither in favor nor against switching to struct based context, but I completely share your concerns about allowing too much flexibility.
There should be a good reason to even have the requirement to extend echo.Context and a clean way to do that should be allowed.
Maybe we identify some more corners, where people start extending because their usecase is not working with core echo or contrib-middlewares.

I also definitly need to play around an a dedicated branch for a context change to get an opinion on that. Hope I get around to take a deep look into echo v5 soon.

[aldas]

I did some testing in January in this branch https://github.com/aldas/echo/tree/v5_alpha_context benchstat give pretty much identical performance interface vs struct (very slightly in favor of struct).

[luckycatx]

What's the thoughts on this lately? I'd love to hear about the change from interface to struct, the flexibility it provides will be beneficial for future updates, also a slightly performance improvement.

[aldas]

Another change - start using Slog logger https://go.googlesource.com/proposal/+/master/design/56345-structured-logging.md

Recently structured logging proposal was accepted for Go 1.21 golang/go#56345

Currently in v5 we have trimmed down logger, but going straight to Slog would be the best. It is opinionated as it is "structured" but this does not mean that you could not have ordinary "single line console message" logger implementation behind it.

[lammel]

The proposal looks quite good and would allow for a standard way of using logging which developers can adjust to their needs without introducing additional dependencies (well, Go 1.21 would be a dependency).

[debuggerpk]

rooting for slog.

[toqueteos]

How much of a bad idea would be for v5 to add support for file binding (as in Context.FormFile) while we are at it?

[bakatz]

Overall I like this proposal, but would suggest one change: instead of having a giant "middleware" repo, split each middleware into its own repo and allow users to select which specific middleware packages they want on their own. I only need 2-3 of them for most projects and would rather just go get ... each one individually.

[jxsl13]

great for having few dependencies

[mei-rune]

I did some testing in January in this branch https://github.com/aldas/echo/tree/v5_alpha_context benchstat give pretty much identical performance interface vs struct (very slightly in favor of struct).

I hope add golang Generics support，
I improve #2000 (comment)

type Echo[T ContextInterface] struct {
   xxxxxx
}
func (*Echo[T ContextInterface]) GET(path string, h HandlerFunc[T], m ...MiddlewareFunc[T]) *Route {
	return e.Add(http.MethodGet, path, h, m...)
}

func (e *Echo[T ContextInterface])  SetNewContextFunc(fn func(ec *Echo, pathParamAllocSize int) *T { 
  e.NewContextFunc = fn
}

type MyContext  struct {
  *echo.Context

   UserData Data
   XXXXX
}

// override QueryParam method
func (c *MyContext)  QueryParam(name string) string { 
 	return "prefix_" + c.Context.QueryParam(name) 
 } 
 
 
  // Echo instance
  e := echo.New[MyContext]()
 e.GET("/xxx", func(c *MyContext) error {
    xxxxx
 })
 

[BapiGso]

Would the V5 version happen to support broitil compression?

[aldas]

Brotli compression can be used in v4 it is not tied to v5. As it is 3rd party it will not be added to the core. I think someone has created PR with brotli which you could use https://github.com/labstack/echo/blob/a327810ef8a5625797ca6a106b538e5abec3917e/middleware/compress_brotli.go

p.s. I someone want to create their middleware library for it - we can at to library list in readme.md.

[jub0bs]

@aldas

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

I think this is a great move: it will free Echo developers to properly validate CORS configuration and report mistakes to callers. However, I think you should also get rid of middleware.CORSWithConfig. Is that on the cards?

[jub0bs]

I've just released a new CORS middleware library for Go. Some of the design ideas behind it might benefit Echo v5 😉

[aldas]

Would you like help by contributing code? or just link your library/blog every time #2534,#2535,#2400,#2471?

[jub0bs]

@aldas I sense some sarcasm/irritation... 🤔

I don't plan on contributing code to Echo; my time is limited and better spent elsewhere. However, I do think that Echo's CORS middleware could benefit from some of my ideas on the topic; ideas I happened to write about on my blog, so why not link to it rather than repeating myself or being handwavy?

Besides, since when does my commenting on GitHub imply that I'm going to contribute PRs? If this is a rule for Echo, then you should document it.

If you want me to stop commenting on Echo issues / PRs / discussions, just say so and I'll go away. 🤷

[aldas]

No, I do not want you to stop commenting and reporting.

Linking your blog pretty much as starter of every thread does not convey the image that this is done for purely samartian reasons. If you take the effort to go throuth the code, at least help us with trivial things (Wink-wink nod-nod) #2535 (comment) Your behavior is not Echo specific. Issues in Fiber, Chi CORS, Gin CORS all eventually lead back to your blog.

All these frameworks are eventually community effort where maintainers are curators and rely often contributions of other people that - that could know the subject matter better. I would like to knock on your concious and step-up your game and advertise yourself in addition to your blog post with PRs to fix the issues.

This is unfortunate as you are subject matter expert here. As you are already going quite deep into current implementation specifics and you have the knowledge and ability it would be most helpul if there would be PRs.

---

Would you be instered in wraping your CORS library into Echo middleware handle and release that MW as library? Then we could add it as 3rd party CORS library in Echo README and recommend it.

Or provide examples (if possible) for Fiber,Gin/Chi/Echo how to use your CORS library. And if it does not support support currently FastHTTP etc end maybe consider refactoring your functionality so that these could be used with minimal effort. To be copy/pasteable into/as middleware wrappers.

This would help all Go frameworks and be beneficial for you as people could link to your CORS as go-to solution.

---

Another idea - create somekind of CORS testsuite for servers (cli app maybe) that can check CORS setup for application under test. I remember that Websocket has that kind of testsuite to verify protocol compliance.

[jub0bs]

@aldas

Thanks for your reply.

All these frameworks are eventually community effort [...]

I occasionally do contribute to other CORS libraries, but only when familiarity and time allows. Research and highlighting issues is already time-consuming as it is; for instance, the post I keep linking to took me months of research into CORS itself and existing libraries. When it comes to fixing/improving things, perhaps based on the GitHub issues I've opened, I'm convinced that regular maintainers of Echo are in a better position than I to do that, should they wish to.

Would you be interested in wrapping your CORS library into Echo middleware handle and release that MW as library? Then we could add it as 3rd party CORS library in Echo README and recommend it.

I do like the idea of other libraries wrapping my own, but

• I don't think I would like to take on this maintenance burden myself,
• Echo's commitment to "callbacks" like AllowOriginFunc and friends doesn't seem compatible with such an approach.

Or provide examples (if possible) for Fiber,Gin/Chi/Echo how to use your CORS library.

I already do, at least for my old CORS library. I'm going to produce new examples for my new library.

Another idea [...]

Thanks for sharing that Autobahn project with me. It wasn't on my radar and does look interesting. I have similar ideas in mind:

• an offensive-security tool for dynamic detection of insecure CORS configurations, and
• a language-agnostic test suite for CORS middleware libraries.

Neither is ready for prime time yet, but I can ping you if/when they are, if you're interested.

[DeadInside1985]

Its possible to make this configurable? https://github.com/labstack/echo/blob/master/context.go#L396
In case there many files in one request 32mb not enough

[ippoippo]

Given that Go 1.22 has enhancements to net/http routing, will v5 make use of those enhancements.
I still prefer Echo's (and other frameworks do this) approach of having specific GET, POST, DELETE functions. However, those could now be implemented by simply(?) making use of the new router behaviour in net/http instead of using custom logic?

Same for how path parameters are handled.

I recently found https://github.com/go-michi/michi
(I'm not connected with the project, reason why I found it was because I am assessing whether my needs, and other project needs should be done with Echo or the std lib).
Michi seems to be following the path that the underlying router code should be used where possible, and not overlap.

[mei-rune]

fix #2485 and #2517 in the v5?

[mei-rune]

O！ it is already fix in the v5.

[fullgukbap]

Supports fiber config when creating instances on fiber.

Why not support echo in the same way?

[aldas]

Router has config in v5 and http.Server has its own config. Echo instance and Group are actually glorified wrappers to add routes - there are not much things to configure.

[apuatcfbd]

Hi, do you have any estimate of when v5 might be released?