feat: improve error reporting and add structured error codes

Extend error responses with additional JSON fields and HTTP headers to
provide richer diagnostic information. Introduce new error codes
(token_expired, quota_exhausted) to support programmatic handling and
automatic token refresh. Add a helper for extracting the extended
metadata into the Error struct. Includes general refactoring to improve
code consistency across the codebase.

Author: alansy-nscale

pkg/messaging/consumer/cascadingdelete.go

@@ -98,7 +98,7 @@ func (c *CascadingDelete) Consume(ctx context.Context, envelope *messaging.Envel
 	}
 
 	if c.resourceLabel != "" {
-		opts.LabelSelector = labels.SelectorFromSet(map[string]string{
+		opts.LabelSelector = labels.SelectorFromSet(labels.Set{
 			c.resourceLabel: envelope.ResourceID,
 		})
 	}

pkg/openapi/common.spec.yaml

@@ -17,35 +17,45 @@ components:
           type: string
   schemas:
     error:
-      description: Generic error message, compatible with oauth2.
+      description: Represents a structured error response returned by the API. It consolidates both OAuth 2.0-related and general API errors into a unified format.
       type: object
       required:
+      - type
+      - status
       - error
-      - error_description
       properties:
+        type:
+          description: Specifies whether the error originated from an OAuth 2.0 context or from the general API.
+          type: string
+          enum:
+          - oauth2_error
+          - api_error
+        status:
+          description: The HTTP status code returned with the response.
+          type: integer
         error:
-          description: A terse error string expanding on the HTTP error code. Errors are based on the OAuth 2.02 specification, but are expanded with proprietary status codes for APIs other than those specified by OAuth 2.02.
+          description: A concise, machine-readable identifier for the specific error, enabling clients to handle particular conditions programmatically.
           type: string
           enum:
-          # Defined by OAuth 2.02
+          # Common error codes
           - invalid_request
-          - unauthorized_client
+          # OAuth 2.0 error codes
+          - unsupported_grant_type
+          - invalid_grant
+          - invalid_token
+          - invalid_client
           - access_denied
-          - unsupported_response_type
-          - invalid_scope
+          - insufficient_scope
           - server_error
-          - temporarily_unavailable
-          - invalid_client
-          - invalid_grant
-          - unsupported_grant_type
-          # Proprietary
-          - not_found
+          # API error codes
+          - token_expired
+          - unauthorized
+          - resource_missing
           - conflict
-          - method_not_allowed
-          - unsupported_media_type
-          - forbidden
+          - quota_exhausted
+          - internal
         error_description:
-          description: Verbose message describing the error.
+          description: A human-readable explanation that provides additional context about the error. This field is omitted when no extra description is available.
           type: string
     kubernetesLabelValue:
       description: |-

pkg/openapi/helpers.go

@@ -18,13 +18,15 @@ limitations under the License.
 package openapi
 
 import (
+	"encoding/json"
+	"fmt"
 	"net/http"
 
 	"github.com/getkin/kin-openapi/openapi3"
 	"github.com/getkin/kin-openapi/routers"
 	"github.com/getkin/kin-openapi/routers/gorillamux"
 
-	"github.com/unikorn-cloud/core/pkg/server/errors"
+	errorsv2 "github.com/unikorn-cloud/core/pkg/server/v2/errors"
 )
 
 // Schema abstracts schema access and validation.
@@ -65,8 +67,55 @@ func NewSchema(get SchemaGetter) (*Schema, error) {
 func (s *Schema) FindRoute(r *http.Request) (*routers.Route, map[string]string, error) {
 	route, params, err := s.router.FindRoute(r)
 	if err != nil {
-		return nil, nil, errors.OAuth2ServerError("unable to find route").WithError(err)
+		err = fmt.Errorf("failed to find route: %w", err)
+		return nil, nil, err
 	}
 
 	return route, params, nil
 }
+
+func parseJSONErrorResponse(headers http.Header, data []byte) error {
+	var response errorsv2.Error
+	if err := json.Unmarshal(data, &response); err != nil {
+		return errorsv2.NewInternalError().WithCause(err).Prefixed()
+	}
+
+	return response.WithSimpleCause("upstream error").
+		WithWWWAuthenticate(headers).
+		WithOAuth2ErrorCode(headers).
+		WithAPIErrorCode(headers)
+}
+
+//nolint:nlreturn,wsl
+func ParseJSONValueResponse[T any](headers http.Header, data []byte, status, expected int) (T, error) {
+	if status != expected {
+		var zero T
+		err := parseJSONErrorResponse(headers, data)
+		return zero, err
+	}
+
+	var response T
+	if err := json.Unmarshal(data, &response); err != nil {
+		err = errorsv2.NewInternalError().WithCause(err).Prefixed()
+		return response, err
+	}
+
+	return response, nil
+}
+
+//nolint:nlreturn,wsl
+func ParseJSONPointerResponse[T any](headers http.Header, data []byte, status, expected int) (*T, error) {
+	if status != expected {
+		var zero T
+		err := parseJSONErrorResponse(headers, data)
+		return &zero, err
+	}
+
+	var response T
+	if err := json.Unmarshal(data, &response); err != nil {
+		err = errorsv2.NewInternalError().WithCause(err).Prefixed()
+		return nil, err
+	}
+
+	return &response, nil
+}

pkg/server/conversion/conversion.go

@@ -28,6 +28,7 @@ import (
 	unikornv1 "github.com/unikorn-cloud/core/pkg/apis/unikorn/v1alpha1"
 	"github.com/unikorn-cloud/core/pkg/constants"
 	"github.com/unikorn-cloud/core/pkg/openapi"
+	errorsv2 "github.com/unikorn-cloud/core/pkg/server/v2/errors"
 	"github.com/unikorn-cloud/core/pkg/util"
 
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
@@ -165,7 +166,7 @@ func OrganizationScopedResourceReadMetadata(in metav1.Object, tags unikornv1.Tag
 	return out
 }
 
-// ProjectScopedResourceReadMetadata extracts project scoped metdata from a resource for
+// ProjectScopedResourceReadMetadata extracts project scoped metadata from a resource for
 // GET APIs.
 //
 //nolint:errchkjson
@@ -238,6 +239,16 @@ type MetadataMutationFunc func(required, current metav1.Object) error
 
 // UpdateObjectMetadata abstracts away metadata updates.
 func UpdateObjectMetadata(required, current metav1.Object, mutators ...MetadataMutationFunc) error {
+	if err := updateObjectMetadata(required, current, mutators); err != nil {
+		return errorsv2.NewInternalError().
+			WithCausef("failed to update object metadata: %w", err).
+			Prefixed()
+	}
+
+	return nil
+}
+
+func updateObjectMetadata(required, current metav1.Object, mutators []MetadataMutationFunc) error {
 	req := required.GetAnnotations()
 	if req == nil {
 		req = map[string]string{}
@@ -293,12 +304,10 @@ func LogUpdate(ctx context.Context, current, required metav1.Object) error {
 }
 
 func ConvertTag(in unikornv1.Tag) openapi.Tag {
-	out := openapi.Tag{
+	return openapi.Tag{
 		Name:  in.Name,
 		Value: in.Value,
 	}
-
-	return out
 }
 
 func ConvertTags(in unikornv1.TagList) openapi.TagList {
@@ -316,12 +325,10 @@ func ConvertTags(in unikornv1.TagList) openapi.TagList {
 }
 
 func GenerateTag(in openapi.Tag) unikornv1.Tag {
-	out := unikornv1.Tag{
+	return unikornv1.Tag{
 		Name:  in.Name,
 		Value: in.Value,
 	}
-
-	return out
 }
 
 func GenerateTagList(in *openapi.TagList) unikornv1.TagList {

pkg/server/handler/error.go

@@ -0,0 +1,38 @@
+/*
+Copyright 2025 the Unikorn Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package handler
+
+import (
+	"net/http"
+
+	"github.com/unikorn-cloud/core/pkg/server/errors"
+)
+
+// NotFound is called from the router when a path is not found.
+func NotFound(w http.ResponseWriter, r *http.Request) {
+	errors.HTTPNotFound().Write(w, r)
+}
+
+// MethodNotAllowed is called from the router when a method is not found for a path.
+func MethodNotAllowed(w http.ResponseWriter, r *http.Request) {
+	errors.HTTPMethodNotAllowed().Write(w, r)
+}
+
+// HandleError is called when the router has trouble parsing paths.
+func HandleError(w http.ResponseWriter, r *http.Request, err error) {
+	errors.OAuth2InvalidRequest("invalid path/query element").WithError(err).Write(w, r)
+}

pkg/server/middleware/cors/cors.go

@@ -25,7 +25,8 @@ import (
 	"github.com/spf13/pflag"
 
 	"github.com/unikorn-cloud/core/pkg/openapi"
-	"github.com/unikorn-cloud/core/pkg/server/errors"
+	errorsv2 "github.com/unikorn-cloud/core/pkg/server/v2/errors"
+	"github.com/unikorn-cloud/core/pkg/server/v2/httputil"
 	"github.com/unikorn-cloud/core/pkg/util"
 )
 
@@ -65,7 +66,13 @@ func Middleware(schema *openapi.Schema, options *Options) func(http.Handler) htt
 			// Handle preflight
 			method := r.Header.Get("Access-Control-Request-Method")
 			if method == "" {
-				errors.HandleError(w, r, errors.OAuth2InvalidRequest("OPTIONS missing Access-Control-Request-Method header"))
+				err := errorsv2.NewInvalidRequestError().
+					WithSimpleCause("missing Access-Control-Request-Method header").
+					WithErrorDescription("Missing Access-Control-Request-Method header in OPTIONS request.").
+					Prefixed()
+
+				httputil.WriteErrorResponse(w, r, err)
+
 				return
 			}
 
@@ -74,7 +81,7 @@ func Middleware(schema *openapi.Schema, options *Options) func(http.Handler) htt
 
 			route, _, err := schema.FindRoute(request)
 			if err != nil {
-				errors.HandleError(w, r, err)
+				httputil.WriteErrorResponse(w, r, err)
 				return
 			}