Documentation
¶
Overview ¶
Package web is a hex-opinionated wrapper around labstack/echo/v4.
A Server owns an *echo.Echo instance pre-wired with the hex-standard middleware stack (request ID, panic recovery, CORS, structured logging through hex/log) and health/readiness endpoints. Consumers register routes on the underlying echo instance via Echo().
See ADR-0006 for scope decisions: hex/web is medium-scope. It owns the server, middleware, health endpoints, and graceful shutdown. It does not prescribe controller/router directory conventions.
Example:
srv := web.New(web.Options{Address: ":8080"})
srv.Echo().GET("/hello", func(c echo.Context) error {
return c.String(200, "hi")
})
if err := srv.Start(); err != nil { return err }
defer srv.Shutdown(ctx)
The Server satisfies hex/provider.Shutdowner so a consumer provider can register the server and have shutdown wired automatically.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Address is the listen address (e.g. ":8080", "127.0.0.1:3000").
// Defaults to ":8080".
Address string
// ReadTimeout, WriteTimeout, IdleTimeout configure the underlying
// net/http server. Zero uses echo's defaults (no timeout).
ReadTimeout time.Duration
WriteTimeout time.Duration
IdleTimeout time.Duration
// HealthPath is the route that reports application liveness. Defaults
// to "/healthz". Set to "" to disable.
HealthPath string
// ReadyPath is the route that reports application readiness. Defaults
// to "/readyz". Set to "" to disable.
ReadyPath string
// ReadyFn is invoked on ReadyPath. Return nil for 200 OK, or an error
// to render 503 with the error text. If nil, ReadyPath always returns
// 200.
ReadyFn func(context.Context) error
// CORS toggles the default CORS middleware. Defaults to true. Pass
// CORSConfig to customise; the default allows all origins/methods.
CORS bool
CORSConfig *echomw.CORSConfig
// DisableRequestID skips the RequestID middleware.
DisableRequestID bool
// DisableRecover skips the panic-recovery middleware. Do not disable
// in production.
DisableRecover bool
// DisableLogger skips the hex-log request logger middleware.
DisableLogger bool
}
Options configures a new Server. All fields are optional; the zero value yields a Server listening on :8080 with the full middleware stack.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a hex HTTP server. Zero value is not usable; call New.
func New ¶
New constructs a Server with the hex-standard middleware stack applied. The server is not yet listening; call Start.
Default middleware, in order: RequestID, request logger (hex/log), Recover. CORS is opt-in via Options.CORS or Options.CORSConfig — many hex services are internal-only and do not need it.
func (*Server) Echo ¶
Echo returns the underlying *echo.Echo instance. Use this to register routes, groups, and additional middleware.
func (*Server) Shutdown ¶
Shutdown gracefully stops the server, waiting up to ctx's deadline for in-flight requests to complete.
func (*Server) Start ¶
Start begins listening on the configured address. Start blocks until the server stops. Use it in a goroutine and pair with Shutdown.
Start returns http.ErrServerClosed when Shutdown is invoked normally. Callers should treat that as success:
if err := srv.Start(); err != nil && !errors.Is(err, http.ErrServerClosed) {
return err
}
Source Files
Directories