CAPire

Appearance

On this page

Middlewares ​

Learn about default middlewares and all the options of customization.

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.

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:

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
]
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
]

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.

js
cds.middlewares = {
  auth,
  context,
  ctx_auth,
  ctx_model,
  errors,
  trace,
  before = [
    context(),
    trace(),
    auth(),
    ctx_auth(),
    ctx_model()
  ]
}
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.

Customization of req.user ​

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

js
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()
]
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 ​

js
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()
]
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.

Current Limitations ​

  • Configuration of middlewares must be done programmatically.