1 Release 1 Tag

RSS Feed

• v0.9.0 1ec0780f72

  Compare

  Release v0.9.0 Stable

  Rene Nochebuena released this 2026-03-19 07:40:35 -06:00 | 0 commits to main since this release

  v0.9.0

  code.nochebuena.dev/go/httpserver

  Overview

  httpserver provides a lifecycle-managed HTTP server built on chi v5. It implements
  launcher.Component (OnInit → OnStart → OnStop) and embeds chi.Router directly,
  so a single value serves both as a lifecycle component and as the router for all route
  registration.

  This release reflects an API designed through multiple architecture reviews and
  validated end-to-end via the todo-api POC. It is versioned at v0.9.0 rather than
  v1.0.0 because it has not yet been exercised in production workloads across all edge
  cases, preserving the option for minor API refinements before committing to full
  stability.

  What's Included

  New(logger Logger, cfg Config, opts ...Option) HttpServerComponent

  Constructs the server component. No middleware is installed by default; the full
  middleware stack is composed explicitly at construction time via WithMiddleware.

  HttpServerComponent interface

  Embeds both launcher.Component and chi.Router, giving callers the complete chi
  routing API (Get, Post, Route, Mount, Use, With, Group, etc.) on the
  same value that participates in the launcher lifecycle.

  Config struct

  Field	Env var	Default
  Host	SERVER_HOST	0.0.0.0
  Port	SERVER_PORT	8080
  ReadTimeout	SERVER_READ_TIMEOUT	5s
  WriteTimeout	SERVER_WRITE_TIMEOUT	10s
  IdleTimeout	SERVER_IDLE_TIMEOUT	120s

  WithMiddleware(mw ...func(http.Handler) http.Handler) Option

  Accumulates middleware applied to the root router during OnInit. Order is
  preserved and caller-controlled.

  Logger interface

  Duck-typed: requires only Info(msg string, args ...any) and
  Error(msg string, err error, args ...any). logz.Logger satisfies this directly.

  Lifecycle

  • OnInit — applies registered middleware to the router
  • OnStart — starts http.ListenAndServe in a background goroutine
  • OnStop — calls http.Server.Shutdown with a 10-second context timeout; in-flight requests have up to 10 seconds to complete

  Installation

  go get code.nochebuena.dev/go/httpserver@v0.9.0
  

  Requires code.nochebuena.dev/go/launcher and github.com/go-chi/chi/v5.

  Design Highlights

  chi over other frameworks. chi uses stdlib http.Handler everywhere. Every
  middleware in the micro-lib stack (httpmw) and every handler adapter (httputil)
  uses http.Handler/http.ResponseWriter/*http.Request natively. No wrapper
  code is required at any boundary.

  Embedded chi.Router. HttpServerComponent embeds chi.Router directly in the
  interface. Callers get the full routing API without delegation or wrapper methods.
  Route registration and lifecycle management happen on the same value.

  No default middleware. New() installs nothing. The middleware stack is composed
  explicitly with WithMiddleware(...) at construction time, keeping the stack visible
  and ordering unambiguous in the application source.

  Duck-typed Logger. The two-method Logger interface avoids a hard dependency on
  logz. Any struct with Info and Error methods satisfies it, including test stubs
  and application-local adapters.

  Known Limitations & Edge Cases

  • No TLS/HTTPS support. The server binds with http.ListenAndServe only. TLS
    termination is expected at the infrastructure layer (reverse proxy, load balancer).
  • The graceful shutdown drain timeout (10 seconds) is hardcoded in OnStop and is
    not configurable via Config or Option. Long-running streaming requests may be
    cut short if they exceed this window.
  • Middleware registered via srv.Use(mw) after OnInit has run may not behave as
    expected depending on chi's internal router state. All middleware should be
    provided via WithMiddleware at construction time.

  v0.9.0 → v1.0.0 Roadmap

  • Make the graceful shutdown timeout configurable (e.g., WithShutdownTimeout)
  • Evaluate optional TLS support via a WithTLS(certFile, keyFile string) Option
  • Production hardening: validate behavior under high concurrency and slow-client scenarios
  • Consider exposing a ServeHTTP method to enable embedding the server in test suites without binding a real port

  Downloads

  • Source Code (ZIP)
  • Source Code (TAR.GZ)