Gear and a Go web framework built on net/http and middleware

A framework that sits on top of net/http

Gear is described as a lightweight, composable and high performance web service framework for Go, and the first decision in its design document settles most of its character: the server is built on the native net/http rather than fasthttp.

That choice is the framework's identity. There is a whole class of Go web frameworks that swap the standard HTTP stack out for a faster one, and the trade is always the same: throughput against the ecosystem, the handler signatures and the middleware that assumes a particular server. Gear declines that trade. Everything in the feature list, from the router to the context to the middlewares, sits on top of net/http, which means the standard library's server behaviour, its HTTP/2 support and its connection handling are what you get.

The Go module confirms the era. The go directive is 1.20, and the direct dependencies are small and specific: a cookie utility, a content negotiator, the testify test library, a trie-based mux called trie-mux from the same organisation, and golang.org/x/net. The last one matters, since x/net is where the HTTP/2 and HTTP/3 support lives, which is consistent with the claim of complete HTTP/2.0 support.

The primary language is Go, the licence is MIT, the default branch is master, and the last push was on 2026-07-02. There are no GitHub releases, so there is no tagged version to pin, and the version you get is whatever commit you clone.

The audience is a Go developer who wants the ergonomics of a framework without leaving the standard library, and who is comfortable with a framework whose design is documented in a design document rather than only in godoc.

The middleware model and the context that carries state

The feature list leads with middleware flow control, described as effective and flexible, with the tagline that you can create anything by middleware. That is the framework's central mechanism, and the design document spells out how it works.

There are two flow modes. The middleware has a single-direction sequential flow control, and there is also a cascade flow control. Then there are the After Hook and End Hook for post-processing, and an Any interface giving unlimited state extension capability on the context. The design document's own list of topics covers the server base, the middleware extension model, the single-direction and cascade flow control, the context integrated with context.Context, centralised error and exception handling, the after and end hooks, the context state extension, and request data parsing and validation.

That is a lot of machinery, and the reason for it is worth understanding. In many Go frameworks the middleware is a function that wraps a handler, and ordering is obvious but there is no way to run something after the response is written, because the response has already gone out. Gear's after and end hooks exist for exactly that: work that must happen once the response is committed.

The context is the other half. It is integrated with context.Context, which means request-scoped values follow the standard Go cancellation and deadline propagation, and it can carry arbitrary state through the Any interface, so a middleware can attach a value that a later handler reads without a package-level variable.

The error handling is centralised and described as powerful and smart, and the design document's topic is centralised, intelligent and customisable error and exception handling. Centralised error handling in Go usually means the handler returns an error rather than writing a response, and the framework decides what to do with it. That is the pattern the hello example below shows, and it is what makes the app.Error call at the end of the example meaningful.

A first server, and what the example shows

The hello example is short enough to read in one go, and it shows the whole shape of a Gear application.

  app := gear.New()

  // Add logging middleware
  app.UseHandler(logging.Default(true))

  // Add router middleware
  router := gear.NewRouter()

A Gear application is an app, a set of middlewares registered on it, and a router registered as another middleware. The logging middleware goes on with UseHandler, and the router is created separately and then attached the same way, which is what makes the middleware order explicit and readable.

Handlers are functions taking a *gear.Context and returning an error, and the response is written by calling methods on the context:

  router.Get("/hello", func(ctx *gear.Context) error {
    return ctx.HTML(200, "<h1>Hello, Gear!</h1>")
  })

The error return is the mechanism, and returning ctx.HTML from it is the shorthand. The catch-all handler shows the same pattern with JSON:

  router.Otherwise(func(ctx *gear.Context) error {
    return ctx.JSON(200, map[string]any{
      "Host":    ctx.Host,
      "Method":  ctx.Method,
      "Path":    ctx.Path,
      "URI":     ctx.Req.RequestURI,
      "Headers": ctx.Req.Header,
    })
  })

The Otherwise handler is the framework's not-found route, and it reflects the request back, which makes it a useful debugging tool. Note that ctx.Req is the standard *http.Request, and ctx.Path, ctx.Host and ctx.Method are conveniences on top of it.

The last two lines of the example are the ones to note:

  app.UseHandler(router)
  app.Error(app.Listen(":3000"))

The router is attached after the logging middleware, so the order of registration is the order of execution. And the server error is passed to app.Error rather than being ignored, which is how a listen failure on a port already in use reaches you instead of disappearing.

For a Go developer, the shape is familiar enough to read in a minute, which is the main argument for a framework that stays close to the standard library.

The router, and what it delegates

The router is described as a trie base HTTP request handler, described as as fast as the httprouter project it links to, supporting regexp parameters and group routes.

Its own feature list is where the differences from a plain mux appear. It supports named parameters, regexp matching, suffix matching, multi-router, router layer middlewares, fixed path automatic redirection, trailing slash automatic redirection, and automatic handling of 405 Method Not Allowed and of the OPTIONS method. The claim at the end of the list is best performance, which is a benchmark claim you should check yourself rather than take on faith.

Two of those features carry more weight than the rest. Router layer middlewares means you can attach middleware to a group of routes rather than to the whole application, which is how a router that supports groups earns the group route support in the first place. And automatic handling of OPTIONS is not a detail: a preflight request that returns 405 is a broken CORS setup, and a framework that answers it correctly removes a class of debugging.

The implementation detail to notice is in the dependency list. The router is not built in; it is teambition/trie-mux, a separate module. Gear wraps it, adds the group and middleware behaviour, and ties it into the context and error model. That is a reasonable division, since a trie router is a self-contained data structure with a benchmarkable interface, but it means the routing behaviour has two upstream sources and you will find yourself reading trie-mux documentation when a route does not match.

The repository layout shows the framework split into the pieces the feature list implies: app.go for the application and the server wiring, router.go for the routing, context.go for the request context, response.go for the response helpers, compress.go for the response content compression, and util.go and const.go for the shared helpers. Each has a matching test file, and the logging/ and middleware/ directories hold the built-in middlewares.

The examples directory is broader than the README suggests, with entries for file download, gearproxy, hello, http2, pprof, quic, sse and staticgo, which is a better map of what the framework actually supports than the feature list alone.

Middlewares, command line tools and the gRPC example

The built-in middlewares are the part of the feature list that saves the most time, and they cover the usual ground: integrated timeout context.Context, integrated response content compress, integrated structured logging middleware, integrated request body parser, integrated signed cookies, and integrated CORS, Secure, Favicon and Static middlewares. The context also carries more useful methods for manipulating the HTTP request and response.

Two of the examples are complete command line tools that are worth knowing about, because they show the framework doing the work of a small server with very little code.

The static server is installed with the go tool:

go install github.com/teambition/gear/example/staticgo@latest

It is described as a useful command line tool that serves your local files as a web server, with TLS support, and the osx, linux and windows versions can be built with make build. The example source takes an address flag defaulting to 127.0.0.1:3000, a path flag for the static files to serve, and certFile and keyFile flags used to create a TLS static server. The logic is: if both certificate and key are given, listen with TLS, otherwise listen plainly.

The reverse proxy is installed the same way:

go install github.com/teambition/gear/example/gearproxy@latest
gearproxy -help

The second line matters in a small way, because the installation command does not tell you what the tool is called, and the tool is not on your path under the package name.

The HTTP2 example shows server push, which is the feature that distinguishes the framework from a plain net/http server. The route handler calls ctx.Res.Push for a stylesheet path with http.PushOptions, and the stylesheet route then serves it, with the whole app served over TLS so that HTTP/2 is negotiated.

There are also separate gRPC server and client examples. The claim that HTTP and gRPC run on the same port is the interesting one there, since it means a single listener serves both protocols, and the repository also carries quic and sse examples that the feature list does not mention at all.

The limits, and the case against a new dependency

Three limits follow from what the project is and where it sits.

The first is the release state. There are no GitHub releases, the module version is not published as a tag, and the go directive is still 1.20 while the toolchain has moved well past that. A framework with no released version means your build is pinned to a commit, and upgrading is a diff rather than a version bump. For a service where the framework owns request parsing, routing and error handling, that is a dependency you will carry for a long time on the least stable basis the ecosystem offers.

The second is that much of what Gear provides is now close to the standard library. The Go module targets 1.20, and the standard library's ServeMux gained method and wildcard pattern matching in that release, which covers a good part of what the router's named parameters and group routes are for. A team starting today can plausibly build the same service on net/http plus a router library plus a logging library, with fewer abstractions to reason about.

The third is the size of the framework's own surface. The middleware model with single-direction flow, cascade flow, after hooks, end hooks and Any-typed context state is a substantial concept to hold in your head for the sake of features that most services will use once. A framework that is easy to extend is also a framework where it is easy to build something only you understand, and the design document's eight topics are each a decision you will have to make deliberately rather than by default.

The alternative worth comparing is the standard library plus a router. The difference in approach is that Gear gives you one import, one context type and one error model across the whole application, while the standard library route gives you a smaller dependency set and a request context that is exactly http.Request with your own middleware type. The trade is coherence against minimalism, and for a service that will not grow a large middleware surface, minimalism usually wins.

Where Gear still earns its place is a codebase with a lot of shared HTTP behaviour, where the middleware chain and the after and end hooks are the point rather than an accident.

Editorial conclusion

Gear is a good fit for a Go team that wants net/http rather than a framework that replaces it, and that needs the framework conveniences such as a router with named and regexp parameters, a request context with state, and a middleware chain with post-processing hooks, since those are the parts Gear adds and nothing else. It is a poor fit for a new greenfield service, because the framework has not shipped a release, the module still targets Go 1.20 while current Go is further ahead, and the same job is done today by the standard library's enhanced ServeMux plus a mature third-party router. Before adopting, check the Go version floor in go.mod against what you run, and read the design document, because the middleware ordering model with its single-direction flow and cascade flow is the part you will have to reason about most.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. teambition/gear on GitHub