📝 [v3 Proposal]: Koa Style ctx.Request and ctx.Response Objects

[nickajacks1]

Feature Proposal Description

Currently, the Ctx object handles almost all of the work that is performed in a Handler function. This can potentially lead to confusion about what parts of the API interact with the request and what parts interact with the response (eg Cookie vs Cookies).

Previously, we decided against eliminating the Ctx object entirely (#2764), but at the tail end of the discussion in Discord, it was brought up that we could avoid almost all breaking changes by following what Koa does: put the core implementation in Request and Response objects and have a generic Ctx API which provides convenient aliases for the request+response APIs.

In other words, the existing Ctx object stays exactly as-is, but ctx.Response() and ctx.Request() are reworked to hold more of the core functionality. As alluded to above, this allows users to more easily reason about what parts of the API touch the request vs response.

I am creating this proposal to attempt to take that idea and arrive at a concrete conclusion for whether we would like to implement this or not for v3 and beyond.

More reading: https://koajs.com/

Alignment with Express API

While inspired by Koa, the approach of splitting Ctx into distinct Request and Response objects brings Fiber closer to Express's res and req centered APIs.

HTTP RFC Standards Compliance

The proposal is not relevant to HTTP RFCs.

API Stability

This would be a breaking change, as it would change Ctx.Request() and Ctx.Response() to no longer directly return the underlying fasthttp Request and Response objects. Consequently, it will need to be implemented during a major version bump.
The only way around this would be to make the new Request and Response objects compose the fasthttp objects, but that might prove to be a clumsy solution.

Having a clear separation between Request and Response APIs allows for a more idiomatic design. With the current Ctx-only design, we already have examples of collisions between request-based and response-based actions. For example, Ctx.Get and Ctx.GetResponseHeader.

Feature Examples

package main

import (
	"github.com/gofiber/fiber/v3"
)

func main() {
	app := fiber.New()

	// This syntax is still valid under the proposed changes
	app.Get("/old-stuff", func(c fiber.Ctx) error {
		if c.Accepts("text/plain") == "" {
			return c.SendStatus(fiber.StatusNotAcceptable)
		}

		name := c.Cookies("name")

		cookie := new(fiber.Cookie)
		cookie.Name = "userId"
		cookie.Value = "1234"
		c.Cookie(cookie)

		// ...

		return c.SendString("Hello " + name)
	})

	// Ergonomic mix of Ctx and direct req/res usage
	app.Get("/new-stuff", func(c fiber.Ctx) error {
		if c.Accepts("text/plain") == "" {
			return c.SendStatus(fiber.StatusNotAcceptable)
		}

		name := c.Req().Cookies("name")

		cookie := new(fiber.Cookie)
		cookie.Name = "userId"
		cookie.Value = "1234"
		c.Res().Cookie(cookie)

		// ...

		return c.SendString("Hello " + name)
	})

	// Directly using req/res for everything
	app.Get("/new-stuff2", func(c fiber.Ctx) error {
		if c.Req().Accepts("text/plain") == "" {
			return c.Res().SendStatus(fiber.StatusNotAcceptable)
		}

		name := c.Req().Cookies("name")

		cookie := new(fiber.Cookie)
		cookie.Name = "userId"
		cookie.Value = "1234"
		c.Res().Cookie(cookie)

		// ...

		return c.Res().SendString("Hello " + name)
	})
}

Checklist:

• I agree to follow Fiber's Code of Conduct.
• I have searched for existing issues that describe my proposal before opening this one.
• I understand that a proposal that does not meet these guidelines may be closed without explanation.

[nickajacks1]

Sorry to bring this up again, but I figured I'd try to close the loop on this because the previous discussion kind of fizzled out when the Koa idea was brought up.
No worries if we want to keep the API as-is, it will be good to be able to point back to this proposal in the future either way.

Gist with sample implementation
https://gist.github.com/nickajacks1/2fd8bc71ba3a5a9839ebaf4313082efe

[gaby]

Ping @gofiber/maintainers

[ReneWerner87]

i like your proposal and gist, we can do it that way for all i care

this way the old api's still work and it's better separated

[ReneWerner87]

@efectn @gaby @sixcolors any ideas for this? otherwise someone can start with this or ?

[efectn]

I am OK with the change. Btw we should return Req() and Resp() as interface.

[ReneWerner87]

https://github.com/rjeczalik/interfaces#cmdinterfacer-

maybe via go:generate

[ReneWerner87]

@efectn we could also use this for the ctx interface

[efectn]

@efectn we could also use this for the ctx interface

Sounds good idea

[Fenny]

Sounds good, to keep it short and neady I vote for .Req / .Res interface. It's still good to allow users to access the underlying fasthttp pointers. Maybe ctx.Fasthttp() is an option, but should all methods be exposed in this one? If so, some functions might break internals, can place it "use at own risk" kinds thing 😆 or we limit it to fasthttp's request / response pointers only.

Feel free to comment

[sixcolors]

I also vote for .Req / .Res interface. Your example looks good.

I like ctx.Fasthttp().Res() more than ctx.Res().Fasthttp() but it doesn't really matter. I could easily be convinced it should be the other way.

[nickajacks1]

Thanks for the feedback. I'll get started.
I think that fasthttp gives you enough ways to shoot yourself in the foot that accessing it should be a "use at your own risk" type of thing, but leaving it available for use is probably a good idea just in case someone really needs it due to gaps in the fiber public API.

Should the existing ctx.Request() and ctx.Response() be left alone, marked deprecated, or removed? Today, they return the fasthttp objects, but they're also available using c.Context().Request. It would be confusing to have more than one method that returns a "request" or "response" object, but removing it entirely would be one more breaking change. Maybe that's fine since it's a new major version and it can be fixed with a find+replace.

[sixcolors]

I lean toward removing redundant or similarly named functions that would make the framework confusing. Accessing the underlying fasthttp pointer should be very explicit so I favor the ctx.Fasthttp() approach.

This would be breaking and I think v3 is a good opportunity to clean up and improve our approach. But, i think we really need to start a v2 => v3 migration guide. I recently did a migration of play billing lib for an Android app and think Google did a good job of their guide https://developer.android.com/google/play/billing/migrate-gpblv6

What does everyone else think?