Making top-level request/response data more composable

[rhodeon]

I've been using Huma for almost a year on production and it has largely been a pleasure.
While the initial draw for us was the OpenAPI generation, the type-safety of requests/responses ultimately turned out to be the biggest game-changer.

That said, there's a pain point I'm currently experiencing.

I make use of an envelope to wrap all response data for consistency and extensibility:

{  
  "data": {  
    "name": "John Doe"  
  }  
}

This makes it easy to extend the response with extra information like pagination details:

{
  "data": [
    {
      "name": "John Doe"
    },
    {
      "name": "Jane Doe"
    }
  ],
  "metadata": {
    "current_page": 1,
    "page_size": 2,
    "total_pages": 1,
    "total_records": 2
  }
}

To simply that, I make use of a generic wrapper to enforce the envelope.

// Envelope is a uniform wrapper around the actual response data.
type Envelope[T any] struct {
    Body ResponseBody[T]  
}

// ResponseBody is a shortcut to skip manually declaring the body for all responses.
type ResponseBody[T any] struct {  
    Data T `json:"data"`  
}

func Success[T any](data T) *Envelope[T] {  
    return &Envelope[T]{  
       Body: ResponseBody[T]{  
          Data: data,  
       },  
    }  
}

As mentioned in the docs, Huma automatically treats the Body field of requests/responses structs as the request/response body. So it needs to be explicitly part of the envelope.

This works perfectly fine for most endpoints:

func (h *Handlers) Create(_ context.Context, _ *struct{}) (*responses.Envelope[responses.User], error) {  
    return responses.Success(responses.User{}), nil  
}

But it falls apart when I need to provide custom response headers as they can't be dynamically added to the generic.
Like with the Body, it would be great to also have a special field for the headers, let's say Headers which is automatically handled. So the envelope can be extended to:

type Envelope[T any, U any] struct {
    Body ResponseBody[T]  
    Headers U
}

My current workaround is having a general Headers struct which holds all possible headers in the system and inlining it into the envelope:

type Envelope[T any] struct {
    Body ResponseBody[T]  
    Headers
}

type Headers struct {  
    MyHeader   string `header:"My-Header"`  
    YourHeader string `header:"Your-Header"`  
    OurHeader   string `header:"Our-Header"`  
    TheirHeader string `header:"Their-Header"`
    // And so on...
}

func Success[T any, headers Headers](data T) *Envelope[T] {  
    return &Envelope[T]{  
       Body: ResponseBody[T]{  
          Data: data,  
       },
       headers
    }  
}

func (h *Handlers) Create(_ context.Context, _ *struct{}) (*responses.Envelope[responses.User], error) {  
    return responses.Success(responses.User{}, responses.Headers{  
    MyHeader: "Mine",  
    YourHeader: "Yours",  
	}), nil  
}

This works but adds noise of unused headers in that endpoint's documentation, making it less accurate.

That brings me back to my original point. Treating Header as a special field for headers in the response would be great to aid reusability of wrappers.

In the same vein, this can also be extended to requests. Like with responses, Body fields in a request struct are automatically treated as the request body. The same can be done for Headers, Paths, Queries and Cookies.

One issue I see with this is the possibility of breaking existing code which have those fields already set for other purposes.
To limit that, they can be prepended with "Huma" i.e. Headers -> HumaHeaders. This doesn't make the chances of collision zero, but it should greatly reduce them.

Ultimately, a more foolproof alternative would be having a huma struct tag:

type GetUserOrdersRequest struct {  
    Body    struct{} `huma:"body"` // Same as the current behaviour.  
    Headers Headers  `huma:"headers"`  
    Queries Queries  `huma:"queries"`  
    Paths   Paths    `huma:"paths"`  
    Cookies Cookies  `huma:"cookies"`  
}  

type Headers struct {  
    MyHeader   string `header:"My-Header"`  
    YourHeader string `header:"Your-Header"`  
}
  
type Paths struct {  
    UserId int `path:"user_id"`  
}  
type Queries struct {  
    Sort string `query:"sort"`  
}  
  
type Cookies struct {  
    SessionId string `cookie:"session_id"`  
}  

This is my preferred approach as it has the advantage of being able to freely use any field names, and also gives a more intuitive (in my opinion, at least) model of the request/response.

[rhodeon]

@danielgtaylor, what do you think of this idea? I'd be happy to work on an implementation if it sounds good.