From 71c8eb4a76d8f3c04624b40c67a75563593dbbd0 Mon Sep 17 00:00:00 2001 From: sjvans <30337871+sjvans@users.noreply.github.com> Date: Wed, 10 Jul 2024 10:15:17 +0200 Subject: [PATCH 1/5] [cds^8] cds.middlewares.before --- node.js/cds-serve.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md index 198ea898e..c96d63c1e 100644 --- a/node.js/cds-serve.md +++ b/node.js/cds-serve.md @@ -217,11 +217,10 @@ app.use (cds.middlewares.before, protocol_adapter) The standard set of middlewares uses the following order: ```js cds.middlewares.before = [ - context(), // provides cds.context - trace(), // provides detailed trace logs when DEBUG=trace - auth(), // provides req.user & tenant - ctx_auth(), // propagates auth results to cds.context - ctx_model(), // fills in cds.context.model + context(), // provides cds.context + trace(), // provides detailed trace logs when DEBUG=trace + auth(), // provides cds.context.user & cds.context.tenant + ctx_model(), // fills in cds.context.model ] ``` From 8fe4e137a52bdb6f73edd1a4f4627e90c2c656fa Mon Sep 17 00:00:00 2001 From: D050513 Date: Wed, 10 Jul 2024 10:33:49 +0200 Subject: [PATCH 2/5] rework cds.middlewares.before --- node.js/cds-serve.md | 50 +++++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md index c96d63c1e..2fa84e198 100644 --- a/node.js/cds-serve.md +++ b/node.js/cds-serve.md @@ -215,6 +215,7 @@ app.use (cds.middlewares.before, protocol_adapter) ``` The standard set of middlewares uses the following order: + ```js cds.middlewares.before = [ context(), // provides cds.context @@ -234,20 +235,22 @@ _ctx_auth_ requires that _authentication_ has run before. This middleware initializes [cds.context](events#cds-context) and starts the continuation. It's required for every application. + +### . trace() {.method} + +The tracing middleware allows you to do a first-level performance analysis. It logs how much time is spent on which layer of the framework when serving a request. +To enable this middleware, you can set for example the [environment variable](cds-log#debug-env-variable) `DEBUG=trace`. + + ### . auth() {.method} [By configuring an authentication strategy](./authentication#strategies), a middleware is mounted that fulfills the configured strategy and subsequently adds the user and tenant identified by that strategy to [cds.context](events#cds-context). + ### . ctx_model() {.method} It adds the currently active model to the continuation. It's required for all applications using extensibility or feature toggles. -### . trace() {.method} - -The tracing middleware allows you to do a first-level performance analysis. It logs how much time is spent on which layer of the framework when serving a request. -To enable this middleware, you can set for example the [environment variable](cds-log#debug-env-variable) `DEBUG=trace`. - - ### .add(mw, pos?) {.method} @@ -255,15 +258,16 @@ Registers additional middlewares at the specified position. `mw` must be a function that returns an express middleware. `pos` specified the index or a relative position within the middleware chain. If not specified, the middleware is added to the end. - ```js - cds.middlewares.add (mw, {at:0}) // to the front - cds.middlewares.add (mw, {at:2}) - cds.middlewares.add (mw, {before:'auth'}) - cds.middlewares.add (mw, {after:'auth'}) - cds.middlewares.add (mw) // to the end - ``` +```js +cds.middlewares.add (mw, {at:0}) // to the front +cds.middlewares.add (mw, {at:2}) +cds.middlewares.add (mw, {before:'auth'}) +cds.middlewares.add (mw, {after:'auth'}) +cds.middlewares.add (mw) // to the end +```
+ ### Custom Middlewares The configuration of middlewares must be done programmatically before bootstrapping the CDS services, for example, in a [custom server.js](cds-serve#custom-server-js). @@ -274,7 +278,6 @@ The framework exports the default middlewares itself and the list of middlewares cds.middlewares = { auth, context, - ctx_auth, ctx_model, errors, trace, @@ -282,13 +285,13 @@ cds.middlewares = { context(), trace(), auth(), - ctx_auth(), ctx_model() ] } ``` In order to plug in custom middlewares, you can override the complete list of middlewares or extend the list programmatically. + ::: warning Be aware that overriding requires constant updates as new middlewares by the framework are not automatically taken over. ::: @@ -298,31 +301,34 @@ Be aware that overriding requires constant updates as new middlewares by the fra #### Customization of `req.user` You can register middlewares to customize `req.user`. -It must be set after authentication but before `cds.context` is initialized. +It must be done after authentication. +If the `cds.context.tenant` is manipulated as well, it must also be done before `cds.context.model` is set for the current request. ```js cds.middlewares.before = [ cds.middlewares.context(), cds.middlewares.trace(), cds.middlewares.auth(), - function req_user (req,res,next) { - req.user.id = '' + req.user.id + function ctx_user (_,__,next) { + const ctx = cds.context + ctx.user.id = '' + ctx.user.id next() }, - cds.middlewares.ctx_auth() + cds.middlewares.ctx_model() ] ``` #### Enabling Feature Flags +You can register middlewares to customize `req.features`. +It must be done before `cds.context.model` is set for the current request. ```js cds.middlewares.before = [ cds.middlewares.context(), cds.middlewares.trace(), cds.middlewares.auth(), - cds.middlewares.ctx_auth(), - function req_features (req,res,next) { + function req_features (req,_,next) { req.features = ['', ''] next() }, @@ -332,11 +338,13 @@ cds.middlewares.before = [ [Learn more about Feature Vector Providers.](../guides/extensibility/feature-toggles#feature-vector-providers){.learn-more} + ### Current Limitations - Configuration of middlewares must be done programmatically. + ## cds. protocols The framework provides adapters for OData V4 and REST out of the box. In addition, GraphQL can be served by using our open source package [`@cap-js/graphql`](https://github.com/cap-js/graphql). From c2ed27ade957dc66ef057dc3259eb32d46042724 Mon Sep 17 00:00:00 2001 From: sjvans <30337871+sjvans@users.noreply.github.com> Date: Wed, 10 Jul 2024 10:39:14 +0200 Subject: [PATCH 3/5] Update node.js/cds-serve.md --- node.js/cds-serve.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md index 2fa84e198..02a4f9d6f 100644 --- a/node.js/cds-serve.md +++ b/node.js/cds-serve.md @@ -302,7 +302,7 @@ Be aware that overriding requires constant updates as new middlewares by the fra You can register middlewares to customize `req.user`. It must be done after authentication. -If the `cds.context.tenant` is manipulated as well, it must also be done before `cds.context.model` is set for the current request. +If `cds.context.tenant` is manipulated as well, it must also be done before `cds.context.model` is set for the current request. ```js cds.middlewares.before = [ From eae3fbaf5605c9aab1cc3f68c5e1f14a24534118 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Jeglinsky?= Date: Wed, 10 Jul 2024 11:20:36 +0200 Subject: [PATCH 4/5] Update node.js/cds-serve.md --- node.js/cds-serve.md | 1 + 1 file changed, 1 insertion(+) diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md index 02a4f9d6f..0c7a8a660 100644 --- a/node.js/cds-serve.md +++ b/node.js/cds-serve.md @@ -265,6 +265,7 @@ cds.middlewares.add (mw, {before:'auth'}) cds.middlewares.add (mw, {after:'auth'}) cds.middlewares.add (mw) // to the end ``` +
From 11ea0db7b5b57844a7676412772c05c586551496 Mon Sep 17 00:00:00 2001 From: sjvans <30337871+sjvans@users.noreply.github.com> Date: Wed, 10 Jul 2024 13:31:55 +0200 Subject: [PATCH 5/5] Apply suggestions from code review --- node.js/cds-serve.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/node.js/cds-serve.md b/node.js/cds-serve.md index 0c7a8a660..a062591fb 100644 --- a/node.js/cds-serve.md +++ b/node.js/cds-serve.md @@ -220,8 +220,8 @@ The standard set of middlewares uses the following order: cds.middlewares.before = [ context(), // provides cds.context trace(), // provides detailed trace logs when DEBUG=trace - auth(), // provides cds.context.user & cds.context.tenant - ctx_model(), // fills in cds.context.model + auth(), // provides cds.context.user & .tenant + ctx_model(), // fills in cds.context.model, in case of extensibility ] ```