Routing

In Copper, each package that serves HTTP defines a router, which is any type that implements a single-method interface:

type Router interface {
	Routes() []chttp.Route
}

When the app starts, Copper collects every router into a single handler.

Defining Routes

To add routes to a package, scaffold a router with the CLI:

copper scaffold:router rockets

This creates pkg/rockets/router.go, registers the router in pkg/app/handler.go, and adds it to the package’s wire module. A router looks like this:

pkg/rockets/router.go

type NewRouterParams struct {
	Logger clogger.Logger
}

func NewRouter(p NewRouterParams) *Router {
	return &Router{logger: p.Logger}
}

type Router struct {
	logger clogger.Logger
}

func (ro *Router) Routes() []chttp.Route {
	return []chttp.Route{
		{
			Path:    "/api/rockets",
			Methods: []string{http.MethodGet},
			Handler: ro.HandleListRockets,
		},
		{
			Path:    "/api/rockets/{id}",
			Methods: []string{http.MethodGet},
			Handler: ro.HandleGetRocket,
		},
	}
}

Handlers are plain http.HandlerFuncs. Anything your handlers need, such as services, a *chttp.JSONReaderWriter, or config, may be added as a field on NewRouterParams, and wire will inject it for you.

Path Parameters

Parameters are declared in the path with {name} and read using chttp.URLParams:

func (ro *Router) HandleGetRocket(w http.ResponseWriter, r *http.Request) {
	var (
		ctx = r.Context()
		id  = chttp.URLParams(r)["id"]
	)

	// ...
}

You may also constrain a parameter with a regular expression; for example, {id:[0-9]+} only matches numeric IDs. Since routing is backed by gorilla/mux, its full pattern syntax is available.

Query Parameters

Query parameters may be read directly from the request:

status := r.URL.Query().Get("status")

Route Matching

You never need to worry about the order in which routes are declared. Copper will automatically sort them so that deeper paths match first and literal segments take priority over parameters at the same depth. For example, /rockets/featured always wins over /rockets/{id}, while a catch-all such as /{path:.*} matches last.

Registering Routers

copper scaffold:router handles this for you, but it is useful to know where routers live. The app’s HTTP handler is assembled in pkg/app/handler.go:

pkg/app/handler.go

func NewHTTPHandler(p NewHTTPHandlerParams) http.Handler {
	return chttp.NewHandler(chttp.NewHandlerParams{
		Routers: []chttp.Router{
			p.Rockets,
		},
		GlobalMiddlewares: []chttp.Middleware{
			chttp.SetRequestIDInCtxMiddleware(),
			p.DatabaseTxMW,
			p.RequestLoggerMW,
		},
		Logger: p.Logger,
	})
}

Serving Under a Base Path

If you would like to mount your entire app under a prefix, you may set base_path in your config:

[chttp]
base_path = "/admin"

Declare your route paths with the prefix included; Copper strips it at registration time.

When base_path is set, routes that don’t start with the prefix are skipped. You may set RegisterWithBasePath: true on a route to have the prefix joined onto its path instead, which is how Copper’s static file routes work.

Getting Started

The Basics

Architecture

HTTP

Database

Frontend

Digging Deeper

Reference

Defining Routes

Path Parameters

Query Parameters

Route Matching

Registering Routers

Serving Under a Base Path

​Defining Routes

​Path Parameters

​Query Parameters

​Route Matching

​Registering Routers

​Serving Under a Base Path

Defining Routes

Path Parameters

Query Parameters

Route Matching

Registering Routers

Serving Under a Base Path