Request/response handling is very hard to find.

[buffpojken]

Is your feature request related to a problem? Please describe.
Coming back to Arc from a few major versions back, I found it very hard to find how http function handling had changed, and how it currently works, given the major changes in request/response-handling. Finding it today requires reading through the entire Runtime-section, and it's mentioned under middleware.

It's not clear if the changed to the incoming request object is a feature of Arc or if it requires the middleware, since it's documented under the middleware.

Describe the solution you'd like
I'd argue that how the http functions work is at the core of Arc, and that it should be moved to its own section, probably under each runtime as it's runtime-specific.

Describe alternatives you've considered
It could be moved to a complete new section under Reference with runtime-specific sections as well, which would increase visibility and make it a lot easier to find at the cost of muddying up the information hierarchy under Reference.

Perhaps a new section similar to the old Guides from the docs for v5 (https://v5.arc.codes/guides/http) which was both extremely clear and easy to find.

[buffpojken]

If this is something you'd wish to entertain, I'd be more than willing to make a PR with the suggested changes.

[filmaj]

Thanks for filing this!

I empathize with you about coming back to this a few major revisions behind. We have kept an upgrade guide in the docs up to date with each major revision, and I think some of the information you were looking for is in there. Perhaps the upgrade guide should be highlighted more? Right now it's all the way at the bottom of the sidebar menu on the docs site. Maybe we should put it under "Developer Experience"? And what about calling out the HTTP request/response format breaking changes in one of the last major versions in the HTTP-specific docs (I forget if it was 5->6 or 6->7)?

I'd argue that how the http functions work is at the core of Arc, and that it should be moved to its own section, probably under each runtime as it's runtime-specific.

I agree that http is at the core of arc. Are you suggesting having a sub-bullet points in the docs menu as so?

Runtime
  -> Node
    -> HTTP
  -> Deno
    -> HTTP
  -> Ruby
    -> HTTP
  -> Python
    -> HTTP

Would we therefore also want the other runtime features as sections in there, like events, queues, tables, etc.?

We should definitely highlight / link to the http request and response formats more in the runtime docs, though we have the luxury of being able to simply link to AWS docs' on the topic, which are also language-agnostic.

[shalvah]

This is a real need. I'm new to Arc (but have experience with Serverless) and am using Ruby, but I can't find any info on how to write a simple HTTP handler in the docs. What's more, the generated template is not correct (no request object is passed into the handler even though it declares one).