Add HEAD method support for all GET endpoints (RFC 9110 compliance)

[ericfitz]

Overview

RFC 9110 Section 9.3.2 recommends that servers SHOULD support HEAD requests for all resources that support GET. Currently, the TMI API returns 405 Method Not Allowed for HEAD requests.

Background

HEAD requests are useful for:

• Bandwidth optimization (checking resource existence/metadata without transferring body)
• Health checks and monitoring
• Conditional requests (checking Last-Modified, ETag without downloading)
• Cache validation

Current Behavior

$ curl -I http://localhost:8080/.well-known/openid-configuration
HTTP/1.1 405 Method Not Allowed

Expected Behavior

$ curl -I http://localhost:8080/.well-known/openid-configuration
HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
Content-Type: application/json
# (no response body)

Implementation Challenges

After investigation, implementing HEAD support requires significant changes:

1. OpenAPI Specification: Add HEAD operations for all ~53 GET endpoints
2. Code Generation: oapi-codegen creates separate parameter types for HEAD methods (e.g., ListAddonsHeadParams vs ListAddonsParams)
3. Handler Implementation: Need to implement 53+ HEAD handler methods that delegate to GET handlers
4. Middleware Approach: Simple middleware-based conversion doesn't work because Gin's router matches routes before middleware runs

Proposed Approaches

Option 1: OpenAPI + Generated Handlers (Most Complete)

• Add HEAD to OpenAPI spec for all GET endpoints
• Generate API code with oapi-codegen
• Implement handler stubs that delegate to GET methods
• Pros: Fully documented in OpenAPI spec, proper type safety
• Cons: Requires modifying 53+ endpoints, maintaining parallel parameter types

Option 2: Dynamic Route Registration (Simpler)

• After OpenAPI routes are registered, programmatically register HEAD routes
• Use Gin's built-in HEAD support (automatically strips body from GET response)
• Pros: Minimal code changes, automatic for all GET routes
• Cons: Not reflected in OpenAPI spec, requires careful handler chain management

Option 3: Middleware-based (Cleanest but Complex)

• Create middleware that intercepts HEAD requests and converts to GET
• Strip response body before sending
• Pros: Single point of implementation
• Cons: Routing happens before middleware, requires custom routing logic

Reference Materials

• RFC 9110 Section 9.3.2: https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.2
• Related commit removing X-XSS-Protection: dc88012
• CATS security test report: cats-report/Test7.json

Priority

Low/Medium - This is a "SHOULD" (not "MUST") per RFC 9110. The current 405 response is correct and RFC-compliant. HEAD support is a nice-to-have for better HTTP semantics and client compatibility.

Related Issues

• Security headers validation (resolved in dc88012)
• CATS fuzzer testing compliance