Skip to content
HTTP Runtime

HTTP Runtime

Generated HTTP code talks to httpx, not to Gin, Fiber, Echo, or Hertz directly. server/httpz adds the JSON envelopes and handler wrappers that official templates use.

Layers

LayerPackageRole
Router contractgithub.com/go-sphere/httpxEngine, Router, Handler, Middleware, Context, Streamer
Adaptershttpx/stdx, httpx/ginx, httpx/fiberx, httpx/echox, httpx/hertzxstdx is plain net/http; the rest wrap a concrete framework
Responsesgithub.com/go-sphere/sphere/server/httpzWithJson, WithSSE, DataResponse, ErrorResponse, SSEStream
Middlewaresphere/server/middleware/*Auth, CORS, online, rate limiter, selector

protoc-gen-sphere defaults are httpx.Router / httpx.Context / httpx.Handler, with httpz.WithJson for unary methods and httpz.WithSSE for server-streaming methods. See protoc-gen-sphere.

Success Envelope

{
  "success": true,
  "data": { }
}

httpz.WithJson writes HTTP 200 unless the handler set a status through httpx.ResponseInfo (for example 201).

Error Envelope

{
  "success": false,
  "code": 1001,
  "message": "User not found"
}

Rules enforced by httpz.AbortWithJsonError:

  • HTTP status comes from httpx.StatusError (or the parser). Invalid statuses become 500.
  • code is an application code. It is 0 unless the error implements httpx.CodeError.
  • message is user-facing. It is the generic status text unless the error implements httpx.MessageError with a non-empty message.
  • error (err.Error()) is included only when httpz.SetDebugMode(true).

Typed proto errors generated by protoc-gen-sphere-errors implement those interfaces, so .Join() / returning the enum produces a stable client payload. Plain fmt.Errorf and driver errors do not leak internal text in production.

Binding

Generated handlers bind through httpx.Context:

if err := ctx.BindJSON(&in); err != nil {
    return nil, err
}
if err := ctx.BindQuery(&in); err != nil {
    return nil, err
}
if err := ctx.BindURI(&in); err != nil {
    return nil, err
}

GET/HEAD/DELETE/OPTIONS never call BindJSON, even if the proto declared body. Enable fail_on_warn on protoc-gen-sphere if you want that to fail generation instead of warning.

Streaming

httpx.Streamer is the portable incremental-response capability implemented by every adapter. httpx.ServerSentEvents builds SSE framing on top of it and provides SSEWriter.Send, SendData, SendJSON, and Comment. Every event is flushed as one unit.

Generated server-streaming methods use a two-phase httpz.WithSSE handler:

return httpz.WithSSE(func(ctx httpx.Context) (httpz.SSEStream[*WatchResponse], error) {
    var in WatchRequest
    if err := ctx.BindQuery(&in); err != nil {
        return nil, err
    }
    stdCtx := ctx.Context()
    return func(send func(*WatchResponse) error) error {
        return srv.Watch(stdCtx, &in, send)
    }, nil
})

The prepare phase owns request binding and may return a normal JSON error before anything is committed. The producer phase must only use captured ordinary Go values—not httpx.Context—and must stop when send fails or the standard context is canceled.

By default, the first reply commits a 200 text/event-stream response. Reply messages are unnamed JSON data events, successful completion emits done, and a later failure emits error with the normal ErrorResponse. A producer failure before its first reply is still rendered as a regular JSON error status. After commit, the wrapper emits 15-second keep-alive comments and disables nginx buffering. Push endpoints that may wait indefinitely before their first reply can opt into eager commit through a custom stream wrapper; see the streaming guide for the trade-off.

stdx, Gin, Echo, and Hertz additionally implement httpx.Flusher for manually flushing a response inside a handler. Fiber does not, but its Streamer implementation works through Fiber’s deferred stream writer. In-process httpx.TestRequester calls buffer the final stream body, so use a real network connection to test incremental delivery and disconnect behavior.

See Server Streaming for the proto contract, service implementation pattern, client behavior, and deployment considerations.

Template Wiring

Official templates construct a net/http server and stdx engine from httpsrv.Options (internal/pkg/httpsrv):

httpServer := &http.Server{
    Addr:              addr,
    ReadHeaderTimeout: readHeaderTimeout, // 10s
    ReadTimeout:       opts.readTimeout(),
    IdleTimeout:       opts.idleTimeout(),
}
engineOpts := []stdx.Option{
    stdx.WithServer(httpServer),
    stdx.WithErrorHandler(httpz.AbortWithJsonError),
    stdx.WithMaxBodySize(opts.maxBodyBytes()),
}
if len(opts.TrustedProxies) > 0 {
    engineOpts = append(engineOpts, stdx.WithTrustedProxies(opts.TrustedProxies...))
}
engine := stdx.New(engineOpts...)

httpsrv.Options exposes four optional JSON/YAML fields (0 selects the default; a negative value disables the limit):

  • read_timeout_seconds — whole-request read timeout (default 30s; responses and SSE streams are not bounded by it)
  • idle_timeout_seconds — keep-alive idle timeout (default 120s)
  • max_body_bytes — engine-wide request body cap (default 4 MiB)
  • trusted_proxies — proxy IPs or CIDRs whose X-Forwarded-For header ClientIP trusts (default empty)

File-upload servers call opts.WithUploadDefaults(), which raises zero defaults to 5m (read_timeout_seconds) and 64 MiB (max_body_bytes).

stdx.WithAddr(addr) is enough when you do not need custom timeouts or server settings. Replace stdx with ginx, fiberx, echox, or hertzx without changing generated service interfaces. Keep:

  • generated Register*HTTPServer(route httpx.Router, srv ...)
  • binding tags from sphere.binding
  • httpz envelopes, unless you override the generator flags

Limits, Timeouts, and Trusted Proxies

  • Engine body cap (WithMaxBodySize): Available on all five httpx adapters (stdx, ginx, fiberx, echox, hertzx), limiting request bodies on every route to n bytes (n <= 0 disables). Requests declaring a larger Content-Length fail before route middleware runs, and streaming bodies passing n fail on read with *http.MaxBytesError. httpx.ParseError, httpz.ParseError, and WrapBindError classify *http.MaxBytesError as HTTP 413.
  • Trusted proxies (WithTrustedProxies): Configures trusted proxy IPs or CIDRs for ctx.ClientIP() across all five adapters. stdx and fiberx ignore forwarding headers by default until WithTrustedProxies is set; ginx, echox, and hertzx trust every peer by default unless WithTrustedProxies is called (passing no entries disables forwarding headers). Invalid entries panic at construction time, so templates validate trusted_proxies via Options.Validate() during config load.
  • File upload cap (fileserver.WithMaxUploadSize): Caps PUT upload bodies on fileserver.RegisterFileUploader. A declared Content-Length above n responds 413 before spending the one-time upload token; a streaming/chunked body exceeding n deletes any partial object and responds 413 with the token spent. Uploads are unbounded by default (n <= 0).

Middleware

There is one middleware form: a layer receives the rest of the chain and returns what runs in its place. Use registers it on an engine, a group, or a router.

type Middleware func(next httpx.Handler) httpx.Handler

func RequestID(next httpx.Handler) httpx.Handler {
    return func(ctx httpx.Context) error {
        ctx.SetContext(withRequestID(ctx.Context()))
        return next(ctx)
    }
}

Returning without calling next stops the chain (there is no Abort bookkeeping), and an error returned by next is rendered at the route where the chain was composed — a layer that logs or measures the outcome should read that error, not only ctx.StatusCode().

Where a layer runs:

  • A route’s chain is resolved when the route is registered. A late engine.Use reaches the routes an existing group registers afterwards; routes already registered keep the chain they were registered with.
  • Use layers always run inside anything mounted with the adapter’s UseNative (ginx, echox, fiberx, hertzx), whatever the registration order. stdx has no UseNative, because net/http has no native middleware type beyond the one AdaptStdMiddleware already takes.
  • An engine-scope chain also covers paths no route matched (404/405), so access logging, panic recovery, and CORS see them; a group’s chain never does, because a 404 belongs to no group.
  • ctx.SetContext values set below stay visible to the layers above after next returns.

Official templates register the shared logger layers at engine scope (internal/pkg/httpsrv/httpsrv.go):

engine.Use(logger.Log(lg), logger.RecoveryLog(lg, true))

sphere/server/middleware ships the same shape for auth, CORS, online tracking, rate limiting, selector, and logger. See Logging for the logger layer’s composition rules and Upgrading if you are migrating middleware written against the old func(httpx.Context) error form.

Custom Error Parser

The default parser is httpz.ParseError: httpx.ParseError plus the status of storage sentinels, which carry none of their own (storageerr.ErrNotFound → 404, storageerr.ErrDestExists / storageerr.ErrFileNameInvalid → 400; an httpx.StatusError in the chain still wins). Templates install a parser that maps protovalidate and Ent errors first. A parser set with httpz.SetDefaultErrorParser replaces the default entirely, so it must fall back to httpz.ParseError, not httpx.ParseError — otherwise a missing storage key renders as 500:

httpz.SetDefaultErrorParser(func(err error) (int32, int32, string) {
    var ve *protovalidate.ValidationError
    if errors.As(err, &ve) {
        return 0, 400, /* joined violation messages */
    }
    return httpz.ParseError(err)
})

The parser return is (code, status, message).

  • code is still zeroed unless the error implements httpx.CodeError.
  • message from httpx.MessageError always wins when non-empty.
  • Otherwise a non-empty parser message is used, falling back to the generic status text only when it is empty. Joined validation text comes back this way; httpz.ParseError returns an empty message for unclassified errors, so raw err.Error() strings never reach the client.
  • Adapter default error handlers use httpx.RenderError (status + {success, code, message}, no error field). Official templates install httpz.AbortWithJsonError through stdx.WithErrorHandler so middleware failures use the same envelope as WithJson.

NewXxxError(msg) / NewWithStatus(status, msg) put msg in GetMessage(). XxxError(err) without extra arguments still has an empty user message and becomes the generic status text. Bind failures are wrapped as httpx.BadRequestError in every adapter.

Related

Last updated on