RFC 174: New variadic syntax for route declaration and parameters

[EwenQuim]

RFC fuego-174 New variadic syntax for route declaration and parameters

Current problem

The chaining syntax have at least 4 serious limits.

func main() {
	s := fuego.NewServer()

	// Old syntax - chaining
	fuego.Get(s, "/test", myController, middleware1, middleware2).
		Description("coucou").
		QueryParam("my-param", "description"). // Chaining might look sexy but it's not DRY if you want to reuse headers
                Header("my-param", "description")
}

• ❌ 1️⃣ Not DRY: hard to reuse the same params from a route to another. feat: add group parameters #165 might help by declaring params at the group level but it won't solve the problem of reusing the same parameters through the whole app. It also makes refactoring more difficult.
• ❌ 2️⃣ No way of grouping parameters often used together, like limit/offset or page/per_page query params
• ❌ 3️⃣ It sets OpenAPI params AFTER route registration. I tried everything. Even using pointers won't solve the issue of transmitting data through the closure in HTTPHandler (serve.go) after it is registered (might just need a PR from someone wiser than me but it seems tricky honestly)
• ❌ 4️⃣ Not extensible. These methods (Header, Description...) have with Route[Body, Return] as receiver, so users cannot add their custom behaviour.

Proposition

Using the ...func(*Options) "variadic options" pattern might be an elegant solution to it.

• ✅ 1️⃣ DRY: you can defined parameters and reuse them later or in many parts of the app
• ✅ 2️⃣ grouping parameters is possible with a little help from the Fuego lib (option.Group, I have an implementation)
• ✅ 3️⃣ It sets OpenAPI params while registrating the route. It is nom possible to verify that c.QueryParam() does not contains a typo or wrong information
• ✅ 4️⃣ Extensible. User just have to create their own function and can access the Route object

func main() {
        s := fuego.NewServer()

	// New syntax - the classic `...func(*Option)` variadic options
       
	fuego.Get(s, "/test", myController,
		defaultOptions,
		option.Query("name", "description"),       // 3️⃣ Query & Header information can now be injected into the controllers via the context - now if you declare QueryParam("my-param") in the route declaration and use c.QueryParam("my-param-with-typo") in the controller, you get a warning
		option.Header("Accept", "coucou"),
		option.Middleware(middleware1),
		option.Description("coucou"),
		option.Middleware(mdlw, middleware2), // the middlewares will be applied in the order `middleware1`, `mdlw`, `middleware2`
                myReusableOption,
                // Allows future behaviour to be injected
	)

        myReusableOption := option.Query("name", "Name") // 1️⃣  Can be used in many routes

        defaultPagination := option.Group( // 2️⃣ Grouping
		option.Middleware(mdlw),
                option.Query("per_page", "Number of entities per page"),
		option.Query("page", "Page requested"),
	)

        myOwnOption := func(route *fuego.BaseRoute) { // 4️⃣ : my own Route customization
             r.XXX = YYY // Entirely free to modify the `BaseRoute` Object as I wish (BaseRoute is Route[X, Y] without type parameters)
        }
}

Other solution

Another solution would be using #119 and embedding. I would like to try something else. Sure, with this proposal, we will not enjoy some compile-time checks, but:

• This proposed solution is more flexible
• It makes Fuego easily usable for newcomers, which is something we want. Simplicity always win.
• RFC 119: Strongly typed params (header, query params typed in controller signature) #119 would introduce 2 new Context* structs
• Using struct tags have some serious limitations. Tags are not strings, and cannot be computed dynamically, which is an issue often mentioned in competitor frameworks. The proposed solution is very flexible.
• Nothing prevents you to write Authorization string 'header:"Autorisation"' and make typos anyway, thus catching nothing at runtime. The variadic options would enable parameters validation and/or warnings at runtime.
• RFC 119: Strongly typed params (header, query params typed in controller signature) #119 would introduce a lot of complexity to the framework

Limits

1. The fuego.Description is not very "discoverable". I don't like maintaining documentation and want the users to be able to discover Fuego behaviour from their IDE. For *Server options, we used fuego.WithXxx syntax. This allow users to know that every fuego.WithXxx is a Server option and enabled them to discover new options easily by typing fuego.With<Tab> or looking at all the functions starting by With in the docs. I would like to do the same thing here, but it hurts readability. What should we do? I think of 2 solutions
   1. Use Opt prefix (example : fuego.OptDescription("My controller does this")) - ugly
   2. Use another package like option (example: option.Description("My controller does this")) only used for description - how the user would figure that the option package exists ? We can maybe spam it in the docs?
2. This is of course a huge breaking change. We should it introduce carefully and maybe support the old and the new syntax for a few releases with a deprecation notice. But I think it is worth it long term.

[EwenQuim]

@redecs @rizerkrof @dylanhitt @qbit I really need the input of everyone here, if you have time

[redecs]

More flexibility is a plus for me and I like the option func pattern variadic parameters. In my experience with Go I've learned to stay way from struct tags - they seem great until it backfires and/or you're constrained, so the approach described here compared to #119 makes more sense to me.

I do have some questions: Would the options.Middleware() be the only outlier from the OpenAPI related ones? Would putting all the OpenAPI options under its own package make sense?

Here's how I would use something like this:

# [...]
import (
       "github.com/go-fuego/fuego"
       fuegoOpt "github.com/go-fuego/fuego/options"
       fuegoOA "github.com/go-fuego/fuego/options/openapi"
)
# [...]
fuego.Get(s, "/test", myController,
		defaultOptions,
		fuegoOA.Query("name", "description"),       
		fuegoOA.Header("Accept", "coucou"),
		fuegoOpt.Middleware(middleware1),
		fuegoOA.Description("coucou"),
	)
# [...]

In my mind separating the OpenAPI setup from the the generic options (middleware and maybe others) improves the clarity but it reduces "discoverability" since it adds another layer (package). What do you think?

[EwenQuim]

In mind separating the OpenAPI setup from the the generic options (middleware and maybe others)

OpenAPI options have a real impact on the code, it's not just declaration. For example:

fuego.Get(s, "/test", myController,
   option.Header("X-Header", "My header")
   option.QueryInt("age", "Age", param.Default(18), param.Example("Old guy", 75)) // ... will set the default query parameter to 18 in the controller.
)

It's hard to have a clear difference between openAPI and the actual running code.

[EwenQuim]

We'll have 2 new packages :

• option for route level options (func (*BaseRoute) pattern)
• param for parameter level options (func (*OpenAPIParam) pattern)

What do you think about the naming? @ccoVeille I forgot to tag you sorry

On a side note: while implementing it, I found that these new patterns are insanely powerful. We'll be able to have full OpenAPI3.1-compatible route parameters with proper validation, setting defaults, custom user-defined behaviours etc... I definitely confirm that Fuego v0.15 will adopt this RFC

[redecs]

The separation by route level or param level also makes sense to me, since it's more about what it can do (functionality) that what they are (concept). This also seems more idiomatic in Go. I like the naming too.

[ccoVeille]

I'm a huge advocate of Option design pattern, so I love it.

The name are fine to me

[dylanhitt]

I believe this can be closed?