Skip to content

Latest commit

 

History

History
148 lines (107 loc) · 4.25 KB

middlewares.md

File metadata and controls

148 lines (107 loc) · 4.25 KB
label synopsis status
Middlewares
Learn about default middlewares and all the options of customization.
released

Middlewares

{{$frontmatter?.synopsis}}

::: warning Customization is a beta feature. Beta features aren't part of the officially delivered scope that SAP guarantees for future releases. For more information, see Important Disclaimers and Legal Information. :::

Configuration

To use tracing and customization, you can start the application with the middlewares profile from the command line using --profile middlewares or set cds.requires.middlewares = true within your project configuration.

::: tip This configuration becomes the default with one of our upcoming releases. :::

Default Middlewares

Before Middlewares

cds.context

This middleware initializes cds.context and starts the continuation. It's required for every application.

Tracing

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 DEBUG=trace.

Learn more about needed configuration.{.learn-more}

Authentication

By configuring an authentication strategy, a middleware is mounted that fulfills the configured strategy.

cds.context.user / cds.context.tenant

This middleware adds user and tenant identified by authentication middleware to cds.context.

cds.context.model

It adds the currently active model to the continuation. It's required for all applications using extensibility or feature toggles.

Default Order

By default, the middlewares are executed in the following order:

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
]

::: warning Be aware of the interdependencies of middlewares ctx_model requires that cds.context middleware has run before. ctx_auth requires that authentication has run before. :::

Customization

The configuration of middlewares must be done programmatically before bootstrapping the CDS services, for example, in a custom server.js.

Basics

The framework exports the default middlewares itself and the list of middlewares which run before the protocol adapter starts processing the request.

cds.middlewares = {
  auth,
  context,
  ctx_auth,
  ctx_model,
  errors,
  trace,
  before = [
    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. :::

Learn more about the middlewares Default Order.{.learn-more}

Customization of req.user

You can register middlewares to customize req.user. It must be set after authentication but before cds.context is initialized.

cds.middlewares.before = [
  cds.middlewares.context(),
  cds.middlewares.trace(),
  cds.middlewares.auth(),
  function req_user (req,res,next) {
    req.user.id = '<my-idp>' + req.user.id
    next()
  },
  cds.middlewares.ctx_auth()
]

Enabling Feature Flags

cds.middlewares.before = [
  cds.middlewares.context(),
  cds.middlewares.trace(),
  cds.middlewares.auth(),
  cds.middlewares.ctx_auth(),
  function req_features (req,res,next) {
    req.features = ['<feature-1>', '<feature-2>']
    next()
  },
  cds.middlewares.ctx_model()
]

Learn more about Feature Vector Providers.{.learn-more}

Current Limitations

  • Configuration of middlewares must be done programmatically.