timeout

README

Timeout

[!NOTE] This repository has been transferred from github.com/tigerwill90/foxtimeout to github.com/fox-toolkit/timeout. Existing users should update their imports and go.mod accordingly.

Timeout is a middleware for Fox which ensure that a handler do not exceed the configured timeout limit.

Disclaimer

Timeout's API is closely tied to the Fox router, and it will only reach v1 when the router is stabilized. During the pre-v1 phase, breaking changes may occur and will be documented in the release notes.

Getting started

Installation

go get -u github.com/fox-toolkit/timeout

Feature

• Allows for custom timeout response to better suit specific use cases.
• Tightly integrates with the Fox ecosystem for enhanced performance and scalability.
• Supports dynamic timeout configuration on a per-route & per-request basis using custom Resolver.

Usage

package main

import (
	"errors"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/fox-toolkit/fox"
	"github.com/fox-toolkit/timeout"
)

func main() {
	f := fox.MustRouter(
		fox.DefaultOptions(),
		fox.WithMiddleware(
			timeout.Middleware(2*time.Second),
		),
	)

	f.MustAdd(fox.MethodGet, "/hello/{name}", func(c *fox.Context) {
		_ = c.String(http.StatusOK, fmt.Sprintf("Hello %s\n", c.Param("name")))
	})
	// Disable timeout the middleware for this route
	f.MustAdd(fox.MethodGet, "/download/{filepath}", DownloadHandler, timeout.OverrideHandler(timeout.NoTimeout))
	// Use 15s timeout instead of the global 2s for this route
	f.MustAdd(fox.MethodGet, "/workflow/{id}/start", WorkflowHandler, timeout.OverrideHandler(15*time.Second))

	if err := http.ListenAndServe(":8080", f); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatalln(err)
	}
}

Documentation

Index

• Constants
• func DefaultTimeoutResponse(c *fox.Context)
• func Middleware(dt time.Duration, opts ...Option) fox.MiddlewareFunc
• func OverrideHandler(dt time.Duration) fox.RouteOption
• func OverrideRead(dt time.Duration) fox.RouteOption
• func OverrideWrite(dt time.Duration) fox.RouteOption
• type Option
  • func WithResponse(h fox.HandlerFunc) Option
• type Timeout

Examples

• OverrideHandler

Constants

const NoTimeout = time.Duration(0)

Functions

func DefaultTimeoutResponse

func DefaultTimeoutResponse(c *fox.Context)

DefaultTimeoutResponse sends a default 503 Service Unavailable response.

func Middleware

func Middleware(dt time.Duration, opts ...Option) fox.MiddlewareFunc

Middleware returns a fox.MiddlewareFunc that runs handlers with the given time limit.

The middleware calls the next handler to handle each request, but if a call runs for longer than its time limit, the handler responds with a 503 Service Unavailable error and the given message in its body (if a custom response handler is not configured). After such a timeout, writes by the handler to its ResponseWriter will return http.ErrHandlerTimeout.

The timeout middleware supports the http.Pusher interface but does not support the http.Hijacker or http.Flusher interfaces.

Individual routes can override the timeout duration using the OverrideHandler option. It's also possible to set the read and write deadline for individual route using the OverrideRead and OverrideWrite option. If dt <= 0 (or NoTimeout), this is a passthrough middleware but per-route options remain effective.

func OverrideHandler

func OverrideHandler(dt time.Duration) fox.RouteOption

OverrideHandler returns a RouteOption that sets a custom timeout duration for a specific route. This allows individual routes to have different timeout values than the global timeout. Passing a value <= 0 (or NoTimeout) disables the timeout for this route.

Example

f, err := fox.NewRouter(
	fox.WithMiddleware(Middleware(2 * time.Second)),
)
if err != nil {
	panic(err)
}

f.MustAdd(fox.MethodGet, "/hello/{name}", func(c *fox.Context) {
	_ = c.String(http.StatusOK, fmt.Sprintf("hello %s\n", c.Param("name")))
})

f.MustAdd(fox.MethodGet, "/long", func(c *fox.Context) {
	time.Sleep(10 * time.Second)
	c.Writer().WriteHeader(http.StatusOK)
}, OverrideHandler(12*time.Second))

f.MustAdd(fox.MethodGet, "/no-timeout", func(c *fox.Context) {
	c.Writer().WriteHeader(http.StatusOK)
}, OverrideHandler(NoTimeout))

func OverrideRead

func OverrideRead(dt time.Duration) fox.RouteOption

OverrideRead returns a RouteOption that sets the read deadline for the underlying connection. This controls how long the server will wait before timing out while reading the request body.

func OverrideWrite

func OverrideWrite(dt time.Duration) fox.RouteOption

OverrideWrite returns a RouteOption that sets the write deadline for the underlying connection. This controls how long the server will wait before timing out writes to the client.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithResponse

func WithResponse(h fox.HandlerFunc) Option

WithResponse sets a custom response handler function for the middleware. This function will be invoked when a timeout occurs, allowing for custom responses to be sent back to the client. If not set, the middleware use DefaultTimeoutResponse.

type Timeout

type Timeout struct {
	// contains filtered or unexported fields
}

Timeout is a middleware that ensure HTTP handlers don't exceed the configured timeout duration.