server

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 17 Imported by: 0

README

server

CI Coverage Latest release Go reference Go License

github.com/zionmedianetwork/server is a small, opinionated wrapper around Echo v4 that gives a Go service an HTTP listener with the parts every service needs already wired: structured access logging through a logger you inject, a request id, a body limit, panic recovery, CORS that is closed until you open it, baseline security headers, optional rate limiting and compression, liveness and readiness endpoints, an optional request timeout, and a graceful shutdown that drains in-flight requests on SIGINT/SIGTERM.

The logger is the only thing it asks you for, and it asks for three methods — Infow, Warnw, Errorw — so log/slog from the standard library is enough. See Logging.

It is a library. There is no main, nothing runs on its own, and everything it does is decided by a consumer's call to NewHTTP and by HTTP_* environment variables.

What it is not

  • Not a TLS server. It serves H2C — HTTP/2 cleartext — via Echo's StartH2CServer. There is no certificate handling and no listener option to add one. TLS termination is expected upstream, in an ingress controller, a service mesh sidecar or a cloud load balancer. Exposing this process directly to clients puts every request, response, credential and cookie on the wire in plaintext. That is a deployment requirement, not a footnote: if nothing terminates TLS in front of it, this server is not safe to expose.
  • Not a websocket server. The package name and the previous README claimed "http and websocket servers". There has never been a websocket implementation here. Nothing in this repository upgrades a connection.
  • Not a framework. It registers no application routes and imposes no handler signature beyond Echo's. You get an *echo.Echo and use it.

Install

go get github.com/zionmedianetwork/server

Requires Go 1.23.3 or newer (the go directive in go.mod).

Quick start

package main

import (
	"log/slog"
	"os"

	"github.com/labstack/echo/v4"
	"github.com/zionmedianetwork/server"
)

// The logger this package wants is three methods. slog takes the same
// alternating key/value arguments, so each one 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...) }

func main() {
	log := slogLogger{l: slog.New(slog.NewJSONHandler(os.Stdout, nil))}

	// nil config means "read HTTP_* from the environment".
	s, err := server.NewHTTP(nil, log)
	if err != nil {
		log.Errorw("build http server", "error", err)
		os.Exit(1)
	}

	s.Echo().GET("/v1/videos/:id", func(c echo.Context) error {
		return server.HTTPResponse(c, map[string]string{"id": c.Param("id")})
	})

	// Run blocks until SIGINT/SIGTERM, drains, and returns. Handle the error:
	// it is the only report a failed bind will ever make.
	if err := s.Run(); err != nil {
		log.Errorw("http server stopped", "error", err)
		os.Exit(1)
	}
}

Two non-standard-library imports, and that is the whole dependency list: this package, and Echo for the handler signature. The logging is log/slog, so it costs nothing to add. If your service already has a logger — including github.com/zionmedianetwork/logam, whose Logger satisfies the interface as it is, with no adapter — pass that instead and delete the three methods. See Logging.

Four runnable, lint-clean programs live in examples/ — start there rather than with the snippet above.

The consumer flow

Three calls, in this order.

1. NewHTTP(cfg *HttpConfig, log Logger) (*httpServer, error)

Pass nil for cfg to load the configuration from the environment (equivalent to calling NewHttpConfig() yourself and passing the result).

log is a server.Logger: Infow, Warnw, Errorw, and nothing else. Any value with those three methods is accepted, so this parameter does not oblige you to adopt a logging library — a log/slog adapter is three lines, and a logam.Logger satisfies it directly. There is no default: the package logs through the value it is given, on every request and every readiness probe, and installs no no-op in its place. A nil logger is refused here, before the configuration is even read, rather than substituted for — a no-op stand-in would leave a service serving with no access log and no record of a failing readiness check, looking healthy while being unobservable. See Logging.

Everything the configuration decides is resolved and validated here, before anything is wired up, so a misconfigured server is reported by this call and never half-built. NewHTTP returns an error — it does not panic and does not exit — for:

Cause Example message fragment
log is nil logger is nil: ... panics on the first request that is logged
HTTP_MAX_BODY_LIMIT unparseable or non-positive invalid max body limit "10 megs"
HTTP_REAL_IP_SOURCE not peer or xff invalid real ip source "XFF"
An entry in HTTP_TRUSTED_PROXIES that is not CIDR invalid trusted proxy "10.1.0.7"
HTTP_TRUSTED_PROXIES set while the source is peer set HTTP_REAL_IP_SOURCE=xff or drop HTTP_TRUSTED_PROXIES
HTTP_REQUEST_TIMEOUT negative want a positive duration, or zero to disable it
HTTP_REQUEST_TIMEOUT at or above HTTP_WRITETIMEOUT must be below the write timeout 15s
An entry in HTTP_TIMEOUT_EXEMPT_PATHS without a leading / want a route pattern beginning with "/"
An entry in HTTP_ALLLOWED_ORIGINS that is not a bare origin invalid allowed origin "https://app.example.com/"
* in HTTP_ALLLOWED_ORIGINS alongside named origins allows every origin, so the named ones are never consulted
HTTP_CORS_MAX_AGE or HTTP_HSTS_MAX_AGE negative, or under 1s truncates to zero and disables it
HTTP_HSTS_MAX_AGE set while security headers are disabled drop HTTP_DISABLE_SECURITY_HEADERS or drop HTTP_HSTS_MAX_AGE
HTTP_HSTS_INCLUDE_SUBDOMAINS with no HTTP_HSTS_MAX_AGE no Strict-Transport-Security header is sent
HTTP_RATE_LIMIT negative, or HTTP_RATE_LIMIT_BURST set without it set HTTP_RATE_LIMIT or drop HTTP_RATE_LIMIT_BURST

The returned type is unexported. You cannot name it in a variable declaration, a struct field or a function signature — hold it in a := binding, or define your own narrow interface if you need to pass it around. See Known limitations.

2. s.Echo() *echo.Echo

The only route-registration API. There is none on the server itself.

e := s.Echo()
e.GET("/v1/videos/:id", getVideo)
e.POST("/v1/videos", createVideo)

The built-in middleware stack is applied in this order and is fixed at construction. The first entry is the outermost wrapper, so everything below it sees the responses — including the rejections — that the ones after it produce:

  1. Pre: RemoveTrailingSlash, RequestID
  2. Use: security headers — unless HTTP_DISABLE_SECURITY_HEADERS is set
  3. Use: CORS
  4. Use: BodyLimit, request logger, Recover
  5. Use: rate limiter — only when HTTP_RATE_LIMIT is set
  6. Use: gzip — only when HTTP_GZIP is set
  7. Use: request timeout — only when HTTP_REQUEST_TIMEOUT is set

Three placements are load-bearing. CORS sits outside everything that can refuse a request, so a 413 from the body limit, a 429 from the rate limiter and the 500 from a recovered panic all carry Access-Control-Allow-Origin — a cross-origin response without it is one the browser will not show the script that asked, status and all, so a rejected upload would otherwise look like a CORS misconfiguration rather than a file that was too big. The rate limiter sits inside the access log, so every 429 is logged; a limit you cannot see biting is indistinguishable from a client that stopped calling. The access log sits outside Recover, so a panicking handler is logged: Echo's request logger builds its entry after next(c) returns and does not defer that, so a panic unwinding through it skips the log entirely — with Recover outside, as it was until now, a 500 from a panic produced no access log line at all. Inside, the panic has become a response before the logger sees it.

The cost of the first one: a CORS preflight is answered above the access log, so OPTIONS requests are not logged. They are cached by the browser for HTTP_CORS_MAX_AGE anyway.

The cost of the third one is small but worth knowing: Recover no longer wraps the logger, so a Logger implementation that panics is not contained by this package. That is a bug in the logger, it can only happen after the response has been written, and net/http still stops it taking the process down.

You may append your own with e.Use(...) or e.Pre(...), but you cannot reorder or remove the built-ins, and anything you append with Use runs inside all of them.

Register every route before calling Run(): Echo's router is not guarded against concurrent registration, so adding a route while the server is serving races with the requests it is routing. RegisterReadinessCheck is the exception — its registry has its own lock and is explicitly safe to call while serving.

3. s.Run() error

Run installs handlers for SIGINT and SIGTERM before anything starts listening, serves, and blocks. On a signal it stops accepting connections and drains in-flight requests within HTTP_SHUTDOWN_TIMEOUT.

Situation Result
Clean drain after a signal nil
Failed bind (port in use, malformed address) non-nil, naming the address
Drain overran the grace period non-nil, wrapping context.DeadlineExceeded

Three properties are worth stating explicitly, because each has bitten someone:

  • Run never terminates the process. Deciding that a failure to serve warrants a non-zero exit status belongs to the application.
  • Run never logs on the caller's behalf. The returned error is its only report. A caller that discards it gets silence on a failed bind — the process stays up, serves nothing and exits 0.
  • A second signal during a drain takes its default action. The signal handlers are released the moment draining starts, so a Ctrl-C on a drain that is not progressing aborts it, as everyone expects.

The recommended call site:

if err := s.Run(); err != nil {
	log.Errorw("http server stopped", "error", err)
	os.Exit(1)
}

A clean shutdown returns nil, so this does not turn an ordinary SIGTERM from an orchestrator into a failed exit.

And one accessor: s.Addr() (net.Addr, bool)

The address the listener is actually bound to. It matters when the configured one does not name the port:

go func() { errCh <- s.Run() }()

if addr, ok := s.Addr(); ok {
	log.Infow("listening", "addr", addr.String())
}

HTTP_BIND_ADDRESS=:0 asks the kernel to choose a port, and BindAddress never learns which one it got — a test, or a process that has to register itself somewhere, needs the resolved address rather than the requested one.

State Result
Before Run has bound a port nil, false
Listening the listener's address, true
After a drain has finished the address it bound, true

Three things follow from that table:

  • The second result is not decoration. Before Run there is no listener, and a bare net.Addr return would hand you the nil interface that panics on .String() one line later, with nothing in the signature to warn you. Run and Addr are on different goroutines by construction, so "not yet" is a state every caller passes through — poll it, or read it after the server has answered something.
  • It is not a liveness signal. Shutting down closes the listener without clearing it, so Addr keeps answering afterwards. It tells you what this server bound, not whether it is still serving; that is /healthz.
  • It is safe to call while Run is starting, because it reads through Echo's own accessor, which takes the lock startup writes the listener under.

Configuration

HttpConfig is populated by envconfig with the prefix HTTP. Durations use Go's time.ParseDuration syntax (15s, 2m, 500ms); lists are comma-separated; booleans accept true/false/1/0.

Environment variable Field Default Meaning
HTTP_BIND_ADDRESS BindAddress :8080 Address the listener binds.
HTTP_READTIMEOUT ReadTimeout 15s http.Server.ReadTimeout: the whole request, headers and body, must arrive within it.
HTTP_WRITETIMEOUT WriteTimeout 15s http.Server.WriteTimeout: the connection is closed once it passes, whatever the handler is doing.
HTTP_SHUTDOWN_TIMEOUT ShutdownTimeout 10s Grace period in-flight requests get after a termination signal.
HTTP_REQUEST_TIMEOUT RequestTimeout 0 (off) Deadline put on the request context. Must be strictly below HTTP_WRITETIMEOUT. See Request timeouts.
HTTP_TIMEOUT_EXEMPT_PATHS TimeoutExemptPaths empty Route patterns the request timeout skips, e.g. /videos/:id/stream,/uploads. Each must start with /.
HTTP_READINESS_TIMEOUT ReadinessTimeout 2s Bound on one readiness probe, covering all checks together.
HTTP_MAX_BODY_LIMIT MaxBodyLimit 10M Largest accepted request body, in gommon byte notation (10M, 512K, 4MiB). M is decimal: 10M is 10,000,000 bytes; use 10MiB for binary.
HTTP_ALLLOWED_ORIGINS AlllowedOrigins empty CORS origin allowlist. Empty allows no cross-origin access. Note the spelling. See CORS.
HTTP_ALLOWED_HEADERS AllowedHeaders Accept,Authorization,Content-Type,X-Request-Id Request headers a preflight allows. One L, unlike the line above.
HTTP_CORS_MAX_AGE CorsMaxAge 1h How long a browser may cache a preflight. 0 sends no Access-Control-Max-Age at all.
HTTP_DISABLE_SECURITY_HEADERS DisableSecurityHeaders false Turns off the baseline response headers. See Security headers.
HTTP_HSTS_MAX_AGE HstsMaxAge 0 (off) Strict-Transport-Security lifetime. Only sent for requests that arrived over TLS or carried X-Forwarded-Proto: https.
HTTP_HSTS_INCLUDE_SUBDOMAINS HstsIncludeSubdomains false Adds includeSubdomains. Inert — and refused — without a max age.
HTTP_RATE_LIMIT RateLimit 0 (off) Requests per second per client address. See Rate limiting.
HTTP_RATE_LIMIT_BURST RateLimitBurst one second's worth Requests allowed to arrive at once. Refused while the rate limit is off.
HTTP_GZIP Gzip false Compresses responses over 1 KiB, skipping probe paths and HTTP_TIMEOUT_EXEMPT_PATHS.
HTTP_STATIC_PATH StaticPath /static Currently ignored. See Known limitations.
HTTP_DEBUG Debug false Copies handler errors into response bodies, indents all JSON, and adds the cause to readiness reports.
HTTP_REAL_IP_SOURCE RealIPSource peer peer or xff. See Client IP.
HTTP_TRUSTED_PROXIES TrustedProxies empty Comma-separated CIDRs allowed to relay a client address. Only valid with xff.

Not configurable: the HTTP/2 settings (MaxConcurrentStreams: 200, MaxReadFrameSize: 1024000, IdleTimeout: 10s), the CORS method list (GET, POST, PUT, PATCH, DELETE), Access-Control-Allow-Credentials (never sent — see CORS), the security header values, and the middleware stack.

Two naming gotchas

These are real, they cost people time, and neither can be fixed without a breaking change to every deployment already setting them.

  1. HTTP_READTIMEOUT and HTTP_WRITETIMEOUT have no underscore in the middle. Every other multi-word field carries envconfig's split_words:"true" tag; ReadTimeout and WriteTimeout do not. So HTTP_READ_TIMEOUT and HTTP_WRITE_TIMEOUT are silently ignored and you get the 15s defaults:

    $ HTTP_WRITE_TIMEOUT=99s ./svc     # ignored
    ... "write_timeout": "15s"
    $ HTTP_WRITETIMEOUT=99s ./svc      # read
    ... "write_timeout": "1m39s"
    

    Do not copy this style for new fields — HTTP_SHUTDOWN_TIMEOUT, HTTP_REQUEST_TIMEOUT and HTTP_READINESS_TIMEOUT are all split correctly.

  2. HTTP_ALLLOWED_ORIGINS has three L's. The struct field is misspelled AlllowedOrigins, and envconfig derives the variable name from the field. HTTP_ALLOWED_ORIGINS still does nothing at all. What has changed is the consequence: the origin list now defaults to empty, so the typo means no cross-origin access rather than every origin, and it announces itself the first time a browser calls. Note also its new neighbour HTTP_ALLOWED_HEADERS, which has one L and is correctly spelled — the two sit next to each other in a config file and are easy to skim past. The misspelling is also visible in Go code for anyone building an HttpConfig by hand.

Building a config by hand

HttpConfig and its fields are exported, so a consumer that does not want environment variables can build one directly. Note that the defaults live in NewHttpConfig, not in struct tags, so a hand-built config gets Go zero values for anything you leave out. Three of those are defended at the point of use — an unset body limit, shutdown timeout and readiness timeout each fall back to the package default rather than doing something absurd — but ReadTimeout and WriteTimeout will genuinely be zero, meaning no transport timeout at all.

Health and readiness

Four routes are registered for you, and all four are excluded from the access log — probe traffic is high volume and carries no information.

Path Kind Answers
/healthz, /v1/healthz Liveness Static 200 OK, body OK, text/plain.
/readyz, /v1/readyz Readiness 200 when every registered check passes, 503 when any fails.

Liveness is deliberately static. It says "this process is running and answering" and nothing else: a liveness probe that failed because the database was unreachable would have an orchestrator restart a pod whose only problem is somewhere else, turning a dependency outage into a crash loop.

Readiness is what a load balancer should consult.

if err := s.RegisterReadinessCheck("postgres", db.PingContext); err != nil {
	return fmt.Errorf("register readiness check: %w", err)
}

RegisterReadinessCheck(name string, check ReadinessCheck) error returns an error for an empty name, a nil check, or a name already taken. It is safe to call before Run and while the server is serving: each probe works from a snapshot, so a check registered mid-flight is picked up by the next probe.

A ReadinessCheck is func(ctx context.Context) error. It runs on every probe, so it should be a ping and not a query, and it must respect the context it is handed — a check that blocks anyway is abandoned at the deadline and reported as failed, but its goroutine keeps running. Checks run concurrently (so one slow dependency does not make the others look broken), the whole probe is bounded by HTTP_READINESS_TIMEOUT, and a check that panics is contained and reported as a failure rather than taking the process down.

Response shape, with no checks registered:

{"status":"ok","checks":[]}

With a failing dependency (503), checks listed in registration order:

{"status":"fail","checks":[{"name":"postgres","status":"fail"},{"name":"redis","status":"ok"}]}

The cause is not in the body unless HTTP_DEBUG is set. Driver errors name hosts, ports, databases and accounts — pq: password authentication failed for user "zion_admin" — and readiness is routinely exposed further than the rest of the API. With HTTP_DEBUG=true each failing check gains an error field.

The cause is always written to the log, in both settings, at warn level, because the probe paths are excluded from the access log and it would otherwise exist nowhere:

WARN  readiness check failed  {"check": "postgres", "error": "pq: dial tcp 10.0.0.7:5432: connect: connection refused", "failing_for": "0s"}
INFO  readiness check recovered  {"check": "postgres", "failing_for": "204.223ms"}

Warn rather than error because a dependency going away is expected and usually self-healing, and this process is doing the right thing by answering 503. To keep a fleet of pods polled once a second from producing tens of thousands of identical lines, only transitions are logged, plus a repeat at most once a minute while a check stays down, plus one line on recovery.

Kubernetes probes should point at /healthz for livenessProbe and /readyz for readinessProbe (and startupProbe, if you use one).

Request timeouts

Off by default, and deliberately so: this package cannot see the routes it will carry. A blanket timeout is wrong for large downloads and uploads, and for any streaming or SSE route that holds a request open by design, so a library that switched one on at upgrade time would convert working routes into 503s without anybody changing a line of code.

HTTP_REQUEST_TIMEOUT=10s
HTTP_TIMEOUT_EXEMPT_PATHS=/v1/videos/:id/stream,/v1/uploads
HTTP_WRITETIMEOUT=120s

Three things decide whether this works.

It must be strictly below HTTP_WRITETIMEOUT, and NewHTTP enforces that. net/http closes the connection once the write timeout passes, so a request timeout that is not shorter cancels handlers and never manages to write the 503; the client sees a truncated stream or a reset instead of a status. The default write timeout is 15s, so the obvious "give requests 30 seconds" is exactly the setting that cannot work:

build http server: request timeout 30s must be below the write timeout 15s, ...

Exemptions name route patterns, not URLs. /videos/:id/stream, not /videos/42/stream; the package's own static route is /static*. An entry without a leading / is refused at startup, because it could never match and would sit there looking like an exemption that works.

It only bounds handlers that cooperate. The timeout is implemented by putting a deadline on c.Request().Context(). A handler that selects on that context, or passes it into its database driver and HTTP clients, is unblocked at the deadline; returning the context's error (or an error wrapping it with %w) is what the middleware turns into 503 Service Unavailable. A handler that ignores the context runs to completion exactly as it would with no timeout configured, holding its goroutine and its connection — and a handler that notices cancellation but returns some unrelated error will be answered with whatever that error maps to, usually 500. Propagating the request context into every blocking call is what makes the timeout real. See examples/streaming for all three cases side by side.

Note also that exempting a route from the request timeout is not enough on its own: the write timeout still applies to it, so a long stream needs HTTP_WRITETIMEOUT raised as well or the transport cuts it off regardless.

HTTP_TIMEOUT_EXEMPT_PATHS has a second effect: those routes are also skipped by gzip when HTTP_GZIP is on. See Compression.

Client IP

HTTP_REAL_IP_SOURCE decides where c.RealIP() reads the client address from, which is also the remote_ip in every access log line and the basis for anything you build on top (allowlists, audit trails, rate limiting).

Value Behaviour
peer (default) The address that opened the connection. X-Forwarded-For and X-Real-IP are ignored entirely.
xff X-Forwarded-For, walked from the right, stopping at the first hop that is not a trusted proxy. X-Real-IP is still ignored.

The default is peer because forwarding headers are client-supplied data: with nothing trusted in front, any caller can claim any address it likes. Echo's own default (no IPExtractor set) believes those headers from anyone; this package sets an extractor explicitly in every case so that never applies.

HTTP_TRUSTED_PROXIES is a comma-separated CIDR list and is only meaningful with xff:

  • Empty: loopback and the private ranges are trusted, which covers the usual sidecar and cluster-internal ingress. Link-local is never trusted.
  • Set: the list is exhaustive, not additive. Naming the load balancer says where the proxies are, so the implicit trust in loopback and every private address stands down. This surprises people — after setting HTTP_TRUSTED_PROXIES=10.4.0.0/16, a request relayed from 127.0.0.1 is no longer believed.

Setting HTTP_TRUSTED_PROXIES while the source is still peer is a startup error, not a no-op: the ranges would never be consulted, and a silent no-op leaves an operator believing a proxy is trusted. xff is also only safe when the proxy in front overwrites rather than appends to an incoming X-Forwarded-For. See examples/behind-proxy.

CORS

The default allows nothing. With HTTP_ALLLOWED_ORIGINS unset, no origin gets Access-Control-Allow-Origin, so no browser hands a response from this server to a script served from anywhere else.

That is a change. The default used to be *, which meant every service that never set the variable published every route — GET, POST, PUT, PATCH and DELETE alike — to any page that could get a browser to call it, and nothing in that deployment's configuration recorded the decision. To restore the old behaviour exactly, set HTTP_ALLLOWED_ORIGINS=*.

HTTP_ALLLOWED_ORIGINS=https://app.example.com,https://admin.example.com

Entries are origins: a scheme and a host, optionally a port, and nothing else. https://app.example.com/ (trailing slash), app.example.com (no scheme) and https://app.example.com/videos (a path) are all refused by NewHTTP, because none of them can ever equal the Origin header a browser sends and each would sit in the config looking like an allowance that works. Echo's wildcard host patterns are supported: https://*.example.com.

Listing * alongside named origins is refused too. The wildcard matches first and matches everything, so such a list reads as a narrow policy and behaves as an open one.

Three more things:

  • Credentials are never allowed. This package does not send Access-Control-Allow-Credentials and has no setting for it, so even HTTP_ALLLOWED_ORIGINS=* cannot be used to read a response that depends on the caller's cookies. Enabling credentials belongs with whoever owns the authentication scheme, and credentials-with-a-wildcard is the CORS misconfiguration everybody writes about.
  • Preflights are cached for an hour. Access-Control-Max-Age was never sent, so browsers re-issued an OPTIONS preflight before every non-simple cross-origin request. The default is now 1h: browsers cap this themselves (Chrome at 2 hours, Firefox at 24), so a larger number is silently truncated and buys nothing, while an hour is honoured verbatim everywhere and bounds how long a tightened policy keeps working in an already-open tab. HTTP_CORS_MAX_AGE=0 restores the old "no header" behaviour.
  • Request headers are an allowlist. AllowHeaders was unset, which made echo reflect whatever the browser asked for. The default is now Accept,Authorization,Content-Type,X-Request-Id — the last one so a browser client can send the correlation id this package logs and echoes back. HTTP_ALLOWED_HEADERS=* restores "anything the browser asks for"; note that the fetch standard excludes Authorization from that wildcard, so list it by name if you need it.

CORS is enforced by the browser, not by this server: a refused origin still gets a normal 200 (or a 204 for a preflight) with the header simply absent. Testing it with curl will mislead you.

Security headers

On by default, on every response including the rejections:

Header Value Why
X-Content-Type-Options nosniff Stops a browser second-guessing a Content-Type, which is how an upload or JSON endpoint ends up executing as script.
X-Frame-Options SAMEORIGIN Refuses cross-origin framing. Not DENY: this package serves a same-origin static route, and DENY would break an embed the deployment owns while adding nothing.
Referrer-Policy strict-origin-when-cross-origin The paths here name resources (/v1/videos/42); this keeps them out of a third party's Referer.
X-XSS-Protection 0 Deliberate, and not echo's default of 1; mode=block. The legacy auditor that enables was itself exploitable and is gone from every current browser; 0 is what OWASP now recommends, sent rather than omitted so a browser that still has the auditor does not switch it on itself.

HTTP_DISABLE_SECURITY_HEADERS=true turns all four off and restores the previous behaviour exactly.

No Content-Security-Policy is set. A useful one names a particular application's script, style and frame origins, and a policy that guesses wrong does not fail loudly — it silently stops half a page loading. Add your own with s.Echo().Use(...).

HSTS is off by default, and that is deliberate

Strict-Transport-Security is not sent unless HTTP_HSTS_MAX_AGE is set.

Every other header here describes one response. HSTS is a durable instruction: for max-age seconds afterwards the browser refuses to speak plaintext to that host, and the only way to undo it early is to serve max-age=0 over working HTTPS. This process speaks h2c with no TLS of its own, so whether the origin it is reached at is HTTPS everywhere is a fact about somebody's ingress that this package cannot see. A library that emitted HSTS by default could take a hostname offline, on upgrade, for whatever plaintext still depends on it.

When you do set it:

HTTP_HSTS_MAX_AGE=2160h              # ninety days; Go durations have no "d"
HTTP_HSTS_INCLUDE_SUBDOMAINS=true

That is sent as Strict-Transport-Security: max-age=7776000; includeSubdomains.

  • The header is emitted only for requests that arrived over TLS or carried X-Forwarded-Proto: https. Behind a terminating proxy that means the proxy must set that header, and must be the only thing that can — the same requirement HTTP_REAL_IP_SOURCE documents for X-Forwarded-For.
  • includeSubdomains is off by default because it is the irreversible part: it pins every name under the domain, including ones this service knows nothing about. It is refused without a max age, since that combination sends no header at all while reading like HSTS is configured.
  • There is no preload and there will not be one. That is a submission to a list compiled into browsers, it takes months to leave, and no library should be able to put a consumer's domain on it.

Rate limiting

Off by default. HTTP_RATE_LIMIT is requests per second per client address:

HTTP_RATE_LIMIT=20
HTTP_RATE_LIMIT_BURST=60     # optional; defaults to one second's worth

Over the limit the caller gets 429 Too Many Requests, and the refusal is in the access log like any other response.

Off by default because three of its properties are facts about a deployment that this package cannot see:

  • The limiter is per process. Ten replicas of a service configured at 20 req/s enforce 200 req/s in aggregate, and that number changes every time the deployment scales.
  • The store is in memory. It holds one bucket per distinct client address, dropped after three idle minutes. Behind a proxy that is a small map; facing the open internet directly it is a function of your attacker's address space.
  • It is keyed on c.RealIP(), so it inherits HTTP_REAL_IP_SOURCE. With the wrong source every caller shares one bucket, or every caller can mint a new one at will — and a limit keyed on a spoofable address is worse than no limit, because it looks like protection. Read Client IP before switching this on.

/healthz, /v1/healthz, /readyz and /v1/readyz are never rate limited. A 429 on readiness withdraws the instance from load balancing and a 429 on liveness invites an orchestrator to restart it, which would turn a burst of client traffic into an outage by way of the probes.

A burst is derived from the rate when you do not set one — rounded up, and never zero, because the underlying store treats a zero burst literally and refuses everything: HTTP_RATE_LIMIT=0.5 with no burst would otherwise configure an outage. Setting HTTP_RATE_LIMIT_BURST while the rate limit is off is a startup error rather than a no-op.

Compression

Off by default. HTTP_GZIP=true compresses responses over 1 KiB for clients that send Accept-Encoding: gzip.

Off by default because this package carries media. Compressing an MP4 or a JPEG spends CPU on both ends to produce something no smaller, and compression buffers: a streaming or SSE route only keeps streaming because echo's writer forces a gzip flush on each Flush(), and the proxies in front are under no such obligation.

When it is on, two sets of routes are skipped:

  • the probe paths, whose bodies are two words and would come out larger;
  • every route named in HTTP_TIMEOUT_EXEMPT_PATHS. That list already names the routes a deployment has declared long-running — the streams, the downloads, the uploads — which is exactly the set compression should stay out of. One list, so the two cannot drift apart. See examples/streaming.

Responses

HTTPResponse(c echo.Context, data interface{}) error is the intended way to write JSON. It type-switches on the payload:

Payload Status Body
server.PostConfirmation, or *PostConfirmation 201 the value, unwrapped
server.PatchConfirmation, or *PatchConfirmation 200 the value, unwrapped
server.Confirmation, or *Confirmation 200 the value, unwrapped
a nil pointer to any of the three 200 {"data":null}
anything else 200 {"data": <payload>}
// 200 {"data":{"id":"42","title":"Episode 42"}}
return server.HTTPResponse(c, video{ID: "42", Title: "Episode 42"})

// 201 {"resource":"video","message":"created","id":"42"}
return server.HTTPResponse(c, server.PostConfirmation{
	Resource: "video", Message: "created", ID: "42",
})

// The same 201 and the same body: pointer and value are treated alike.
return server.HTTPResponse(c, &server.PostConfirmation{
	Resource: "video", Message: "created", ID: "42",
})

Pointers used to be a defect here and are not any more. Until this change the type switch matched value types only, so &server.PostConfirmation{...} fell through to the default branch and answered 200 wrapped in data instead of 201 bare — silently, since nothing at the call site said so. Both forms now go through the same cases. If you have code written around the old behaviour, see Responses: what changed below.

A nil pointer is deliberately not a confirmation: a typed nil carries no id, resource or message, so answering 201 with a body of null would report a creation containing nothing. It takes the envelope instead and comes out exactly as an untyped nil does — 200 {"data":null} — rather than dereferencing anything in a response path.

Also exported: server.ResponsePayload, a map[string]interface{} for building an ad-hoc payload by hand. (server.Singular, an identically defined and entirely unused second name for it, was removed — replace any use with ResponsePayload; the underlying type is the same, so nothing but the name changes.) Adding a new confirmation type means adding both its cases, value and pointer, otherwise it is silently wrapped in data.

Responses: what changed

Passing a pointer to a confirmation is the one behaviour change here that a consumer can observe without changing a line of their own code:

Call Before Now
HTTPResponse(c, &PostConfirmation{...}) 200 {"data":{...}} 201 {...}
HTTPResponse(c, &PatchConfirmation{...}) 200 {"data":{...}} 200 {...}
HTTPResponse(c, &Confirmation{...}) 200 {"data":{...}} 200 {...}
HTTPResponse(c, (*PostConfirmation)(nil)) 200 {"data":null} 200 {"data":null}

This is the intended behaviour arriving late, not a new one: the value forms have always answered this way, and any client that was reading data out of a pointer confirmation was reading a bug. Check clients that parse a creation response for a data key, and anything asserting 200 on a POST. Passing the confirmation by value was and remains unaffected.

Logging

This package never constructs a logger and never writes anywhere else. The caller passes one to NewHTTP, and every line the package emits — one entry per request, plus the readiness lines — goes through it.

The contract is three methods
type Logger interface {
	Infow(msg string, keysAndValues ...interface{})
	Warnw(msg string, keysAndValues ...interface{})
	Errorw(msg string, keysAndValues ...interface{})
}

That is all of it, and they are the three the package calls. The arguments after msg are alternating keys and values — "status", 503 — the convention zap's SugaredLogger established and slog shares.

The interface is declared here, where it is consumed, rather than imported from a logging library, so using this package does not oblige you to adopt one. Nothing in the package proper imports a logger implementation.

log/slog, with no dependency at all
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...) }

s, err := server.NewHTTP(nil, slogLogger{l: slog.New(slog.NewJSONHandler(os.Stdout, nil))})

Three one-line methods, and log/slog is standard library, so a service wired this way adds no logging dependency at all. slog takes the same alternating key/value arguments, so the adapter forwards them untouched; a logger with a different shape — zerolog's fluent chain, logrus's Fields map — converts them in these same three methods. examples/minimal and examples/streaming run exactly this, and the adapter is compiled and exercised by the package's own tests (logger_test.go), so it cannot quietly stop working.

No adapter is exported from this package on purpose. It would be six lines of code and a permanent piece of public API, and every consumer needs a slightly different one — their own handler, their own level mapping, a request-scoped logger pulled from a context — so the type belongs in the consumer.

logam still works, unchanged
log := logam.NewLogger(logam.Config{
	LogLevel:    "info",
	LogFormat:   "json",
	Environment: logam.EnvProduction,
})

s, err := server.NewHTTP(nil, log) // no adapter, no wrapper

github.com/zionmedianetwork/logam's Logger carries seventeen methods; this package calls three of them, and Go satisfies interfaces structurally, so a logam.Logger is a server.Logger. Every call written before this interface existed compiles unchanged, and a compile-time assertion in logam_compat_test.go keeps it that way. That assertion, in a test file, is the only reason logam is in this module's go.mod at all: nothing in the package proper imports it, so it is never compiled into a consumer's binary and deleting that one file is what would let go mod tidy drop it. examples/readiness and examples/behind-proxy use logam.

What gets logged

One structured entry per request. The rendering is your handler's; this came out of examples/minimal's slog JSON handler, wrapped here for width:

{"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}
  • request_id comes from the RequestID middleware and is the same value sent back in the X-Request-ID response header. A client-supplied X-Request-ID is preserved, so a correlation id survives the hop.
  • path is the matched route pattern's path and uri the raw request URI, including the query string.
  • status is what the client actually received: the global error handler runs before the values are read.
  • An error field is added when the handler chain returned one.

Level: error when the handler returned an error or the status was 5xx; info otherwise. Note the consequence — a handler that returns echo.NewHTTPError(400, ...) is logged at error level, while one that writes the same 400 with c.JSON/c.NoContent and returns nil is logged at info:

{"level":"ERROR","msg":"request","method":"POST","path":"/v1/videos","status":400,
 "bytes_out":32,"error":"code=400, message=title is required",...}

(abridged: the other fields are as above.)

A panicking handler is logged too, and its entry has a shape of its own worth recognising: status 500, error level, and no error field. Recover runs inside the logger and handles the recovered panic itself, so by the time the entry is built there is no error left to report — the level comes from the status, not from the error. The panic value and its stack go to stderr through Echo's own recoverer and never reach the injected logger, so a 500 with no error field is the line that tells you to go and find them.

{"level":"ERROR","msg":"request","method":"GET","path":"/v1/videos/42","status":500,
 "bytes_out":36,"request_id":"...","latency":"212.4µs",...}

Liveness and readiness paths (/healthz, /v1/healthz, /readyz, /v1/readyz) are skipped entirely, matched on the route pattern, so a query string or trailing slash does not sneak them back into the log.

CORS preflights are absent too, for a different reason: the CORS middleware answers an OPTIONS above the logger, which is the placement that lets every rejection below it carry CORS headers — see the middleware stack under The consumer flow.

Warnw has exactly one caller: a failing readiness check. That line carries the dependency's own error, which the probe response withholds unless HTTP_DEBUG is set, and since the probe paths are outside the access log it is the only place the cause is written down. Only transitions are logged, plus a repeat at most once a minute while a check stays down, plus one line on recovery — see Health and readiness.

Three things do not go through the injected logger: Echo's own startup line (⇨ http server started on :8080, on stdout — the banner is hidden, the port line is not), Echo's internal logger for the rare case where writing an error response itself fails, and the [PANIC RECOVER] line with the stack trace, which Recover prints to stderr. The access log records that a request panicked; the stack is only on stderr.

Examples

Four runnable programs, each in its own directory with its own README:

Example Demonstrates Logger
examples/minimal The smallest correct service, and the call site to copy. log/slog
examples/readiness Readiness checks over stub dependencies you can knock over with curl. logam
examples/behind-proxy Production-shaped config behind a TLS-terminating load balancer. logam
examples/streaming A request timeout that spares a streaming route. log/slog

Two of each on purpose: the stdlib pair shows that this package needs no logging dependency, the logam pair that an existing logam.Logger is passed straight in. Nothing else about the four differs in how they log.

They are part of this module, so go build ./..., go vet ./... and golangci-lint run ./... cover them.

Development

go build ./...
go vet ./...
gofmt -l .                       # must print nothing
go test -count=1 ./...
go test -race -count=1 ./...     # several tests are timing- and race-sensitive
go test -run '^TestName$' ./...  # a single test
golangci-lint run ./...          # config and rationale in .golangci.yml

CI pins the linter, so without a local install the exact version it runs is:

go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run ./...

A tool@version run resolves outside this module, so it adds nothing to go.mod.

go.sum is committed and go.mod is tidy, so a fresh clone builds directly — there is no go mod tidy step to run first. CI (.github/workflows/ci.yml) enforces both: it fails on any diff go mod tidy would produce and on go.sum becoming untracked, then runs the commands above plus go mod verify and govulncheck. A tidy diff in CI means something else is wrong; do not "fix" it by regenerating the module files.

Adding a dependency — including for an example — changes go.mod and will fail that check until the change is committed deliberately.

Coverage
go test -count=1 -covermode=atomic -coverprofile=coverage.out .
go tool cover -func=coverage.out | tail -1
go tool cover -html=coverage.out

Note the . rather than ./...: the figure that matters is the library's, and examples/ is four package main programs with no tests by design — CI compiles and lints them, which is the whole claim being made about them. Including them takes the same test run from 98.6% to 70.2%, which would be a number about the wrong thing.

The badge at the top is produced by .github/workflows/coverage.yml on every push to main: it makes the same measurement, renders a shields.io endpoint document, and commits it to an orphan badges branch that shields reads over raw.githubusercontent.com. No third-party coverage service, no account and no token beyond the workflow's own. If that job has never run — or its branch has been deleted — the badge renders as an error rather than a number; it cannot go quietly stale, because it has no last-known-good value to fall back to.

Releasing

go get resolves this module by tag, so a release is a semver tag plus a GitHub Release. Both are made by .github/workflows/release.yml, which is workflow_dispatch only:

input
release_type patch / minor / major, applied to the highest existing semver tag
prerelease cut vX.Y.Z-rc.N instead. go get @latest never selects a prerelease
dry_run on by default: print the plan and the notes, create nothing

It refuses to run from anywhere but main, runs the whole of ci.yml before tagging (the same workflow, called — not a second copy of the commands), makes an annotated tag whose message is the release notes, and publishes the release with GitHub's generated notes.

The one rule worth knowing before pressing it: Go requires major version 2 and above to appear in the module path. Releasing v2.0.0 means changing module github.com/zionmedianetwork/server to .../v2 and updating every import first, in an ordinary reviewed pull request. The workflow checks for this and refuses to tag rather than publishing a module that go get cannot resolve. The version-computation logic lives in .github/scripts/next-version.sh and has its own table-driven test:

bash .github/scripts/next-version-test.sh

Known limitations

Everything here is true of the code as it stands. None of it is a plan.

  • No TLS. H2C only; termination must happen upstream. See What it is not.
  • No websocket support, despite the historical README. Nothing here upgrades a connection.
  • The server type is unexported. NewHTTP returns *httpServer, so consumers cannot name the type in a variable declaration, struct field or function signature. Use :=, or declare your own interface with the two or three methods you need.
  • The middleware stack and CORS policy are fixed at construction. You can append middleware through s.Echo(), but not reorder or remove the built-in chain, and the CORS method list is not configurable.
  • CORS is closed until you open it. No origin is allowed unless HTTP_ALLLOWED_ORIGINS (three L's) names it. A deployment serving browser clients must set it; * is still available and still a decision.
  • CORS preflights are not in the access log. The middleware answers them above the logger, which is what lets every rejection below carry CORS headers. A browser's own network panel is where a failing preflight is diagnosed.
  • A 413 from a declared Content-Length is not in the access log either. BodyLimit sits above the logger and refuses that request before calling the rest of the chain, so nothing below it runs. An oversize body with no declared length is logged, because the limit is then hit during the handler's read and surfaces as a returned error. The response is correct in both cases — 413, with CORS and security headers — only the log line differs.
  • The rate limiter is per process and in memory. See Rate limiting — the effective fleet-wide limit is your replica count times the configured one.
  • Static files come from the process working directory. The route is hardcoded as e.Static("/static", "static"), so it serves ./static relative to wherever the binary was started. HTTP_STATIC_PATH is read and defaulted but never used — setting it has no effect at all.
  • No Content-Security-Policy and no HSTS by default, and no metrics or tracing instrumentation. See Security headers for why those two are left to the consumer; add the rest with s.Echo().Use(...), or put it in the proxy in front.

License

MIT. See LICENSE.

Documentation

Index

Constants

View Source
const (
	// RealIPSourcePeer uses the address of the host that opened the
	// connection and ignores forwarding headers entirely. It is the default
	// because those headers are client-supplied data: with nothing trusted in
	// front, any caller can claim any address it likes.
	RealIPSourcePeer = "peer"
	// RealIPSourceXFF reads X-Forwarded-For, walking the chain from the right
	// and stopping at the first hop that is not a trusted proxy. Use it only
	// when a proxy this server trusts is always in front and that proxy
	// overwrites, rather than appends to, an incoming X-Forwarded-For.
	RealIPSourceXFF = "xff"
)

The values accepted by HttpConfig.RealIPSource. They decide where echo.Context.RealIP() reads the client address from, which is a property of the deployment topology rather than of this package, and so has to be configurable.

Variables

This section is empty.

Functions

func HTTPResponse

func HTTPResponse(c echo.Context, data interface{}) error

HTTPResponse writes data as JSON: a confirmation as itself, under the status that confirmation means, and anything else with 200 under a "data" key.

A pointer to a confirmation is treated exactly as the value is, so HTTPResponse(c, &PostConfirmation{...}) and HTTPResponse(c, PostConfirmation{...}) produce the same 201 and the same body. They did not until now: the type switch matched value types only, so the pointer form — which is what anyone building the confirmation in a variable first ends up writing — fell through to the envelope and answered 200 wrapped in "data". Nothing about the call site said so, and the difference is only visible in the response.

A nil pointer is not a confirmation. A typed nil carries no resource, no id and no message, so answering 201 with a body of null would report a creation that has nothing in it; it takes the envelope instead and comes out as 200 {"data":null}, which is what an untyped nil has always produced.

func NewHTTP

func NewHTTP(cfg *HttpConfig, log Logger) (*httpServer, error)

NewHTTP builds a server from cfg, or from the environment when cfg is nil, and returns the first configuration error it finds rather than a half-built server.

log is the three-method Logger this package writes its access log and its readiness log through. Any logger satisfies it structurally, including github.com/zionmedianetwork/logam's Logger, so callers passing one of those are unaffected by it being named here. It is required: a nil one is refused here rather than substituted for.

Types

type Confirmation

type Confirmation struct {
	Message string `json:"message"`
}

type HttpConfig

type HttpConfig struct {
	BindAddress  string `split_words:"true" default:":8080"`
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	// ShutdownTimeout is the grace period in-flight requests are given to
	// finish once a termination signal arrives. Read from
	// HTTP_SHUTDOWN_TIMEOUT; defaults to defaultShutdownTimeout.
	ShutdownTimeout time.Duration `split_words:"true"`
	// RequestTimeout bounds how long a handler may run before the request
	// context is cancelled and the caller is answered with 503. Read from
	// HTTP_REQUEST_TIMEOUT; defaults to defaultRequestTimeout, which is zero
	// and means no timeout.
	//
	// The default is off because this package cannot see the routes it will
	// carry. A blanket timeout is wrong for the traffic this network exists to
	// serve — large downloads and uploads, and any streaming or SSE route hold
	// a request open by design — and a library that switched one on at upgrade
	// time would convert those into 503s without anybody changing a line of
	// code. Turning it on is one variable; guessing on a consumer's behalf is
	// not recoverable.
	//
	// When set it must be strictly below WriteTimeout, or the connection is
	// severed before the 503 can be written and the timeout produces a
	// transport error instead of a response. NewHTTP refuses a value that is
	// not.
	RequestTimeout time.Duration `split_words:"true"`
	// TimeoutExemptPaths lists the routes RequestTimeout does not apply to:
	// the streaming, download and upload endpoints that are meant to run long.
	// Read from HTTP_TIMEOUT_EXEMPT_PATHS as a comma-separated list, and inert
	// while RequestTimeout is zero.
	//
	// Entries are matched against the registered route pattern rather than the
	// request URL, so a parameterised route is named by its pattern
	// ("/videos/:id/stream", not "/videos/42/stream") and the static route
	// registered by this package is "/static*". Every entry must start with a
	// slash; NewHTTP refuses one that does not.
	TimeoutExemptPaths []string `split_words:"true"`
	// ReadinessTimeout bounds a single readiness probe, covering all
	// registered checks together. Read from HTTP_READINESS_TIMEOUT; defaults
	// to defaultReadinessTimeout. A non-positive value is treated as unset.
	ReadinessTimeout time.Duration `split_words:"true"`
	// MaxBodyLimit is the largest request body accepted, written in gommon's
	// byte notation: 10M, 512K, 4MiB. Read from HTTP_MAX_BODY_LIMIT; defaults
	// to defaultMaxBodyLimit. An unparseable value is reported by NewHTTP.
	MaxBodyLimit string `split_words:"true"`
	StaticPath   string `split_words:"true" default:""`
	// AlllowedOrigins is the CORS allowlist: the origins a browser may make
	// cross-origin requests from. Read from HTTP_ALLLOWED_ORIGINS — three L's,
	// the field is misspelled and envconfig derives the variable from it — as a
	// comma-separated list. It defaults to empty, which allows no cross-origin
	// access at all.
	//
	// The default used to be "*", and that is the change to know about. A
	// wildcard default means a service that never sets the variable ships an
	// open policy for every method this package allows, including POST, PUT,
	// PATCH and DELETE, to any site that can get a browser to send the request.
	// Nothing about that is visible in a deployment's configuration, because the
	// configuration is empty. A default has to be the answer for the deployment
	// that has not thought about the question, and for cross-origin access that
	// answer is no.
	//
	// "*" remains available and is one variable away: HTTP_ALLLOWED_ORIGINS=*
	// restores the previous behaviour exactly. It is not as dangerous as it
	// looks — this package never sets Access-Control-Allow-Credentials, so a
	// wildcard cannot be used to read an authenticated response — but it is
	// still a decision, and it now has to be made rather than inherited.
	//
	// Entries name a scheme and host with no trailing slash
	// ("https://app.example.com"), optionally with a wildcard in the host
	// ("https://*.example.com"). NewHTTP refuses anything else: an origin that
	// cannot match the Origin header a browser sends would sit in the config
	// looking like an allowance that works.
	AlllowedOrigins []string `split_words:"true"`
	// AllowedHeaders is the request-header allowlist a CORS preflight is
	// answered with. Read from HTTP_ALLOWED_HEADERS — one L, unlike the origins
	// variable above — as a comma-separated list; defaults to
	// defaultAllowedHeaders.
	//
	// Left unset before, echo reflected whatever the browser asked for in
	// Access-Control-Request-Headers, which is to say it allowed every header
	// unconditionally. The default list is the set a JSON API over this package
	// actually needs, and it includes X-Request-Id on purpose: this package
	// honours a client-supplied one as the correlation id, and a browser cannot
	// send it unless the preflight says it may.
	//
	// HTTP_ALLOWED_HEADERS=* restores "any header the browser asks for". The
	// wildcard is honoured for requests without credentials, which is all this
	// package emits, with the one exception the fetch standard carves out:
	// Authorization is never covered by "*" and has to be listed by name.
	AllowedHeaders []string `split_words:"true"`
	// CorsMaxAge is how long a browser may cache a CORS preflight. Read from
	// HTTP_CORS_MAX_AGE; defaults to defaultCorsMaxAge. Zero sends no
	// Access-Control-Max-Age header, which is what this package did before and
	// makes a browser preflight every non-simple cross-origin request again.
	//
	// The default lives in the struct tag rather than in NewHttpConfig, unlike
	// most of this file, precisely so that zero stays reachable and keeps
	// meaning "off": a default applied to a zero value would leave a deployment
	// no way to ask for the old behaviour.
	//
	// The value is sent in whole seconds. NewHTTP refuses a negative duration,
	// and refuses a positive one below a second, which would truncate to zero
	// and silently turn the feature off.
	CorsMaxAge time.Duration `split_words:"true" default:"1h"`
	// DisableSecurityHeaders turns off the baseline response headers this
	// package otherwise sets on every response: X-Content-Type-Options,
	// X-Frame-Options, Referrer-Policy and X-XSS-Protection. Read from
	// HTTP_DISABLE_SECURITY_HEADERS; defaults to false, so the headers are on.
	//
	// They are on by default because they cost one map write each, they change
	// nothing for a non-browser client, and every one of them removes a class of
	// browser behaviour nobody wants from an API: content sniffed into an
	// executable type, a JSON endpoint framed by another site, a path with an id
	// in it leaked to a third party through Referer.
	//
	// The name is negative so that the zero value is the safe one. A positively
	// named bool defaulting to true could only be defaulted where the
	// environment is read, which would leave the headers off for every consumer
	// that builds an HttpConfig in Go instead.
	DisableSecurityHeaders bool `split_words:"true"`
	// HstsMaxAge is the max-age sent in Strict-Transport-Security. Read from
	// HTTP_HSTS_MAX_AGE; defaults to zero, which sends no HSTS header at all.
	//
	// Off by default, and this is the one security header that must be. HSTS is
	// a durable instruction to the browser rather than a property of one
	// response: for max-age seconds afterwards that browser refuses to speak
	// plaintext to the host, and the only way to undo it early is to serve
	// max-age=0 over working HTTPS. This process speaks H2C with no TLS of its
	// own, so whether the origin it is reached at is HTTPS everywhere is a fact
	// about a deployment's ingress that this package cannot see. Emitting HSTS
	// by default would let a library upgrade take a hostname offline for
	// whatever plaintext still depends on it.
	//
	// When it is set, echo emits the header only for requests that arrived over
	// TLS or carried X-Forwarded-Proto: https — so it also depends on the proxy
	// in front setting that header, and on that proxy being the only thing that
	// can.
	//
	// NewHTTP refuses a negative value, a positive value below a second, and a
	// value set while security headers are disabled.
	HstsMaxAge time.Duration `split_words:"true"`
	// HstsIncludeSubdomains adds includeSubdomains to the HSTS header. Read from
	// HTTP_HSTS_INCLUDE_SUBDOMAINS; defaults to false, and inert unless
	// HstsMaxAge is set — NewHTTP refuses the combination that is not, since it
	// reads as HSTS having been configured when no header is sent.
	//
	// Default false because the subdomain form is the irreversible part: it
	// pins every name under the domain, including ones this service knows
	// nothing about and ones that do not exist yet, for the whole max-age.
	HstsIncludeSubdomains bool `split_words:"true"`
	// RateLimit is the number of requests per second allowed from one client
	// address. Read from HTTP_RATE_LIMIT; defaults to zero, which is off.
	//
	// Off by default for three reasons, none of which a library can resolve on a
	// consumer's behalf. The limiter is per process, so the limit a fleet
	// actually enforces is this number times the replica count, and it changes
	// every time the deployment scales. Its store is in memory, so it holds one
	// bucket per distinct client address — bounded only by
	// defaultRateLimitExpiry, which is fine behind a proxy and is a different
	// proposition facing the open internet. And it is keyed on c.RealIP(), so it
	// inherits HTTP_REAL_IP_SOURCE: with the wrong source configured, every
	// caller shares one bucket or every caller can mint a new one at will, and a
	// limit keyed on a spoofable address is worse than no limit because it looks
	// like protection.
	//
	// Liveness and readiness paths are never rate limited. A 429 on /readyz
	// takes the instance out of load balancing and a 429 on /healthz can have an
	// orchestrator restart it, which turns a burst of traffic into an outage.
	RateLimit float64 `split_words:"true"`
	// RateLimitBurst is how many requests may arrive at once before the rate
	// applies. Read from HTTP_RATE_LIMIT_BURST; defaults to one second's worth
	// of requests at RateLimit, and never less than one — a burst of zero denies
	// every request, which is what a fractional rate would otherwise silently
	// produce.
	//
	// Inert while RateLimit is zero, and NewHTTP refuses that combination rather
	// than leaving a burst configured against a limiter that does not run.
	RateLimitBurst int `split_words:"true"`
	// Gzip compresses responses for clients that accept it. Read from HTTP_GZIP;
	// defaults to false.
	//
	// Off by default because this package carries media. Compressing an MP4, a
	// JPEG or any other already-compressed payload spends CPU on both ends to
	// produce something no smaller, and gzip buffers: a streaming or SSE route
	// only keeps streaming because echo's writer forces a gzip flush on every
	// Flush call, and the proxies in front are under no such obligation.
	//
	// When it is on, the routes named in TimeoutExemptPaths are skipped, along
	// with the probe paths. That list already names the routes a deployment has
	// declared long-running — the streams, the downloads, the uploads — which is
	// the same set compression should stay out of.
	Gzip bool `split_words:"true"`
	// Debug makes echo's default error handler put the error a handler
	// returned into the JSON response body. Read from HTTP_DEBUG; defaults to
	// false, because those errors carry SQL text, file paths, upstream URLs
	// and connection-string credentials straight to the caller.
	Debug bool `split_words:"true"`
	// RealIPSource selects where echo.Context.RealIP() reads the client
	// address from: RealIPSourcePeer or RealIPSourceXFF. Read from
	// HTTP_REAL_IP_SOURCE; defaults to RealIPSourcePeer.
	RealIPSource string `split_words:"true"`
	// TrustedProxies lists, in CIDR notation, the hops allowed to relay a
	// client address in X-Forwarded-For. Read from HTTP_TRUSTED_PROXIES as a
	// comma-separated list, and only meaningful when RealIPSource is
	// RealIPSourceXFF. Left empty, loopback and the private ranges are
	// trusted, which covers the usual sidecar and cluster-internal ingress;
	// set, the list is exhaustive and nothing outside it is trusted.
	TrustedProxies []string `split_words:"true"`
}

func NewHttpConfig

func NewHttpConfig() (*HttpConfig, error)

type Logger added in v0.1.0

type Logger interface {
	// Infow records a request that was served and a dependency that has come
	// back after failing.
	Infow(msg string, keysAndValues ...interface{})
	// Warnw records a readiness check that is failing. It is the only place the
	// cause of a failing check is written down: the probe response withholds it
	// unless Debug is set. See logReadiness for why this is warn and not error.
	Warnw(msg string, keysAndValues ...interface{})
	// Errorw records a request the server failed to serve: the handler chain
	// returned an error, or answered 5xx.
	Errorw(msg string, keysAndValues ...interface{})
}

Logger is what this package needs from a logger, and all of it: three structured methods, which are the three it calls.

It is declared here rather than imported so that using this package does not oblige a consumer to adopt a particular logging library. "Accept interfaces, and declare them where they are consumed" pays for itself directly here: github.com/zionmedianetwork/logam's Logger carries seventeen methods, of which this package calls Infow, Warnw and Errorw. Naming that type in the signature would have made the other fourteen — Fatal, Print, Tracef and the rest — the price of admission for anyone whose logger is slog, zerolog or logrus, and every one of them would have been written to satisfy a compiler and never called.

Go satisfies interfaces structurally, so this is not a break for anyone: a logam.Logger still satisfies Logger and existing calls to NewHTTP compile unchanged. logam simply stops being something a consumer has to depend on.

The arguments after msg are alternating keys and values — "status", 503 — the convention zap's SugaredLogger established and slog shares.

Wiring log/slog from the standard library takes three one-line methods and no dependency at all:

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...) }

srv, err := server.NewHTTP(nil, slogLogger{l: slog.Default()})

slog takes the same alternating key/value arguments, so that adapter forwards them untouched; a logger with a different shape converts them in the same three methods. No such adapter is exported from this package. It would be six lines of code and a permanent piece of public API, and every consumer needs a slightly different one — their own handler, their own level mapping, a request-scoped logger pulled from a context — so the type belongs in the consumer, where it can be exactly what that consumer wants.

This package logs through the value it is given on every request and every readiness probe, and installs no no-op default in its place.

type PatchConfirmation

type PatchConfirmation struct {
	PostConfirmation
}

type PostConfirmation

type PostConfirmation struct {
	Resource string `json:"resource"`
	Message  string `json:"message"`
	ID       string `json:"id"`
}

type ReadinessCheck added in v0.1.0

type ReadinessCheck func(ctx context.Context) error

ReadinessCheck reports whether one dependency is usable right now. A nil error means it is; any error means it is not, and the endpoint answers 503.

The check is handed a context carrying the probe's deadline and must respect it: a check that blocks regardless is abandoned once the deadline passes and reported as failed, but its goroutine keeps running until it returns on its own. Prefer the context-aware call the driver already offers — sql.DB.PingContext, redis Ping with a context, an HTTP request built with http.NewRequestWithContext.

A check runs on every probe, so it should be cheap: a ping, not a query.

type ResponsePayload

type ResponsePayload map[string]interface{}

ResponsePayload is the envelope this package wraps an ordinary payload in, and a convenient type for building an ad-hoc one by hand.

Directories

Path Synopsis
examples
behind-proxy command
Command behind-proxy is a production-shaped configuration for running behind a TLS-terminating load balancer, and a route that lets you see the one setting people get wrong: where c.RealIP() reads the client address from.
Command behind-proxy is a production-shaped configuration for running behind a TLS-terminating load balancer, and a route that lets you see the one setting people get wrong: where c.RealIP() reads the client address from.
minimal command
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.
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.
readiness command
Command readiness demonstrates the split between liveness and readiness.
Command readiness demonstrates the split between liveness and readiness.
streaming command
Command streaming is the media-service case: a request timeout tight enough to protect the ordinary API, and a streaming route that must not be killed by it.
Command streaming is the media-service case: a request timeout tight enough to protect the ordinary API, and a streaming route that must not be killed by it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL