The Six Things We Didn't Build: What the Framework Teaches

Part of a research project’s value is what it deliberately left out. This closing post inventories gortex’s six unbuilt directions and what the whole framework teaches.

Correction (2 November 2026, 18:45 Taipei): request-level timeouts are now described as cooperative cancellation that holds only when the handler and its I/O honour the ctx; zero reflection is now limited to router lookup, since handler dispatch still goes through reflect.Value.Call. Suggested by Codex (gpt-6-astra), checked by Claude.

The six unbuilt directions

Gortex’s own design doc lists six “worth doing, not done” directions. What they share: each looks one mile away, and each hides production-grade devils in the detail.

  1. The full graceful-shutdown chain: the hub in The WebSocket Hub: Go’s Take on the Actor Model already has basic graceful shutdown, but production-grade also needs draining (remove from the load balancer first, via K8s preStop plus readiness flipped false, then let in-flight requests finish), shutdown ordering (HTTP listener → drain → WS Hub → DB pool), and propagating the OS signal’s deadline down to every subsystem.
  2. Error semantics in the middleware chain: today a middleware returns an error and ServeHTTP handles it uniformly. A production framework also distinguishes retryable vs non-retryable, should-log vs already-handled, and the error boundary: once a layer swallows an error, can the layers above still observe it?
  3. Config hot-reload: pkg/config loads once. A K8s ConfigMap is updated into the mounted directory, so an fsnotify watch would let you change log level, rate-limit thresholds, or feature flags without a restart.
  4. Request-level timeout propagation: there’s no “global request timeout” today. A production framework usually sets a deadline context in the outermost middleware, so a handler that forgets a timeout still can’t hang forever, as long as the handler and its downstream I/O honour that ctx (the per-check timeout in Observability: Three-State Health Checks and a Tracing Abstraction is a local version of the same move). Cancellation is cooperative: code that ignores the ctx keeps running.
  5. Structured errors: pkg/errors is a flat code→message registry today. A more advanced design has error-code namespaces, error chains, and i18n:
// today: a flat code → message
// wanted: namespaces + layered matching
err := errors.New("ORDER.PAYMENT_FAILED", ...)
if errors.Is(err, order.ErrPayment) { /* handle by layer */ }
  1. OpenAPI / Swagger generation: core/app/doc/ has a swagger.Provider skeleton, but spec generation isn’t finished. Deriving an OpenAPI spec from struct tags + method signatures is the natural extension of the declarative routing in Struct-Tag Routing: reflect in Practice.

What the framework teaches

Read the whole series backwards and a few recurring principles surface:

Closing

Gortex isn’t an open-source framework out to compete with Gin or Echo; it’s a reference implementation, for research and record, not production. Its value is two-sided: it lays out the decisions a platform framework has to make (where the kitchen-sink post started), and the “six things we didn’t build” list is itself a map of where production-grade infrastructure actually gets hard.

Knowing what to build, what to deliberately leave out, and why: that’s probably the most worthwhile thing to take from reading a framework’s source.

Notes

  • The six unbuilt directions (full graceful shutdown, middleware error semantics, config hot-reload, request-level timeout, structured errors, OpenAPI generation) each stall on production-grade detail.
  • The series’ throughline: the answer is context-dependent, pay the cost once, pick the tool by shape, program to interfaces, fail loud + bound inputs, be honest about limits.
  • Gortex is a reference implementation; its value is in demonstrating decisions and deliberate omissions, not in being a production framework.
  • The “didn’t build” list is itself a map of where production-grade infrastructure is hard.
  • The most worthwhile takeaway from reading a framework: knowing what to build, what to skip on purpose, and why.

Source: yshengliao/gortex.


Ideas and technical judgement by Sheng; drafted with Claude · Go 1.25 (gortex go.mod) · compiled retroactively · part of the 2026-06-13 blog renovation, paint still drying.