feat: add support for implicit and explicit head response validation

Author: saisatishkarra

helpers/operation_utilities.go

@@ -7,7 +7,7 @@ import (
 	"mime"
 	"net/http"
 
-	"github.com/pb33f/libopenapi/datamodel/high/v3"
+	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
 )
 
 // ExtractOperation extracts the operation from the path item based on the request method. If there is no
@@ -25,7 +25,10 @@ func ExtractOperation(request *http.Request, item *v3.PathItem) *v3.Operation {
 	case http.MethodOptions:
 		return item.Options
 	case http.MethodHead:
-		return item.Head
+		if item.Head != nil {
+			return item.Head
+		}
+		return item.Get
 	case http.MethodPatch:
 		return item.Patch
 	case http.MethodTrace:

helpers/operation_utilities_test.go

@@ -8,7 +8,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/pb33f/libopenapi/datamodel/high/v3"
+	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
 	"github.com/stretchr/testify/require"
 )
 
@@ -112,3 +112,25 @@ func TestExtractContentType(t *testing.T) {
 	require.Empty(t, charset)
 	require.Empty(t, boundary)
 }
+func TestExtractOperationHeadFallback(t *testing.T) {
+	pathItem := &v3.PathItem{
+		Get:  &v3.Operation{Summary: "GET operation"},
+		Head: nil,
+	}
+
+	req, _ := http.NewRequest(http.MethodHead, "/", nil)
+	operation := ExtractOperation(req, pathItem)
+	require.NotNil(t, operation)
+	require.Equal(t, "GET operation", operation.Summary)
+}
+
+func TestExtractOperationHeadFallbackNoGet(t *testing.T) {
+	pathItem := &v3.PathItem{
+		Head: nil,
+		Get:  nil,
+	}
+
+	req, _ := http.NewRequest(http.MethodHead, "/", nil)
+	operation := ExtractOperation(req, pathItem)
+	require.Nil(t, operation)
+}

paths/specificity.go

@@ -65,7 +65,11 @@ func pathHasMethod(pathItem *v3.PathItem, method string) bool {
 	case http.MethodOptions:
 		return pathItem.Options != nil
 	case http.MethodHead:
-		return pathItem.Head != nil
+		// Treat HEAD as present when either
+		// a Head operation exists or, if Head is absent, when a Get exists
+		// per HTTP semantics (HEAD can be handled by GET if no explicit
+		// HEAD operation is defined).
+		return pathItem.Head != nil || pathItem.Get != nil
 	case http.MethodPatch:
 		return pathItem.Patch != nil
 	case http.MethodTrace:

paths/specificity_test.go

@@ -172,6 +172,12 @@ func TestPathHasMethod(t *testing.T) {
 			method:   "HEAD",
 			expected: true,
 		},
+		{
+			name:     "HEAD if GET exists",
+			pathItem: &v3.PathItem{Get: &v3.Operation{}},
+			method:   "HEAD",
+			expected: true,
+		},
 		{
 			name:     "PATCH exists",
 			pathItem: &v3.PathItem{Patch: &v3.Operation{}},

responses/validate_body.go

@@ -138,7 +138,6 @@ func (v *responseBodyValidator) checkResponseSchema(
 		// extract schema from media type
 		if mediaType.Schema != nil {
 			schema := mediaType.Schema.Schema()
-
 			// Validate response schema
 			valid, vErrs := ValidateResponseSchema(&ValidateResponseSchemaInput{
 				Request:  request,

responses/validate_response.go

@@ -158,6 +158,12 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors
 	schema := input.Schema
 
 	if response == nil || response.Body == http.NoBody {
+
+		// skip response body validation for head request after processing schema
+		if request != nil && request.Method == http.MethodHead {
+			return true, validationErrors
+		}
+
 		// cannot decode the response body, so it's not valid
 		violation := &errors.SchemaValidationFailure{
 			Reason:          "response is empty",
@@ -210,6 +216,28 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors
 	var decodedObj interface{}
 
 	if len(responseBody) > 0 {
+		// Per RFC7231, a response to a HEAD request MUST NOT include a message body.
+		if request != nil && request.Method == http.MethodHead {
+			violation := &errors.SchemaValidationFailure{
+				Reason:          "HEAD responses must not include a message body",
+				Location:        "response body",
+				ReferenceObject: string(responseBody),
+				ReferenceSchema: referenceSchema,
+			}
+			validationErrors = append(validationErrors, &errors.ValidationError{
+				ValidationType:    helpers.ResponseBodyValidation,
+				ValidationSubType: helpers.Schema,
+				Message: fmt.Sprintf("%s response for '%s' must not include a body",
+					request.Method, request.URL.Path),
+				Reason:                 "The response to a HEAD request must not contain a body",
+				SpecLine:               1,
+				SpecCol:                0,
+				SchemaValidationErrors: []*errors.SchemaValidationFailure{violation},
+				HowToFix:               "ensure no response body is present for HEAD requests",
+				Context:                referenceSchema,
+			})
+			return false, validationErrors
+		}
 		err := json.Unmarshal(responseBody, &decodedObj)
 		if err != nil {
 			// cannot decode the response body, so it's not valid

responses/validate_response_test.go

@@ -291,3 +291,55 @@ components:
 	assert.Contains(t, errors[0].Message, "failed schema rendering")
 	assert.Contains(t, errors[0].Reason, "circular reference")
 }
+func TestValidateResponseSchema_ResponseMissing(t *testing.T) {
+	schema := parseSchemaFromSpec(t, `type: object
+properties:
+  name:
+	type: string`, 3.1)
+
+	// Response body missing (NoBody) for a non-HEAD request should error
+	valid, errs := ValidateResponseSchema(&ValidateResponseSchemaInput{
+		Request:  postRequest(),
+		Response: &http.Response{StatusCode: http.StatusOK, Body: http.NoBody},
+		Schema:   schema,
+		Version:  3.1,
+	})
+
+	assert.False(t, valid)
+	require.Len(t, errs, 1)
+	assert.Contains(t, errs[0].Message, "response object is missing")
+}
+
+func TestValidateResponseSchema_HeadEmptySkipsValidation(t *testing.T) {
+	schema := parseSchemaFromSpec(t, `type: object`, 3.1)
+
+	req, _ := http.NewRequest(http.MethodHead, "/test", nil)
+	resp := &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}
+
+	valid, errs := ValidateResponseSchema(&ValidateResponseSchemaInput{
+		Request:  req,
+		Response: resp,
+		Schema:   schema,
+		Version:  3.1,
+	})
+
+	assert.True(t, valid)
+	assert.Len(t, errs, 0)
+}
+
+func TestValidateResponseSchema_HeadWithBodyFails(t *testing.T) {
+	schema := parseSchemaFromSpec(t, `type: object`, 3.1)
+
+	req, _ := http.NewRequest(http.MethodHead, "/test", nil)
+
+	valid, errs := ValidateResponseSchema(&ValidateResponseSchemaInput{
+		Request:  req,
+		Response: responseWithBody(`{"name":"bob"}`),
+		Schema:   schema,
+		Version:  3.1,
+	})
+
+	assert.False(t, valid)
+	require.Len(t, errs, 1)
+	assert.Contains(t, errs[0].Reason, "must not contain a body")
+}