docs: document the request-response cycle #4914

hacksparrow · 2020-03-18T16:26:30Z

Document the LB4 request-response cycle.
Closes #4836

Signed-off-by: Yaapa Hage [email protected]

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

npm test passes on your machine
New tests added or existing tests modified to cover all changes
Code conforms with the style guide
API Documentation in code was updated
Documentation in /docs/site was updated
Affected artifact templates in packages/cli were updated
Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

raymondfeng · 2020-03-20T16:20:17Z

@hacksparrow It's a great start.

I would like to see more information, such as:

Which tier of the request/response trip is extensible/configurable?
How to register an Express middleware? Is it possible?
How to add extensions to various tiers for different use cases? For example:
- authentication is enforced by an action in the sequence
- authorization is performed inside interceptors
- request body parsers
- ajv validation
- what about caching, rate-limiting, metrics, logging?
- error handling
More zoom-ins to various tiers to provide details.

raymondfeng · 2020-03-20T16:23:20Z

This diagram can be useful too - https://loopback.io/pages/en/lb4/imgs/loopback-overview.png

raymondfeng · 2020-03-20T16:25:21Z

A few other things:

How to access request/response objects
How to propagate contextual information via DI

agnes512

Nice writeup. I like the walk through part. And the diagram helps to understand the cycle. Just have a question about the non-controller endpoint part.

docs/site/Req-res-cycle.md

agnes512 · 2020-03-20T18:11:12Z

docs/site/Req-res-cycle.md

+Requests to non-controller endpoints are also intercepted by the app's sequence,
+but the control is handed over to the underlying Express middleware from the
+`InvokeMethod` phase, and never make it to `Send` unless the middleware calls
+`next()`. Unhandled error from Express middleware still reach `Reject`.


I like how we show the differences between these two endpoints. But I am a bit confused about services and the interceptor part. From my understanding, the structure we show above is:

/ ==> controller endpoint -> Services, Interceptors -> repositories Sequence --- \ ==> non-controller endpoint

But IIUC I think the interceptors can also be use with non-controller endpoints. Maybe we make it more clear here.

Can you point out where this structure is contradicted?

/ ==> controller endpoint -> Services, Interceptors -> repositories Sequence --- \ ==> non-controller endpoint

It looks like the interceptors cannot be used in non-controller endpoints. Is it true?

Interceptors work only on Controllers and Repositories, so non-controller endpoint handlers can't be intercepted.

I think I misunderstood the hander in the diagram as the non-controller endpoints.

Works on Services too.

IIRC, global interceptors also intercept non-controller routes.

dhmlau · 2020-03-24T13:36:32Z

@hacksparrow , would this PR closes #1833 instead of Closes #4836, if this PR is only about LB4 req/res cycle?

dhmlau · 2020-03-24T13:43:22Z

docs/site/Req-res-cycle.md

+### The request-response cycle
+
+The request-response cycle involves many components, especially if the request
+is to a controller-endpoint which interacts with a model.


the request is to a controller-endpoint -> the request is coming from a controller-endpoint?

Made it "interacts with the database".

hacksparrow · 2020-03-25T07:17:47Z

@dhmlau only LB4 req-res.

hacksparrow · 2020-03-25T15:47:07Z

@raymondfeng I have updated the PR with your inputs. However, since this PR is only for the flow of the request and the response, I have only mentioned your points from a high-level perspective.

Your points should be covered in another doc, maybe titled "Writing extensions for the request-response cycle".

raymondfeng · 2020-03-25T15:57:48Z

docs/site/Req-res-cycle.md

@@ -0,0 +1,278 @@
+---


Nitpick: let's name the file as Request-response-cycle.md.

raymondfeng · 2020-03-25T15:58:27Z

docs/site/Req-res-cycle.md

+title: 'Request-response cycle'
+keywords: LoopBack 4.0, LoopBack 4
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Application.html


Wrong html link. It should be /doc/en/lb4/Request-response-cycle.html.

raymondfeng · 2020-03-25T15:59:05Z

docs/site/Req-res-cycle.md

+taken by a request, to see how it makes its way through the various parts of the
+framework to return a result.
+
+### Setting up the request-responses infrastruture


request-responses -> request/response

raymondfeng · 2020-03-25T15:59:20Z

docs/site/Req-res-cycle.md

+permalink: /doc/en/lb4/Application.html
+---
+
+## The LoopBack 4 request-response cycle


Maybe request/response?

raymondfeng · 2020-03-25T16:01:06Z

docs/site/Req-res-cycle.md

+
+#### The sequence
+
+The sequence is a simple class with five injected helper methods. These five


with five injected helper methods -> with five injected helper methods by default?

Made it five injected helper methods in the constructor.

raymondfeng · 2020-03-25T16:03:59Z

docs/site/Req-res-cycle.md

+Now this is a step-wise sequence of what happens when a request is made to
+`http://localhost:4000/ping`.
+
+1. The request is intercepted by `MySequence`.


is intercepted by -> 'is dispatched to MySequence by the http server`?

raymondfeng · 2020-03-25T16:05:08Z

docs/site/Req-res-cycle.md

+`http://localhost:4000/ping`.
+
+1. The request is intercepted by `MySequence`.
+2. The route is then identified by `FindRoute`. There is a handler for this request.


based on the verb and path defined by OpenAPI decorators?

raymondfeng · 2020-03-25T16:06:14Z

docs/site/Req-res-cycle.md

+2. The route is then identified by `FindRoute`. There is a handler for this request.
+3. `ParseParams` then tries to parses any parameters might have been submitted.
+There is none.
+4. `InvokeMethod` then invokes the handler with empty parameters. It returns


empty parameters -> resolved parameters which is empty in this case?

raymondfeng · 2020-03-25T16:06:47Z

docs/site/Req-res-cycle.md

+4. `InvokeMethod` then invokes the handler with empty parameters. It returns
+whatever the handler returns, in this case, it is JSON object with `greeting`,
+`date`, `url`, and `headers` properties.
+5. `Send` then sends this JSON object back to the client.


Let's mention error handling here for Reject.

Added: 6. Reject is in place to catch any errors that might be thrown in any of the steps above.

hacksparrow · 2020-03-25T16:28:22Z

@raymondfeng applied all your feedback. PTAL.

raymondfeng · 2020-03-25T17:32:11Z

@hacksparrow Please fix the formatting error with npm run prettier:fix.

Document the LB4 request-response cycle. Signed-off-by: Yaapa Hage <[email protected]>

dhmlau · 2020-03-25T18:39:01Z

Merging the PR per @hacksparrow's request.

hacksparrow added the Docs label Mar 18, 2020

hacksparrow self-assigned this Mar 18, 2020

hacksparrow force-pushed the docs/req-res-cycle branch from 91bbe7a to d6c9466 Compare March 19, 2020 18:20

hacksparrow marked this pull request as ready for review March 20, 2020 14:42

hacksparrow requested review from agnes512, bajtos, deepakrkris, emonddr, jannyHou, nabdelgadir and raymondfeng as code owners March 20, 2020 14:42

hacksparrow force-pushed the docs/req-res-cycle branch 2 times, most recently from cad2d74 to a2ced75 Compare March 20, 2020 15:58

agnes512 reviewed Mar 20, 2020

View reviewed changes

hacksparrow force-pushed the docs/req-res-cycle branch 5 times, most recently from 3218a8b to 4d24da2 Compare March 23, 2020 14:15

dhmlau mentioned this pull request Mar 24, 2020

Document the LoopBack 4 request-response cycle #1833

Closed

dhmlau added this to the Mar 2020 milestone Mar 24, 2020

dhmlau reviewed Mar 24, 2020

View reviewed changes

hacksparrow force-pushed the docs/req-res-cycle branch from 935ace2 to df3c79d Compare March 25, 2020 15:35

raymondfeng reviewed Mar 25, 2020

View reviewed changes

hacksparrow force-pushed the docs/req-res-cycle branch from d08a704 to fcd5a17 Compare March 25, 2020 16:27

raymondfeng approved these changes Mar 25, 2020

View reviewed changes

docs: document the request-response cycle

ab37b3f

Document the LB4 request-response cycle. Signed-off-by: Yaapa Hage <[email protected]>

hacksparrow force-pushed the docs/req-res-cycle branch from e571166 to ab37b3f Compare March 25, 2020 17:56

dhmlau merged commit 413c2a9 into master Mar 25, 2020

dhmlau deleted the docs/req-res-cycle branch March 25, 2020 18:38

dhmlau mentioned this pull request Mar 25, 2020

Migration Guide: Request-response cycle #4836

Closed

2 tasks

hacksparrow mentioned this pull request Apr 6, 2020

docs: side bar link to LB4 req-res doc #5044

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document the request-response cycle #4914

docs: document the request-response cycle #4914

hacksparrow commented Mar 18, 2020 •

edited by agnes512

Loading

raymondfeng commented Mar 20, 2020 •

edited

Loading

raymondfeng commented Mar 20, 2020

raymondfeng commented Mar 20, 2020

agnes512 left a comment

agnes512 Mar 20, 2020

hacksparrow Mar 23, 2020

agnes512 Mar 23, 2020

hacksparrow Mar 23, 2020

agnes512 Mar 23, 2020

hacksparrow Mar 23, 2020

raymondfeng Mar 25, 2020

dhmlau commented Mar 24, 2020

dhmlau Mar 24, 2020

hacksparrow Mar 25, 2020

hacksparrow commented Mar 25, 2020

hacksparrow commented Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

hacksparrow Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

raymondfeng Mar 25, 2020

hacksparrow Mar 25, 2020

hacksparrow commented Mar 25, 2020

raymondfeng commented Mar 25, 2020

dhmlau commented Mar 25, 2020


		#### The sequence

		The sequence is a simple class with five injected helper methods. These five

docs: document the request-response cycle #4914

docs: document the request-response cycle #4914

Conversation

hacksparrow commented Mar 18, 2020 • edited by agnes512 Loading

Checklist

raymondfeng commented Mar 20, 2020 • edited Loading

raymondfeng commented Mar 20, 2020

raymondfeng commented Mar 20, 2020

agnes512 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhmlau commented Mar 24, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hacksparrow commented Mar 25, 2020

hacksparrow commented Mar 25, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hacksparrow commented Mar 25, 2020

raymondfeng commented Mar 25, 2020

dhmlau commented Mar 25, 2020

hacksparrow commented Mar 18, 2020 •

edited by agnes512

Loading

raymondfeng commented Mar 20, 2020 •

edited

Loading