docs: overview of LB3 components and techniques they use #5122

bajtos · 2020-04-16T13:23:21Z

This is the first part of documentation for the spike #4099 How to migrate LB3 components.

I reviewed our official components and (most popular) community extensions, and compiled a list of techniques they use. The idea is to use this list of techniques to identify what content we need to write for LB3 extension maintainers to enable them to upgrade to LB4.

My intention is to commit this document so that it can serve as a kind of a Lightweight Architecture Decision Record. I created a new directory docs/spikes to hold spike-related docs.

@raymondfeng @jannyHou @emonddr (FA owners of Infrastructure for extensions): Please review the document. I am specifically looking for feedback on the list of techniques I identified in LB3 components - is there anything missing? Are there any techniques we don't want to cover at this time, e.g. because we want to wait until there is more demand for them or perhaps because we don't intend to support them in LB4 at all?

I would also like to invite the wider community (@strongloop/loopback-next, @strongloop/loopback-3x-maintainers) to join this discussion too. Is there any LB3 component that you are using in your project and would like to migrate to LB4, but not covered by my list? Let us know!

Below is the list of community extensions I reviewed. I really appreciate the effort our community put into creating extensions, you are awesome! ❤️ Please let us know if you are interested in bringing your extension over to LB4 and what kind of information would help you.

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 👈

jannyHou

~~For each item in the "Techniques", I guess you summarized based on existing issues/repositories/docs, if so, could you add them as references?~~

I think a more reasonable sequence is having the section "Overview of existing LB3 components" before "Techniques" (spent some time to guess the background of those techniques 🙈 )

Great effort! have a minor comment about the access control component.

jannyHou · 2020-04-16T19:42:21Z

docs/spikes/2020-04-how-to-migrate-lb3-components.md

+      `@configure` specific to each service (see the logger extension for an
+      example)._
+
+17. Inject models (entities & repositories) to the service. These models can be


nitpick: I feel LB4 usually uses a model's type, but does not inject it, the repositories are injected.

I know! In this list, I am trying to describe what I saw in LB3 components. How to map them to LB4 concept is another thing, I'll be looking into that once this PR is landed.

I'll add more content to this item to explain.

jannyHou · 2020-04-16T20:00:26Z

docs/spikes/2020-04-how-to-migrate-lb3-components.md

+
+### Authentication & authorization
+
+21. Add a custom step to the default authentication/authorization sequence, so


does "the default authentication/authorization sequence" mean LB4 sequence? There is only one action related to authentication currently. The authorization is handled by interceptor.

Good question.

By "default authentication/authorization sequence", I mean whatever steps are executed by LB3 runtime to authenticate and authorize an incoming request.

Obviously, this will be different in LB4.

I'll change "the default authentication/authorization sequence" to "to the default LB3 authentication/authorization workflow", I hope it will be easier to understand that way.

raymondfeng · 2020-04-17T01:50:06Z

@bajtos Great write-up. I need a bit more time to review it.

emonddr

Good write up

bajtos · 2020-04-20T12:32:29Z

@jannyHou

I think a more reasonable sequence is having the section "Overview of existing LB3 components" before "Techniques" (spent some time to guess the background of those techniques 🙈 )

Ah, sorry for the confusion. The overview section was meant to add more background for people who are interested to dig deeper and/or understand where are the techniques coming from. For many readers, the first section (Techniques) should provide enough information so that they can skip the Overview. I can add a short note to explain this, would that help?

@raymondfeng

Great write-up. I need a bit more time to review it.

Sure, I understand it's a lot of information to digest. Any ETA on when you will have that time? This PR is a part of a task committed for April milestone and there are two more steps to be done, I am concerned the schedule is a bit tight.

jannyHou · 2020-04-20T13:37:17Z

For many readers, the first section (Techniques) should provide enough information so that they can skip the Overview. I can add a short note to explain this, would that help?

Fair enough 👍 thank you sounds good to me.

agnes512

👍 Nice write up. It would be good to have a short note to explain what the Techniques section is for. I was confused too at beginning 😄

raymondfeng · 2020-04-21T22:31:13Z

docs/spikes/2020-04-how-to-migrate-lb3-components.md

+
+1. How to structure the extension code to receive user-provided configuration &
+   target app instance. What are the instructions for adding a LB4 component to
+   a LB4 app.


It's not obvious as there is no explanation of LB3 component's signature (app, config, callback). Maybe something like Expected component module layout and exports?

raymondfeng · 2020-04-21T22:34:49Z

docs/spikes/2020-04-how-to-migrate-lb3-components.md

+
+3. How to migrate a component exporting mixins. See
+   [Migrating model mixins ](https://loopback.io/doc/en/lb4/migration-models-mixins.html)
+   for migration guide for app developers (mixin consumers).


Maybe describe what a LB3 component can contribute to the application when it's mounted?

Maybe a digram would help if it shows the handshake between an application and a component as well as typical artifacts exported from a component.

To some extent, a LB3 application asks its components to extend/patch the app. In contrast, a LB4 application imports bindings (representing the component's contribution to the app) from its components.

Those are all good suggestions for the migration guide, I'll capture them in a note in this document. Please note that I am not that far yet, here I am just collecting and describinh different techniques used by the components.

bajtos · 2020-04-23T12:10:34Z

@jannyHou @nabdelgadir @raymondfeng thank you for thoughtful comments. I pushed a new commit 08572a2 that should address them, can you PTAL again?

Please note that this is not the ultimate final version of the document, we can further improve it in the next step of the spike #4099:

For each feature/pattern found in existing components, propose how to implement it in LB4 style. Some patterns may require functionality that's not available in LB4 yet. This is expected, put down a note and try to link to existing GitHub issues where possible. (Do not create any new issues yet!) Get the proposals reviewed & approved by the team before moving to the next step.

jannyHou

👏

nabdelgadir

👍

nabdelgadir · 2020-04-24T17:52:07Z

docs/spikes/2020-04-how-to-migrate-lb3-components.md

+
+### Services (local and remote)
+
+16. Add a new local service (a class providing JS/TS API), e.g. Push service or


Nitpick: I think the numbering is one off from here down

Great catch, thank you!

- Review of our official components - loopback-component-push, loopback-component-storage. - Review of (most popular) community extensions - Documentation explaining common techniques used by existing components. Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>

bajtos added spike Docs Migration labels Apr 16, 2020

bajtos added this to the April 2020 milestone Apr 16, 2020

bajtos requested review from raymondfeng, emonddr and jannyHou April 16, 2020 13:23

bajtos requested review from agnes512, deepakrkris, hacksparrow and nabdelgadir as code owners April 16, 2020 13:23

bajtos self-assigned this Apr 16, 2020

jannyHou reviewed Apr 16, 2020

View reviewed changes

emonddr approved these changes Apr 17, 2020

View reviewed changes

agnes512 reviewed Apr 21, 2020

View reviewed changes

raymondfeng reviewed Apr 21, 2020

View reviewed changes

bajtos requested review from raymondfeng, agnes512 and jannyHou April 23, 2020 12:10

emonddr approved these changes Apr 23, 2020

View reviewed changes

agnes512 approved these changes Apr 23, 2020

View reviewed changes

jannyHou approved these changes Apr 24, 2020

View reviewed changes

nabdelgadir approved these changes Apr 24, 2020

View reviewed changes

bajtos force-pushed the spike/migrate-components branch from 08572a2 to 6509f52 Compare April 27, 2020 06:50

bajtos merged commit b8421f0 into master Apr 27, 2020

bajtos deleted the spike/migrate-components branch April 27, 2020 07:27

bajtos mentioned this pull request Apr 27, 2020

Spike: How to migrate LB3 components #4099

Closed

11 tasks

This was referenced May 5, 2020

Illustrate the handshake between an application and a component #5337

Open

Clean up extension template and docs #5336

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: overview of LB3 components and techniques they use #5122

docs: overview of LB3 components and techniques they use #5122

bajtos commented Apr 16, 2020

jannyHou left a comment

jannyHou Apr 16, 2020

bajtos Apr 20, 2020

bajtos Apr 23, 2020

jannyHou Apr 16, 2020

bajtos Apr 20, 2020

bajtos Apr 23, 2020

raymondfeng commented Apr 17, 2020

emonddr left a comment

bajtos commented Apr 20, 2020

jannyHou commented Apr 20, 2020

agnes512 left a comment

raymondfeng Apr 21, 2020 •

edited

Loading

raymondfeng Apr 21, 2020

raymondfeng Apr 21, 2020

raymondfeng Apr 21, 2020

bajtos Apr 23, 2020

bajtos commented Apr 23, 2020

jannyHou left a comment

nabdelgadir left a comment

nabdelgadir Apr 24, 2020

bajtos Apr 27, 2020


		### Authentication & authorization

		21. Add a custom step to the default authentication/authorization sequence, so


		### Services (local and remote)

		16. Add a new local service (a class providing JS/TS API), e.g. Push service or

docs: overview of LB3 components and techniques they use #5122

docs: overview of LB3 components and techniques they use #5122

Conversation

bajtos commented Apr 16, 2020

Checklist

jannyHou 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

raymondfeng commented Apr 17, 2020

emonddr left a comment

Choose a reason for hiding this comment

bajtos commented Apr 20, 2020

jannyHou commented Apr 20, 2020

agnes512 left a comment

Choose a reason for hiding this comment

raymondfeng Apr 21, 2020 • edited Loading

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

bajtos commented Apr 23, 2020

jannyHou left a comment

Choose a reason for hiding this comment

nabdelgadir left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raymondfeng Apr 21, 2020 •

edited

Loading