ContextTimeout Middleware is undocumented

[akhayyat]

I cannot find any mention of the ContextTimeout middleware in the documentation.

At the same time, a number of issues as well as the Timeout middleware source code warns against it, but no such warning is present in the documentation.

1. Any reason the documentation only lists the recommended-against Timeout middleware?
2. Would it be possible to document the recommended ContextTimeout middleware, perhaps with a usage example showing what the handler should look like to leverage the ContextTimeout?

[aldas]

ContextTimeout middleware replaces Request context with context that has timeout configured to it. This is useful for situations when you would want long running processes not to last longer than configured timeout. Maybe you have some kind of SQL reporting query that could take really long time under when SQL server is overloaded. by providing context that limits is duration you can assure that your clients will not wait longer than that time. as that SQL method call will end with context.DeadlineExceeded error.

echo/middleware/context_timeout.go

Lines 59 to 72 in ce0b12a

	return func(c echo.Context) error {
	if config.Skipper(c) {
	return next(c)
	}
	timeoutContext, cancel := context.WithTimeout(c.Request().Context(), config.Timeout)
	defer cancel()
	c.SetRequest(c.Request().WithContext(timeoutContext))
	if err := next(c); err != nil {
	return config.ErrorHandler(err, c)
	}
	return nil

this is conceptually different from Timeout middleware as Timeout middleware does not end your SQL call. Timeout MW will just send response to client that request timeoutted but that request will actually will be still running in separate goroutine on your server and will end when handler finishes. Most of the time you do not need this kind of behaviour - maybe only in situations when you need to commit transactions regardless if clients sees that or not.

[akhayyat]

Thank you for the explanation. I understand the difference and agree with the recommendation. My question was: why is ContextTimeout (and the difference and use cases of the two middleware) not documented?

[aldas]

there are no specific reason why ContextTimeout is not documented. I has been forgotten. I am thinking why have we not removed https://echo.labstack.com/docs/middleware/timeout as we actually do not want to advertise that middleware.