go-shim-contract-stub-routing

Answer

Root cause. The shim's auth middleware used isStubPath to decide which requests skip the bearer-token gate. Before the fix, /project and /vcs were auth-gated for all methods, and /instance* was never registered in the mux at all. That produced two contract gaps:

• C19: GET /instance → 404 — the ServeMux had no handler, so the request fell through to "no route" (the pre-fix repro shows this exactly).
• C20: POST /project → 401 — auth rejected the request before the existing 501 method-router stub could run (repro shows 401 wall).

Fix (3 changes):

1. server.go — add the stub handler + registration helper:

// StubHandler implements the 501 contract for recognized-but-unimplemented routes.
// It must be reachable WITHOUT a bearer token, hence the auth bypass in isStubPath.
func StubHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusNotImplemented)
    _ = json.NewEncoder(w).Encode(StubResponse{Error: "not_implemented"})
}

// RegisterStubRoutes mounts /instance stubs. Both patterns are required:
// "/instance/" alone does NOT match "/instance" itself (ServeMux would 301),
// while "/instance" alone would not cover /instance/<id>.
func RegisterStubRoutes(mux *http.ServeMux) {
    mux.HandleFunc("/instance", StubHandler)
    mux.HandleFunc("/instance/", StubHandler)
}

2. server.go — fix isStubPath (the core routing change):

func isStubPath(r *http.Request) bool {
    p := r.URL.Path

    // C19: /instance and /instance/* are pure stubs for every method.
    if p == "/instance" || strings.HasPrefix(p, "/instance/") {
        return true
    }

    // C20: on /project and /vcs only GET is a real (auth-gated) route;
    // non-GET must bypass auth and fall through to the 501 stub.
    if p == "/project" || p == "/vcs" {
        return r.Method != http.MethodGet
    }

    return true // outside the auth-gated surface; keep pre-existing 404 behavior
}

3. main.go — mount the stubs in the handler chain:

func newHandler() http.Handler {
    mux := http.NewServeMux()
    RegisterStubRoutes(mux) // <-- mounts /instance + /instance/*
    mux.HandleFunc("/project", methodRouter(http.MethodGet, projectHandler))
    mux.HandleFunc("/vcs",     methodRouter(http.MethodGet, vcsHandler))
    return AuthMiddleware(mux)
}

The request flow after the fix: AuthMiddleware → isStubPath (skips auth for /instance* and non-GET /project|/vcs) → ServeMux → 501 StubHandler for stubs, real handler for authenticated GET /project|/vcs, 401 only for unauthenticated GET /project|/vcs.