README
¶
Modulex httpx HTTP Adapter
This package provides net/http glue for Modulex's health (liveness) and
readiness checks, plus a managed *http.Server lifecycle. It depends only on
net/http and the core modulex package — no third-party router — so the
core modulex package can stay free of HTTP dependencies (the same pattern
used by modulex/chi).
Usage
import (
"net/http"
"time"
"github.com/mediusfy/modulex/httpx"
)
mux := http.NewServeMux()
mux.HandleFunc("/healthz", httpx.HealthHandler(manager))
mux.HandleFunc("/readyz", httpx.ReadinessHandler(manager))
server := &http.Server{Addr: ":8080", Handler: mux}
handle, err := httpx.Serve(ctx, manager, "http-server", server, 10*time.Second)
if err != nil {
return err
}
// handle.Wait() blocks until the server has shut down cleanly or failed.
manager is anything implementing modulex.HealthCheckProvider /
modulex.ReadinessProvider (a *modulex.Manager satisfies both) and
modulex.TaskSpawner.
Behavior
HealthHandler(p modulex.HealthCheckProvider)runs every registered health (liveness) check concurrently, each bounded by the incoming request's deadline or a 5-second default when the request carries none. It responds200 {"status":"ok","checks":{...}}if every check passes, or503 {"status":"unhealthy","checks":{...}}if any fail. Every registered check appears inchecks, with"ok"for passes and the check's error message for failures.ReadinessHandler(p modulex.ReadinessProvider)behaves identically, sourced fromReadinessChecks()instead, using"ready"/"not-ready"in place of"ok"/"unhealthy".Serve(ctx, spawner, name, server, shutdownTimeout)spawnsserver.ListenAndServe()as a supervised task viamodulex.TaskSpawner.Go, and gracefully callsserver.ShutdownwithshutdownTimeoutwhen eitherctxor the manager's own shutdown fires first.http.ErrServerClosedis treated as a clean exit, not an error — it surfaces as a nil error from the returned*modulex.TaskHandle'sWait().
Why this exists
Every HTTP-serving consumer of Modulex ends up hand-writing the same
boilerplate: run health/readiness checks and marshal them to JSON, and spawn
ListenAndServe alongside a select on context cancellation that calls
Shutdown with a timeout. httpx factors that out once so modules only need
to register named check functions and call Serve.
Testing
go test ./httpx/...
Documentation
¶
Overview ¶
Package httpx provides HTTP glue for Modulex health and readiness checks, plus a managed net/http.Server lifecycle, without pulling net/http into the core modulex package.
Modulex's core Registry abstracts health (liveness) and readiness checks as named functions (see modulex.HealthCheckRegistrar and modulex.ReadinessRegistrar), but deliberately stays free of HTTP dependencies. This package exists for consumers that expose those checks over HTTP:
- HealthHandler serves the aggregated result of every registered health (liveness) check. A failing check means the process should be restarted.
- ReadinessHandler serves the aggregated result of every registered readiness check. A failing check means the instance should be pulled from load balancing, not restarted.
- Serve spawns a *http.Server via a modulex.TaskSpawner and shuts it down gracefully when the supplied context is cancelled, removing the "ListenAndServe + select + Shutdown" boilerplate every HTTP-serving consumer would otherwise hand-write.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HealthHandler ¶
func HealthHandler(p modulex.HealthCheckProvider) http.HandlerFunc
HealthHandler returns an http.HandlerFunc that runs every health (liveness) check registered on p concurrently and reports the aggregate result as JSON.
It responds 200 with {"status":"ok","checks":{...}} if every check passes, or 503 with {"status":"unhealthy","checks":{...}} if any check fails. The checks map always lists every registered check, with a value of "ok" for passing checks and the check's error message for failing ones.
A failing health check means the process is broken and should be restarted; wire this handler to an orchestrator's liveness probe.
func ReadinessHandler ¶
func ReadinessHandler(p modulex.ReadinessProvider) http.HandlerFunc
ReadinessHandler returns an http.HandlerFunc that runs every readiness check registered on p concurrently and reports the aggregate result as JSON.
It responds 200 with {"status":"ready","checks":{...}} if every check passes, or 503 with {"status":"not-ready","checks":{...}} if any check fails. The checks map always lists every registered check, with a value of "ok" for passing checks and the check's error message for failing ones.
A failing readiness check means the instance should be pulled from load balancing, not restarted; wire this handler to an orchestrator's readiness probe.
func Serve ¶
func Serve(ctx context.Context, spawner modulex.TaskSpawner, name string, server *http.Server, shutdownTimeout time.Duration) (*modulex.TaskHandle, error)
Serve spawns server.ListenAndServe as a supervised background task via spawner.Go under the given name, and gracefully shuts the server down with shutdownTimeout when ctx is cancelled.
A modulex.TaskSpawner derives the context its task function runs with from the manager's own lifecycle, not from ctx, so Serve also watches the task's context: shutdown is triggered by whichever of ctx or the manager's shutdown happens first. This means Serve responds correctly both to an explicit caller cancellation and to modulex.Manager.StopModules.
http.ErrServerClosed is treated as a clean exit, not an error: both a natural server exit and a Shutdown-triggered exit surface as a nil error from the returned TaskHandle's Wait. Any other error from ListenAndServe, or a Shutdown that does not complete within shutdownTimeout, is returned by Wait.
Serve exists to remove the repeated "spawn ListenAndServe, select on ctx.Done, Shutdown with a timeout" boilerplate that HTTP-serving consumers of modulex would otherwise hand-write for every service.
Types ¶
This section is empty.
Source Files