httpserver

Documentation

Index

• Constants
• type Config
• type IRunner
  • func NewHttpServer(cfg Config) IRunner

Examples

• NewHttpServer
• NewHttpServer (CustomTimeouts)
• NewHttpServer (Tls)

Constants

const (

	// recommended graceful shutdown timeout for Runner.shutdown ctx; not enforced internally
	DefaultShutdownTimeout = 10 * time.Second

	// NoWriteTimeout, passed as Config.WriteTimeout, disables the write
	// timeout entirely (e.g. for a large file download endpoint). The Go
	// zero value can't be used for this — resolve() already treats a zero
	// WriteTimeout as "not set", replacing it with defaultWriteTimeout — so
	// this uses a negative duration instead. net/http.Server treats any
	// zero-or-negative WriteTimeout identically (it only ever calls
	// SetWriteDeadline when WriteTimeout > 0), so this is exactly as
	// unlimited as a literal 0 would be if net/http saw it directly.
	NoWriteTimeout = -1 * time.Nanosecond
)

Default HTTP server timeout values. NOTE on WriteTimeout: net/http.Server treats a zero-or-negative WriteTimeout as "no limit" (required for large file downloads — a non-zero WriteTimeout applies to the entire response write duration and will kill long-running file transfers server-side regardless of the client's own timeout settings). But Config's own zero value already means "not set, apply the default" for every duration field via resolve() below, so a literal 0 can't reach net/http as "no limit" — passing it just gets overwritten by defaultWriteTimeout. Use NoWriteTimeout instead to request no limit explicitly; see its doc comment.

Types

type Config

type Config struct {
	Port    string // TCP port to listen on, e.g. "8080"
	CrtFile string // TLS certificate file path; empty disables TLS
	KeyFile string // TLS private key file path; empty disables TLS

	ReadTimeout       time.Duration // default: 30s
	WriteTimeout      time.Duration // default: 60s; pass NoWriteTimeout for unlimited (e.g. file downloads)
	IdleTimeout       time.Duration // default: 120s
	ReadHeaderTimeout time.Duration // default: 10s
}

Config holds all configuration for the HTTP server runner. Zero values for duration fields fall back to the package defaults above, except WriteTimeout — see NoWriteTimeout to explicitly request no limit. CrtFile and KeyFile must both be non-empty to enable TLS.

type IRunner

type IRunner interface {
	// Start starts the server and blocks until it is stopped.
	// Returns nil after a graceful shutdown; returns a non-nil error on failure.
	Start(handler http.Handler) error

	// Shutdown gracefully stops the server, waiting for in-flight requests to complete until ctx is cancelled or times out.
	Shutdown(ctx context.Context) error
}

IRunner abstracts a server that can be started and gracefully stopped. The two concrete implementations are:

• httpRunner (this package) — plain HTTP/HTTPS server
• httpserver/lambda.NewHttpServer() — AWS Lambda adapter (unexported lambdaRunner)

Import httpserver/lambda only when Lambda support is required; it carries the AWS SDK dependencies and does not affect callers that only need HTTP.

func NewHttpServer

func NewHttpServer(cfg Config) IRunner

NewHttpServer returns a plain HTTP/HTTPS IRunner configured by cfg. Zero-value duration fields in cfg fall back to the package defaults. For AWS Lambda mode import and use the httpserver/lambda subpackage instead.

Example

ExampleNewHttpServer shows how to create a plain HTTP runner and start the server. The caller is responsible for reading the port (and optional TLS paths) from configuration (e.g. env.Env()) at the composition root.

package main

import (
	"fmt"

	"github.com/phcp-tech/common-library-golang/httpserver"
)

func main() {
	runner := httpserver.NewHttpServer(httpserver.Config{
		Port: "8080",
	})
	fmt.Println(runner != nil)
}

Output:
true

Example (CustomTimeouts)

ExampleNewHttpServer_customTimeouts shows how to override the default timeout values. Zero-value duration fields fall back to the package defaults: ReadTimeout=30s, WriteTimeout=60s, IdleTimeout=120s, ReadHeaderTimeout=10s. WriteTimeout is the one exception: its own zero value can't mean "unlimited" here, since resolve() already uses zero to mean "not set, apply the default" — pass NoWriteTimeout instead to allow unlimited response time (e.g. file downloads).

package main

import (
	"fmt"

	"time"

	"github.com/phcp-tech/common-library-golang/httpserver"
)

func main() {
	runner := httpserver.NewHttpServer(httpserver.Config{
		Port:              "8080",
		ReadTimeout:       15 * time.Second,
		WriteTimeout:      httpserver.NoWriteTimeout, // unlimited — required for file downloads
		IdleTimeout:       60 * time.Second,
		ReadHeaderTimeout: 5 * time.Second,
	})
	fmt.Println(runner != nil)
}

Output:
true

Example (Tls)

ExampleNewHttpServer_tls shows how to enable HTTPS with custom TLS certificate files. CrtFile and KeyFile must both be non-empty to activate TLS.

package main

import (
	"fmt"

	"github.com/phcp-tech/common-library-golang/httpserver"
)

func main() {
	runner := httpserver.NewHttpServer(httpserver.Config{
		Port:    "8443",
		CrtFile: "/etc/ssl/server.crt",
		KeyFile: "/etc/ssl/server.key",
	})
	fmt.Println(runner != nil)
}

Output:
true