Harden server lifecycle and require HTTP server config

Author: pitabwire

config/config.go

@@ -25,9 +25,17 @@ func (c contextKey) String() string {
 const (
 	ctxKeyConfiguration = contextKey("configurationKey")
 	httpStatusOKClass   = 2
+	bytesPerKiB         = 1024
 	// DefaultSlowQueryThresholdMilliseconds is defined in datastore_logger.go.
 
-	DefaultSlowQueryThreshold = 200 * time.Millisecond
+	DefaultSlowQueryThreshold     = 200 * time.Millisecond
+	defaultHTTPReadTimeout        = 30 * time.Second
+	defaultHTTPReadHeaderTimeout  = 5 * time.Second
+	defaultHTTPWriteTimeout       = 30 * time.Second
+	defaultHTTPIdleTimeout        = 90 * time.Second
+	defaultHTTPShutdownTimeout    = 15 * time.Second
+	defaultHTTPMaxHeaderKilobytes = 1024
+	defaultHTTPMaxHeaderBytes     = defaultHTTPMaxHeaderKilobytes * bytesPerKiB
 )
 
 // ToContext adds service configuration to the current supplied context.
@@ -77,6 +85,17 @@ func FillEnv(v any) error {
 	return env.Parse(v)
 }
 
+func parseDurationOrDefault(value string, fallback time.Duration) time.Duration {
+	if value != "" {
+		duration, err := time.ParseDuration(value)
+		if err == nil {
+			return duration
+		}
+	}
+
+	return fallback
+}
+
 type ConfigurationDefault struct {
 	LogLevel      string `envDefault:"info"                      env:"LOG_LEVEL"       yaml:"log_level"`
 	LogFormat     string `envDefault:"info"                      env:"LOG_FORMAT"      yaml:"log_format"`
@@ -106,9 +125,15 @@ type ConfigurationDefault struct {
 	DebugEndpointsEnabledValue  bool   `envDefault:"false"        env:"FRAME_DEBUG_ENDPOINTS"          yaml:"frame_debug_endpoints"`
 	DebugEndpointsBasePathValue string `envDefault:"/debug/frame" env:"FRAME_DEBUG_ENDPOINTS_BASEPATH" yaml:"frame_debug_endpoints_basepath"`
 
-	ServerPort     string `envDefault:":7000"  env:"PORT"      yaml:"server_port"`
-	HTTPServerPort string `envDefault:":8080"  env:"HTTP_PORT" yaml:"http_server_port"`
-	GrpcServerPort string `envDefault:":50051" env:"GRPC_PORT" yaml:"grpc_server_port"`
+	ServerPort     string `envDefault:":7000" env:"PORT"      yaml:"server_port"`
+	HTTPServerPort string `envDefault:":8080" env:"HTTP_PORT" yaml:"http_server_port"`
+
+	HTTPServerReadTimeout       string `envDefault:"30s"  env:"HTTP_SERVER_READ_TIMEOUT"        yaml:"http_server_read_timeout"`
+	HTTPServerReadHeaderTimeout string `envDefault:"5s"   env:"HTTP_SERVER_READ_HEADER_TIMEOUT" yaml:"http_server_read_header_timeout"`
+	HTTPServerWriteTimeout      string `envDefault:"30s"  env:"HTTP_SERVER_WRITE_TIMEOUT"       yaml:"http_server_write_timeout"`
+	HTTPServerIdleTimeout       string `envDefault:"90s"  env:"HTTP_SERVER_IDLE_TIMEOUT"        yaml:"http_server_idle_timeout"`
+	HTTPServerShutdownTimeout   string `envDefault:"15s"  env:"HTTP_SERVER_SHUTDOWN_TIMEOUT"    yaml:"http_server_shutdown_timeout"`
+	HTTPServerMaxHeaderBytes    int    `envDefault:"1024" env:"HTTP_SERVER_MAX_HEADER_KB"       yaml:"http_server_max_header_kb"`
 
 	// Worker pool settings
 	WorkerPoolCPUFactorForWorkerCount int    `envDefault:"10"  env:"WORKER_POOL_CPU_FACTOR_FOR_WORKER_COUNT" yaml:"worker_pool_cpu_factor_for_worker_count"`
@@ -292,7 +317,6 @@ func (c *ConfigurationDefault) ProfilerPort() string {
 type ConfigurationPorts interface {
 	Port() string
 	HTTPPort() string
-	GrpcPort() string
 }
 
 var _ ConfigurationPorts = new(ConfigurationDefault)
@@ -321,18 +345,6 @@ func (c *ConfigurationDefault) HTTPPort() string {
 	return ":8080"
 }
 
-func (c *ConfigurationDefault) GrpcPort() string {
-	if i, err := strconv.Atoi(c.GrpcServerPort); err == nil && i > 0 {
-		return fmt.Sprintf(":%s", strings.TrimSpace(c.GrpcServerPort))
-	}
-
-	if strings.HasPrefix(c.GrpcServerPort, ":") || strings.Contains(c.GrpcServerPort, ":") {
-		return c.GrpcServerPort
-	}
-
-	return c.Port()
-}
-
 type ConfigurationTelemetry interface {
 	DisableOpenTelemetry() bool
 	SamplingRatio() float64
@@ -380,6 +392,45 @@ func (c *ConfigurationDefault) GetExpiryDuration() time.Duration {
 	return time.Second
 }
 
+type ConfigurationHTTPServer interface {
+	HTTPReadTimeout() time.Duration
+	HTTPReadHeaderTimeout() time.Duration
+	HTTPWriteTimeout() time.Duration
+	HTTPIdleTimeout() time.Duration
+	HTTPShutdownTimeout() time.Duration
+	HTTPMaxHeaderBytes() int
+}
+
+var _ ConfigurationHTTPServer = new(ConfigurationDefault)
+
+func (c *ConfigurationDefault) HTTPReadTimeout() time.Duration {
+	return parseDurationOrDefault(c.HTTPServerReadTimeout, defaultHTTPReadTimeout)
+}
+
+func (c *ConfigurationDefault) HTTPReadHeaderTimeout() time.Duration {
+	return parseDurationOrDefault(c.HTTPServerReadHeaderTimeout, defaultHTTPReadHeaderTimeout)
+}
+
+func (c *ConfigurationDefault) HTTPWriteTimeout() time.Duration {
+	return parseDurationOrDefault(c.HTTPServerWriteTimeout, defaultHTTPWriteTimeout)
+}
+
+func (c *ConfigurationDefault) HTTPIdleTimeout() time.Duration {
+	return parseDurationOrDefault(c.HTTPServerIdleTimeout, defaultHTTPIdleTimeout)
+}
+
+func (c *ConfigurationDefault) HTTPShutdownTimeout() time.Duration {
+	return parseDurationOrDefault(c.HTTPServerShutdownTimeout, defaultHTTPShutdownTimeout)
+}
+
+func (c *ConfigurationDefault) HTTPMaxHeaderBytes() int {
+	if c.HTTPServerMaxHeaderBytes > 0 {
+		return c.HTTPServerMaxHeaderBytes * bytesPerKiB
+	}
+
+	return defaultHTTPMaxHeaderBytes
+}
+
 type ConfigurationOAUTH2 interface {
 	LoadOauth2Config(ctx context.Context) error
 	GetOauth2WellKnownOIDC() string

config/config_test.go

@@ -98,7 +98,6 @@ func (s *ConfigSuite) TestFallbacksTable() {
 		cfg         ConfigurationDefault
 		wantPort    string
 		wantHTTP    string
-		wantGRPC    string
 		wantProfile string
 		wantExpiry  time.Duration
 	}{
@@ -107,13 +106,11 @@ func (s *ConfigSuite) TestFallbacksTable() {
 			cfg: ConfigurationDefault{
 				ServerPort:               "7000",
 				HTTPServerPort:           "8080",
-				GrpcServerPort:           "50051",
 				ProfilerPortAddr:         ":6600",
 				WorkerPoolExpiryDuration: "1500ms",
 			},
 			wantPort:    ":7000",
 			wantHTTP:    ":8080",
-			wantGRPC:    ":50051",
 			wantProfile: ":6600",
 			wantExpiry:  1500 * time.Millisecond,
 		},
@@ -122,13 +119,11 @@ func (s *ConfigSuite) TestFallbacksTable() {
 			cfg: ConfigurationDefault{
 				ServerPort:               "invalid",
 				HTTPServerPort:           "invalid",
-				GrpcServerPort:           "invalid",
 				ProfilerPortAddr:         "",
 				WorkerPoolExpiryDuration: "invalid",
 			},
 			wantPort:    ":80",
 			wantHTTP:    ":8080",
-			wantGRPC:    ":80",
 			wantProfile: ":6060",
 			wantExpiry:  time.Second,
 		},
@@ -137,12 +132,10 @@ func (s *ConfigSuite) TestFallbacksTable() {
 			cfg: ConfigurationDefault{
 				ServerPort:               "0.0.0.0:7000",
 				HTTPServerPort:           ":8088",
-				GrpcServerPort:           "127.0.0.1:50052",
 				WorkerPoolExpiryDuration: "1s",
 			},
 			wantPort:    "0.0.0.0:7000",
 			wantHTTP:    ":8088",
-			wantGRPC:    "127.0.0.1:50052",
 			wantProfile: ":6060",
 			wantExpiry:  time.Second,
 		},
@@ -152,13 +145,44 @@ func (s *ConfigSuite) TestFallbacksTable() {
 		s.Run(tc.name, func() {
 			s.Equal(tc.wantPort, tc.cfg.Port())
 			s.Equal(tc.wantHTTP, tc.cfg.HTTPPort())
-			s.Equal(tc.wantGRPC, tc.cfg.GrpcPort())
 			s.Equal(tc.wantProfile, tc.cfg.ProfilerPort())
 			s.Equal(tc.wantExpiry, tc.cfg.GetExpiryDuration())
 		})
 	}
 }
 
+func (s *ConfigSuite) TestHTTPServerSettings() {
+	cfg := &ConfigurationDefault{
+		HTTPServerReadTimeout:       "31s",
+		HTTPServerReadHeaderTimeout: "6s",
+		HTTPServerWriteTimeout:      "32s",
+		HTTPServerIdleTimeout:       "91s",
+		HTTPServerShutdownTimeout:   "16s",
+		HTTPServerMaxHeaderBytes:    2048,
+	}
+
+	s.Equal(31*time.Second, cfg.HTTPReadTimeout())
+	s.Equal(6*time.Second, cfg.HTTPReadHeaderTimeout())
+	s.Equal(32*time.Second, cfg.HTTPWriteTimeout())
+	s.Equal(91*time.Second, cfg.HTTPIdleTimeout())
+	s.Equal(16*time.Second, cfg.HTTPShutdownTimeout())
+	s.Equal(2048*1024, cfg.HTTPMaxHeaderBytes())
+
+	cfg.HTTPServerReadTimeout = "invalid"
+	cfg.HTTPServerReadHeaderTimeout = "invalid"
+	cfg.HTTPServerWriteTimeout = "invalid"
+	cfg.HTTPServerIdleTimeout = "invalid"
+	cfg.HTTPServerShutdownTimeout = "invalid"
+	cfg.HTTPServerMaxHeaderBytes = 0
+
+	s.Equal(30*time.Second, cfg.HTTPReadTimeout())
+	s.Equal(5*time.Second, cfg.HTTPReadHeaderTimeout())
+	s.Equal(30*time.Second, cfg.HTTPWriteTimeout())
+	s.Equal(90*time.Second, cfg.HTTPIdleTimeout())
+	s.Equal(15*time.Second, cfg.HTTPShutdownTimeout())
+	s.Equal(1024*1024, cfg.HTTPMaxHeaderBytes())
+}
+
 func (s *ConfigSuite) TestDatabaseAndEventConfig() {
 	cfg := &ConfigurationDefault{
 		DatabasePrimaryURL:                   []string{"postgres://primary"},

docs/architecture.md

@@ -9,7 +9,7 @@ Frame is a fast, extensible Go framework built around a minimal core `Service` a
 
 ## Mental Model
 
-Frame bootstraps a `Service` that owns shared runtime state and managers. Options configure the service and register startup hooks. The service then starts HTTP/gRPC servers, background workers, and pluggable components.
+Frame bootstraps a `Service` that owns shared runtime state and managers. Options configure the service and register startup hooks. The service then starts the HTTP server, background workers, and pluggable components.
 
 ```
 ctx, svc := frame.NewService(
@@ -49,15 +49,16 @@ Run
   -> validate startup errors
   -> initialize queue manager
   -> start background consumer (if configured)
-  -> start HTTP/gRPC server(s)
+  -> start HTTP server
   -> start profiler (if enabled)
   -> execute startup hooks
   -> block until shutdown or error
 
 Stop
+  -> drain HTTP server
   -> stop profiler
-  -> cancel service context
   -> run cleanup hooks
+  -> cancel service context
 ```
 
 ## Extension Points (Plugin Architecture)

docs/examples.md

@@ -7,11 +7,6 @@ These examples are small, compilable, and use the canonical Frame bootstrap patt
 - Path: `examples/http-basic`
 - Run: `go run ./examples/http-basic`
 
-## gRPC Basic
-
-- Path: `examples/grpc-basic`
-- Run: `go run ./examples/grpc-basic`
-
 ## Queue Basic
 
 - Path: `examples/queue-basic`

docs/getting-started.md

@@ -66,21 +66,16 @@ import (
     "net/http"
 
     "github.com/pitabwire/frame"
-    "google.golang.org/grpc"
 )
 
 func main() {
-    grpcServer := grpc.NewServer()
-
     http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
         w.Write([]byte("HTTP ok"))
     })
 
     ctx, svc := frame.NewService(
         frame.WithName("hello"),
         frame.WithHTTPHandler(http.DefaultServeMux),
-        frame.WithGRPCServer(grpcServer),
-        frame.WithGRPCPort(":50051"),
     )
 
     if err := svc.Run(ctx, ":8080"); err != nil {

docs/server.md

@@ -1,6 +1,6 @@
-# HTTP and gRPC Server
+# HTTP Server
 
-Frame provides an HTTP server with optional gRPC sidecar support. The server layer is configured via `Service` options and environment-based config interfaces.
+Frame provides an HTTP server with configurable lifecycle and transport limits. The server layer is configured via `Service` options and environment-based config interfaces.
 
 ## HTTP Server Basics
 
@@ -40,24 +40,6 @@ _ = svc.Run(ctx, ":8080")
 - Default path: `/healthz`
 - Register custom checks using `AddHealthCheck`.
 
-## gRPC Server
-
-```go
-grpcServer := grpc.NewServer()
-
-ctx, svc := frame.NewService(
-    frame.WithHTTPHandler(http.DefaultServeMux),
-    frame.WithGRPCServer(grpcServer),
-    frame.WithGRPCPort(":50051"),
-)
-
-_ = svc.Run(ctx, ":8080")
-```
-
-Optional:
-- `WithEnableGRPCServerReflection()`
-- `WithGRPCServerListener(listener net.Listener)`
-
 ## HTTP/2 Support
 
 Frame configures HTTP/2 support automatically:
@@ -82,12 +64,13 @@ type ServerDriver interface {
 
 You can inject a custom driver with `WithDriver` for testing or custom transport.
 
-## Default HTTP Timeouts
-
-These defaults are hard-coded in `service.go`:
+## Default HTTP Limits
 
-- Read timeout: 5s
-- Write timeout: 10s
-- Idle timeout: 90s
+These defaults are configurable via `config.ConfigurationHTTPServer` and environment variables:
 
-Adjust by supplying a custom driver.
+- `HTTP_SERVER_READ_TIMEOUT=30s`
+- `HTTP_SERVER_READ_HEADER_TIMEOUT=5s`
+- `HTTP_SERVER_WRITE_TIMEOUT=30s`
+- `HTTP_SERVER_IDLE_TIMEOUT=90s`
+- `HTTP_SERVER_SHUTDOWN_TIMEOUT=15s`
+- `HTTP_SERVER_MAX_HEADER_KB=1024`

docs/service.md

@@ -22,7 +22,7 @@ ctx, svc := frame.NewServiceWithContext(ctx, frame.WithName("orders"))
 ## Service Lifecycle
 
 - `NewService` applies options and initializes core managers.
-- `Run` starts HTTP/gRPC servers, background processing, and startup hooks.
+- `Run` starts the HTTP server, background processing, and startup hooks.
 - `Stop` executes cleanup and shuts down gracefully.
 
 ### Startup Hooks (Ordering Matters)
@@ -65,11 +65,7 @@ Service options are composable and can be applied at construction or later via `
 
 - `WithHTTPHandler(h http.Handler)`
 - `WithHTTPMiddleware(mw ...func(http.Handler) http.Handler)`
-- `WithGRPCServer(grpcServer *grpc.Server)`
-- `WithGRPCPort(port string)`
-- `WithEnableGRPCServerReflection()`
-- `WithGRPCServerListener(listener net.Listener)`
-- `WithDriver(driver ServerDriver)`
+- `WithDriver(driver server.Driver)`
 
 ### Configuration and Logging
 
@@ -133,4 +129,3 @@ Health checks are registered using `AddHealthCheck`, and are served on `/healthz
 
 - Startup errors are collected via `AddStartupError` and returned when `Run` is called.
 - `ErrorIsNotFound(err)` helps normalize "not found" checks across data, gRPC, and HTTP.
-