RFC fuego-119: Strongly typed params (header, query params typed in controller signature)

[EwenQuim]

RFC fuego-119 ➡️ Refused in favor of #174

Goal

Expose parameters (Cookie, Query Param, Header) to the controller signature so they can be registered on OpenAPI document.

Current situation

The user must declare route.QueryParam("name") on the route and c.QueryParam("name") in the controller.

The "magic string" declaration is an issue because nothing prevents the user to declare route.QueryParam("name") on one side and try to use c.QueryParam("username") (username instead of name) on the other.
This is no better than comment declaration (except for the typing part for QueryParamInt and so), so we should be typing more strongly the parameters

Proposal

Strongly typed params

type ParamsIn struct {
  Authorization string `header:"Authorization"`
  Token string `cookie:"Token"`
  Limit *int `query:"limit"` // optional
  BookID string `query:"bookID"` // required
}

type ParamOut struct {
  CustomHeader string `header:"MyHeader"`
  Token string `cookie:"Token,httpOnly,secure"`
}

func (c *fuego.Context[Body, ParamsIn, ParamsOut]) (string, error) {
  fmt.Println(c.Params().Limit)

  // not sure about this syntax
  c.SetParam().CustomHeader
}

Other proposition for Cookies:

Mandatory *http.Cookie typing, so the user can specify dynamically the httpOnly, path and other cookie attributes while still declaring the param on the OpenAPI response.

type ParamsIn struct {
  Token *http.Cookie `cookie:"Token"` 
}

type ParamOut struct {
  Token *http.Cookie `cookie:"Token"`
}

The Context* types would be like this:

• fuego.Context[BodyType, ParamsType] 🆕 body+params, useful for PUT and other cases
• fuego.ContextWithParams[ParamsType] 🆕 no body, just params (headers+query), very useful for GET requests
• fuego.ContextWithBody[BodyType] just body, useful for many POST requests
• fuego.ContextNoBody without params and body

[dylanhitt]

Not sure I understand the point of ParamsOut? Is it a mechanism to build the openapi response?

Could be a bit more strict and [Body, Params (short for QueryParams), Headers] but that could get annoying.

What could be interesting maybe is with marshal attributes we could c.Cookies, c.Params, and c.Headers.

[EwenQuim]

This is for outgoing Headers and Cookies (written on the Response) !

I've added more information to the proposal. I'll continue to build it over time.
I think the [Body, Params, Headers, Cookies] syntax might be annoying when the user only have QueryParams. It would look like this fuego.Context[any, MyParams, any, any]. (after writing this it might not be as annoying as I imagined though).

But the user would have to specify if this is a Request Header or Response Header.

We might want to not type the outgoing Headers (this is currently the case).

[dylanhitt]

Understood. So yeah. I think we should at the minimum separate out each ParamsIn/Out type into it's own struct that is parsed and placed into context. Using c.Params for all feels weird and will probably lead to confusion.

Yeah I agree the syntax of [Body, Params, Headers, Cookies] is not the greatest. We could enforce a stricter struct for the input, but I believe that would require a fair amount of rewrite.

[dylanhitt]

So at the least ctx would be expanded with

// ctx is the context of the request.
// It contains the request body, the path parameters, the query parameters, and the http request.
// Please do not use a pointer type as parameter.
type ctx[B any] interface {
	// Body returns the body of the request.
	// If (*B) implements [InTransformer], it will be transformed after deserialization.
	// It caches the result, so it can be called multiple times.
	Body() (B, error)
	
	Cookies()
	
	Headers()

[EwenQuim]

I'm not so sure now about this way of doing things now. This can be nice but adds complexity to the framework and 2 ways of doing the same thing.

Current

func (rs ingredientRessource) MountRoutes(s *fuego.Server) {
	ingredientsGroup := fuego.Group(s, "/ingredients").
		Header("Content-Type", "The content type of the request"). // Group headers
		Cookie("session", "The session cookie")                                   // Group cookies

	fuego.Get(ingredientsGroup, "/ingredients", rs.getAllIngredients).
		QueryParam("name", "Filter by type").
		QueryParam("name", "Filter by name", fuego.OpenAPIParam{Example: "carrot", Type: "query"})

	fuego.Post(ingredientsGroup, "/ingredients/new", rs.newIngredient)
}

func (rs ingredientRessource) getAllIngredients(c fuego.ContextNoBody) ([]store.Ingredient, error) {
	category := c.QueryParam("category") // Access via magic string. Not catch at compile-time, but we can add a warn log in the framework when receiving request if the param is not declared in the OpenAPI config. I like this idea.
	name := c.QueryParam("name")

	ingredients, err := rs.IngredientRepository.GetIngredients(c.Context(), category, name)
	if err != nil {
		return nil, err
	}

	return ingredients, nil
}

RFC (doubt that this is good)

If I have two route (two controllers) and we want to have a Header param in both, we should do this (see below) because typing cannot be sent through groups.

type getAllIngredientsParams struct {
  Session string `cookie:"session"` // it is a bit of magic string here too, nothing prevents you to write "sesssion" (with 3 n) or any typo in the tag 
}
func (rs ingredientRessource) getAllIngredients(c fuego.ContextWithParams[getAllIngredientsParams]) ([]store.Ingredient, error) {
}

type filterIngredientsParams struct { // not very DRY, it looks like the other struct... Maybe support embedding ? This would mean that we carry a struct in every file...
  Session string `cookie:"session"` 
  Name string `query:"name"` 
}
func (rs ingredientRessource) filterIngredients(c fuego.ContextWithParams[filterIngredientsParams]) ([]store.Ingredient, error) {
  c.Params().Name // This is typed inside the controller
}

We can also support both syntax, but that might cause issues in the future.

[EwenQuim]

We would be using fuego.Context[BodyType, ParamsType]. With go 1.24, the other types will just be aliases to this one. For example, fuego.ContextWithBody[BodyType] = fuego.Context[BodyType, any]

[EwenQuim]

It is mandatory to keep fuego.ContextNoBody and fuego.ContextWithParams for backward compatibility anyway. People would just stop using Fuego if we introduce such a big breaking change.

[EwenQuim]

Recap:

• fuego.Context[BodyType, ParamsType] body+params, useful for PUT and other cases
• fuego.ContextWithParams[ParamsType] no body, just params (headers+query), very useful for GET requests
• fuego.ContextWithBody[BodyType] just body, useful for many POST requests
• fuego.ContextNoBody without params and body

[dylanhitt]

I think maybe one of your messages has a typo? ContextWithParams doesn’t exist yet?

[dylanhitt]

Would the goal be to eventually consolidate all the contexts and deprecate them slowly? Having a lot of input options is also very confusing for the caller.

[dylanhitt]

Any thoughts to something along the lines like (this does just concern itself with input params.

type ContextWithBody[Params, Body any] struct {
	body *Body // Cache the body in request context, because it is not possible to read an http request body multiple times.
	ContextNoBody[Params]
}

type ContextNoBody[Params any] struct {
	Req *http.Request
	Res http.ResponseWriter

	params *Params

	fs        fs.FS
	templates *template.Template

	readOptions readOptions
}

controller signatures would look something like

func (rs ingredientRessource) filterIngredients(c fuego.ContextNoBody[Params]) ([]store.Ingredient, error) {
  ps, err := c.Params
  if err != nil {
  ...
  }
  limit := ps.Limit
}

We could provide base Params struct in the fuego package as well as letting callers compose their own.

All that being said I haven't looked into this very much and their could be a massive technical limitation that i'm overlooking.

[dylanhitt]

I believe this can be closed?