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

nickajacks1 · 2024-02-12T02:39:52Z

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.

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.

The text was updated successfully, but these errors were encountered:

nickajacks1 · 2024-02-12T02:43:47Z

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 · 2024-02-12T04:00:43Z

Ping @gofiber/maintainers

ReneWerner87 · 2024-02-12T08:12:25Z

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 · 2024-02-16T07:58:16Z

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

efectn · 2024-02-16T08:54:57Z

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

ReneWerner87 · 2024-02-16T08:57:39Z

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

maybe via go:generate

ReneWerner87 · 2024-02-16T09:00:40Z

@efectn we could also use this for the ctx interface

efectn · 2024-02-16T10:15:06Z

@efectn we could also use this for the ctx interface

Sounds good idea

Fenny · 2024-02-20T22:57:11Z

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 · 2024-02-20T23:27:34Z

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 · 2024-02-21T01:35:45Z

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 · 2024-02-21T02:38:52Z

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?

nickajacks1 added v3 📝 Proposal labels Feb 12, 2024

sixcolors mentioned this issue Feb 21, 2024

✨ (v3) feature: Implement new generic functions: Params, Get and Convert #2850

Merged

3 tasks

coderabbitai bot mentioned this issue Feb 28, 2024

🧹 v3 (Maintenance): Update docs to reflect fiber.Ctx struct to interface change #2880

Merged

16 tasks

nickajacks1 linked a pull request Mar 3, 2024 that will close this issue

🔥 Feature: Add Req and Res API #2894

Open

30 tasks

ReneWerner87 added this to v3 Apr 17, 2024

ReneWerner87 added this to the v3 milestone Apr 17, 2024

ReneWerner87 linked a pull request Apr 17, 2024 that will close this issue

🔥 Feature: Add Req and Res API #2894

Open

30 tasks

efectn moved this to In Progress in v3 Apr 28, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

nickajacks1 commented Feb 12, 2024

nickajacks1 commented Feb 12, 2024 •

edited

Loading

gaby commented Feb 12, 2024

ReneWerner87 commented Feb 12, 2024

ReneWerner87 commented Feb 16, 2024

efectn commented Feb 16, 2024

ReneWerner87 commented Feb 16, 2024

ReneWerner87 commented Feb 16, 2024

efectn commented Feb 16, 2024 •

edited

Loading

Fenny commented Feb 20, 2024 •

edited

Loading

sixcolors commented Feb 20, 2024 •

edited

Loading

nickajacks1 commented Feb 21, 2024

sixcolors commented Feb 21, 2024 •

edited

Loading

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

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

Comments

nickajacks1 commented Feb 12, 2024

Feature Proposal Description

Alignment with Express API

HTTP RFC Standards Compliance

API Stability

Feature Examples

Checklist:

nickajacks1 commented Feb 12, 2024 • edited Loading

gaby commented Feb 12, 2024

ReneWerner87 commented Feb 12, 2024

ReneWerner87 commented Feb 16, 2024

efectn commented Feb 16, 2024

ReneWerner87 commented Feb 16, 2024

ReneWerner87 commented Feb 16, 2024

efectn commented Feb 16, 2024 • edited Loading

Fenny commented Feb 20, 2024 • edited Loading

sixcolors commented Feb 20, 2024 • edited Loading

nickajacks1 commented Feb 21, 2024

sixcolors commented Feb 21, 2024 • edited Loading

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

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

nickajacks1 commented Feb 12, 2024 •

edited

Loading

efectn commented Feb 16, 2024 •

edited

Loading

Fenny commented Feb 20, 2024 •

edited

Loading

sixcolors commented Feb 20, 2024 •

edited

Loading

sixcolors commented Feb 21, 2024 •

edited

Loading