README
¶
minimal
The smallest correct service built on this package, and the one to copy.
It imports the standard library, Echo and this package. Nothing else. In
particular it does not import github.com/zionmedianetwork/logam: the logger is
log/slog, adapted to server.Logger by three one-line methods, because
running this library requires no logging dependency at all.
The logger, which is the only thing you have to supply
NewHTTP takes a server.Logger, and that interface is three methods:
type Logger interface {
Infow(msg string, keysAndValues ...interface{})
Warnw(msg string, keysAndValues ...interface{})
Errorw(msg string, keysAndValues ...interface{})
}
The whole adapter in main.go is this — slog takes the same alternating
key/value arguments, so each method forwards them untouched:
type slogLogger struct{ l *slog.Logger }
func (s slogLogger) Infow(msg string, kv ...interface{}) { s.l.Info(msg, kv...) }
func (s slogLogger) Warnw(msg string, kv ...interface{}) { s.l.Warn(msg, kv...) }
func (s slogLogger) Errorw(msg string, kv ...interface{}) { s.l.Error(msg, kv...) }
log := slogLogger{l: slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}))}
A logger with a different shape — zerolog, logrus, a request-scoped logger of
your own — is converted in those same three methods. And if your service already
uses logam, there is nothing to convert: logam.Logger satisfies the interface
as it is, which is what ../readiness and
../behind-proxy show. Swap NewJSONHandler for
NewTextHandler here if key=value is easier to read while you curl at it.
Note that serve in main.go takes server.Logger, not the concrete adapter,
so main is the only place this program names a logger at all.
What it demonstrates
- A logger with no dependency behind it, as above.
- Configuration from the environment with
server.NewHttpConfig(), and a configuration error reported separately from a wiring error. - The three-call flow:
NewHTTP(cfg, log)→s.Echo()to register routes →s.Run(). - Both response shapes.
GET /v1/videos/:idreturns an ordinary payload, soHTTPResponseanswers 200 and wraps it as{"data": ...}.POST /v1/videosreturns aserver.PostConfirmation, so it answers 201 with the confirmation unwrapped.&server.PostConfirmation{...}produces the same response; it used not to, which is noted at the call site. - The call site for
Run()'s error, which is the thing this example exists for.Runnever logs on your behalf and never exits the process, so amain()that ends in a bares.Run()exits 0 and says nothing when the bind fails. Here the error is logged and the process exits 1. - Errors handed to callers deliberately:
c.Bind's message names Go types and field offsets, so the handler answers with its own 400 message and attaches the real cause withSetInternal, where the access log picks it up.
Run it
HTTP_BIND_ADDRESS=127.0.0.1:8080 go run ./examples/minimal
Every HTTP_* variable applies; none is required. Useful ones here:
| Variable | Effect |
|---|---|
HTTP_BIND_ADDRESS |
Listen address. Default :8080. |
HTTP_MAX_BODY_LIMIT |
Default 10M. Set it to 10 (ten bytes) to watch the POST below get 413 Request Entity Too Large. |
HTTP_DEBUG |
true indents JSON and copies handler errors into bodies. |
HTTP_SHUTDOWN_TIMEOUT |
Grace period on Ctrl-C. Default 10s. |
Exercise it
Transcripts below are real, taken from HTTP_BIND_ADDRESS=127.0.0.1:18081 go run ./examples/minimal with the port rewritten to 8080 for readability.
$ curl -s -i http://127.0.0.1:8080/healthz | head -1
HTTP/1.1 200 OK
$ curl -s -i http://127.0.0.1:8080/v1/videos/42 | sed -n '1p;$p'
HTTP/1.1 200 OK
{"data":{"id":"42","title":"Episode 42"}}
$ curl -s -i -X POST -H 'Content-Type: application/json' \
-d '{"title":"Episode 1"}' http://127.0.0.1:8080/v1/videos | sed -n '1p;$p'
HTTP/1.1 201 Created
{"resource":"video","message":"created","id":"1"}
$ curl -s -i -X POST -H 'Content-Type: application/json' \
-d '{}' http://127.0.0.1:8080/v1/videos | sed -n '1p;$p'
HTTP/1.1 400 Bad Request
{"message":"title is required"}
$ curl -s -i http://127.0.0.1:8080/readyz | sed -n '1p;$p'
HTTP/1.1 200 OK
{"status":"ok","checks":[]}
Readiness answers 200 with an empty list because no check has been registered:
nothing has declared a dependency, so there is nothing to be unready for. See
../readiness for the other half.
What the slog-backed logger writes
The curl session above, as it appeared on stdout. This is the point of the
example: the request entries are the package's (the first line is this
program's own startup log), the JSON is slog's, and no logging library was
involved in either.
{"time":"2026-08-09T16:47:31.228451-04:00","level":"INFO","msg":"http server starting","bind_address":"127.0.0.1:8080","max_body_limit":"10M","real_ip_source":"peer","shutdown_timeout":"10s"}
{"time":"2026-08-09T16:48:54.907389-04:00","level":"INFO","msg":"request","request_id":"mjQrrQrGccqoIIzbEtFEzvCXtJOJQDRd","method":"GET","path":"/v1/videos/42","uri":"/v1/videos/42","status":200,"remote_ip":"127.0.0.1","latency":"135.11µs","bytes_out":42}
{"time":"2026-08-09T16:48:54.92628-04:00","level":"INFO","msg":"request","request_id":"nTrlYojiJiHOMcBKSsGonklHUmHCZQjJ","method":"POST","path":"/v1/videos","uri":"/v1/videos","status":201,"remote_ip":"127.0.0.1","latency":"127.817µs","bytes_out":50}
{"time":"2026-08-09T16:48:54.944821-04:00","level":"ERROR","msg":"request","request_id":"wtCRBHwrIFLdFMJRFCaVoILWdNjrruPW","method":"POST","path":"/v1/videos","uri":"/v1/videos","status":400,"remote_ip":"127.0.0.1","latency":"26.212µs","bytes_out":32,"error":"code=400, message=title is required"}
Four things to read out of that:
-
Neither probe is there.
/healthzand/readyzwere both requested and both are excluded from the access log, matched on the route pattern. -
The 400 is at
ERROR, notINFO. The handler returnedecho.NewHTTPError(400, ...), and the package logs at error level whenever the handler chain returned an error or the status was 5xx. Writing the same 400 withc.JSONand returningnilwould have been logged at info. That rule is the package's; slog only renders it. -
request_idis the value in theX-Request-IDresponse header. Send your own and it is preserved, so a correlation id survives the hop:$ curl -s -H 'X-Request-ID: my-correlation-id' http://127.0.0.1:8080/v1/videos/7{"level":"INFO","msg":"request","request_id":"my-correlation-id","method":"GET","path":"/v1/videos/7","status":200,...}(that one line abridged; the rest carry the same fields as above.)
-
One line on stdout is not slog's, and cannot be: Echo's own
⇨ http server started on 127.0.0.1:8080. The banner is hidden; that line is not, and it does not go through the injected logger.
Press Ctrl-C (or send SIGTERM) and the server drains and exits 0.
Pointers and values are the same response
Change the POST handler to pass a pointer:
return server.HTTPResponse(c, &server.PostConfirmation{...})
and the request answers 201 with
{"resource":"video","message":"created","id":"1"}, byte for byte what the
value form produces. That is worth trying precisely because it used to differ:
the type switch in response.go matched value types only, and the pointer form
came back 200 with the body wrapped in data. It now names both forms of all
three confirmation types.
A nil pointer is the one case that is not a confirmation:
var c *server.PostConfirmation answers 200 {"data":null} rather than
claiming a creation with an empty body.
Documentation
¶
Overview ¶
Command minimal is the smallest correct service built on github.com/zionmedianetwork/server: configuration from the environment, two routes, the JSON envelope, and — the part that is easy to get wrong — a call site that does something with the error Run returns.
Its logger is log/slog from the standard library, wired to server.Logger by the three one-line methods below. That is deliberate: this package asks for three structured methods and nothing else, so running it needs no logging dependency at all. See ../readiness for the same wiring with github.com/zionmedianetwork/logam, which satisfies server.Logger as it is.
Run it with:
HTTP_BIND_ADDRESS=:8080 go run ./examples/minimal
See the README next to this file for the requests to make against it.