go-api-spec-gap-wiring

Answer

The gap: spec 01-core §6.2 promised GET /api/v1/pools/:appID/status served by sandbox.StatusHandler, but no handler and no route existed. The domain primitive already existed and is reused unchanged: SandboxManager.PoolStatus(appID) (PoolStatus, error) plus the PoolStatus JSON type (with ErrPoolNotFound sentinel). The fix is pure wiring, zero reimplementation.

1. New sandbox/status_handler.go — status mapping 200/404 POOL_NOT_FOUND/400/500, router-style {"error":{"code","message"}} envelope:

var appIDRe = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`)

// StatusHandler serves GET /api/v1/pools/{appID}/status (spec 01-core §6.2).
// 200 OK (PoolStatus JSON) | 400 BAD_REQUEST | 404 POOL_NOT_FOUND | 500 INTERNAL_ERROR
func StatusHandler(mgr SandboxManager) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        appID := r.PathValue("appID")
        if appID == "" || !appIDRe.MatchString(appID) {
            writeError(w, http.StatusBadRequest, "BAD_REQUEST",
                "path parameter appID must be a non-empty alphanumeric identifier")
            return
        }
        status, err := mgr.PoolStatus(appID) // existing primitive, untouched
        if err != nil {
            switch {
            case errors.Is(err, ErrPoolNotFound):
                writeError(w, http.StatusNotFound, "POOL_NOT_FOUND",
                    fmt.Sprintf("no pool exists for appID %q", appID))
            default:
                writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR",
                    "failed to read pool status") // backend detail never leaked
            }
            return
        }
        writeJSON(w, http.StatusOK, status)
    })
}

// Router-style error envelope shared with the rest of the API.
type errorEnvelope struct{ Error errorBody `json:"error"` }
type errorBody struct {
    Code    string `json:"code"`
    Message string `json:"message"`
}

func writeError(w http.ResponseWriter, code int, errCode, message string) {
    writeJSON(w, code, errorEnvelope{Error: errorBody{Code: errCode, Message: message}})
}

func writeJSON(w http.ResponseWriter, code int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(code)
    _ = json.NewEncoder(w).Encode(v)
}

2. The one wiring line in framework.go (Go 1.22+ method-pattern ServeMux; {appID} populates r.PathValue):

mux := http.NewServeMux()

// U-GAP-005 fix: spec 01-core §6.2 promised this route; it was never wired.
mux.Handle("GET /api/v1/pools/{appID}/status", sandbox.StatusHandler(mgr))

// Existing route: /execute runs GetOrCreatePool before Acquire.
mux.Handle("POST /api/v1/execute", sandbox.ExecuteHandler(mgr))

The /execute handler already guarantees GetOrCreatePool runs before Acquire — which is exactly what makes the live E2E (below) work: the pool a request creates via /execute is immediately visible to the status route.

3. httptest fake-manager tests (sandbox/status_handler_test.go) — a fakeManager implements SandboxManager with injectable statusErr/createErr/acquireErr so the handler is tested against a controllable boundary, plus one live E2E test against the real in-memory manager through the exact framework.go wiring.