Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Request/response handling is very hard to find. #311

Open
buffpojken opened this issue Jan 4, 2021 · 3 comments
Open

Request/response handling is very hard to find. #311

buffpojken opened this issue Jan 4, 2021 · 3 comments

Comments

@buffpojken
Copy link

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
Copy link
Author

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

@filmaj
Copy link
Member

filmaj commented Jan 23, 2021

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
Copy link
Contributor

shalvah commented Nov 23, 2021

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

No branches or pull requests

3 participants