Check or emphasize that protobuf endpoints must be rooted at a versioned path

[jpeach]

Description

The clutch HTTP muxer checks that gRPC gateway URLs are rooted at the path /v[0-9]+.

clutch/backend/gateway/mux/mux.go

Lines 38 to 39 in 0aa0f85

	var apiPattern = regexp.MustCompile(`^/v\d+/`)

clutch/backend/gateway/mux/mux.go

Lines 59 to 63 in 0aa0f85

	if apiPattern.MatchString(r.URL.Path) || r.URL.Path == "/healthcheck" {
	// Serve from the embedded API handler.
	a.next.ServeHTTP(w, r)
	return
	}

This is a trap for young players, and it took me a while to figure out why clutch served a 500 when I used an initial path component of /foo. It would be best if clutch enforced this constraint by inspecting the protobuf types at startup, but otherwise it would be nice to emphasize this in the docs.

[danielhochman]

I threw together a quick prototype for doing this at runtime: https://github.com/lyft/clutch/compare/validate-pattern-at-runtime

But we should probably do it during compilation. Since Buf doesn't allow custom linting rules, we will need to write our own linter using protoparse. It shouldn't be that difficult, we already use protoparse for documentation generation.

Alternatively we could also log a warn at runtime. Maybe that is the best option since everyone might not be linting. For example we don't tell the user to run linting on the amiibo example: https://clutch.sh/docs/development/feature.

@jpeach any thoughts here?