Serving Provided Services

• cds. serve (...)
  • .from (model)
  • .to (protocol)
  • .at (path)
  • .in (express app)
  • .with (impl)
• cds. middlewares
  • . context()
  • . trace()
  • . auth()
  • . ctx_model()
  • .add(mw, pos?)
  • Custom Middlewares
  • Current Limitations
• cds. protocols
  • @protocol
  • @path
  • Custom Protocol Adapter
  • Current Limitations

cds. serve (...)

Use cds.serve() to construct service providers from the service definitions in corresponding CDS models.

Declaration:

async function cds.serve (
  service        : 'all' | string | cds.Service | typeof cds.Service,
  options        : { service = 'all', ... }
) .from ( model  : string | CSN )         // default: cds.model
  .to ( protocol : string | 'rest' | 'odata' | 'odata-v2' | 'odata-v4' | ... )
  .at ( path     : string )
  .in ( app      : express.Application )  // default: cds.app
.with ( impl     : string | function | cds.Service | typeof cds.Service )

Common Usages:

const { CatalogService } = await cds.serve ('my-services')

const app = require('express')()
cds.serve('all') .in (app)

Arguments:

• name specifies which service to construct a provider for; use all to construct providers for all definitions found in the models.

cds.serve('CatalogService')  //> serve a single service
cds.serve('all')             //> serve all services found

You may alternatively specify a string starting with './' or refer to a file name with a non-identifier character in it, like '-' below, as a convenient shortcut to serve all services from that model:

cds.serve('./reviews-service')  //> is not an identifier through './'
cds.serve('reviews-service')    //> same as '-', hence both act as:
cds.serve('all').from('./reviews-service')

The method returns a fluent API object, which is also a Promise resolving to either an object with 'all' constructed service providers, or to the single one created in case you specified a single service:

const { CatalogService, AdminService } = await cds.serve('all')
const ReviewsService = await cds.serve('ReviewsService')

Caching:

The constructed service providers are cached in cds.services, which (a) makes them accessible to cds.connect, as well as (b) allows us to extend already constructed services through subsequent invocation of cds.serve.

Common Usages and Defaults

Most commonly, you'd use cds.serve in a custom file to add all the services to your express.js app as follows:

const app = require('express')()
cds.serve('all').in(app)
app.listen()

This uses these defaults for all options:

Option	Description	Default
cds.serve ...	which services to construct	'all' services
↳ .from	models to load definitions from	'./srv' folder
↳ .in	express app to mount to	— none —
↳ .to	client protocol to serve to	'fiori'
↳ .at	endpoint path to serve at	@path or .name
↳ .with	implementation function	@impl or ._source.js

Alternatively you can construct services individually, also from other models, and also mount them yourself, as document in the subsequent sections on individual fluent API options.

If you just want to add some additional middleware, it's recommended to bootstrap from a custom server.js.

.from (model)

Allows to determine the CDS models to fetch service definitions from, which can be specified as one of:

• A filename of a single model, which gets loaded and parsed with [cds.load]
• A name of a folder containing several models, also loaded with [cds.load]
• The string 'all' as a shortcut for all models in the './srv' folder
• An already parsed model in CSN format

The latter allows you to [cds.load] or dynamically construct models yourself and pass in the CSN models, as in this example:

const csn = await cds.load('my-services.cds')
cds.serve('all').from(csn)...

If omitted, './srv' is used as default.

.to (protocol)

Allows to specify the protocol through which to expose the service. Currently supported values are:

• 'rest' plain HTTP rest protocol without any OData-specific extensions
• 'odata' standard OData rest protocol without any Fiori-specific extensions
• 'fiori' OData protocol with all Fiori-specific extensions like Draft enabled

If omitted, 'fiori' is used as default.

.at (path)

Allows to programmatically specify the mount point for the service.

Note that this is only possible when constructing single services:

cds.serve('CatalogService').at('/cat')
cds.serve('all').at('/cat') //> error

If omitted, the mount point is determined from annotation @path, if present, or from the service's lowercase name, excluding trailing Service.

service MyService @(path:'/cat'){...}  //> served at: /cat
service CatalogService {...}           //> served at: /catalog

.in (express app)

Adds all service providers as routers to the given express app.

const app = require('express')()
cds.serve('all').in(app)
app.listen()

.with (impl)

Allows to specify a function that adds [event handlers] to the service provider, either as a function or as a string referring to a separate node module containing the function.

cds.serve('./srv/cat-service.cds') .with ('./srv/cat-service.js')

cds.serve('./srv/cat-service') .with (srv => {
  srv.on ('READ','Books', (req) => req.reply([...]))
})

Learn more about using impl annotations.Learn more about adding event handlers.

Note that this is only possible when constructing single services:

cds.serve('CatalogService') .with (srv=>{...})
cds.serve('all') .with (srv=>{...})  //> error

If omitted, an implementation is resolved from annotation @impl, if present, or from a .js file with the same basename than the CDS model, for example:

service MyService @(impl:'cat-service.js'){...}

srv/cat-service.cds  #> CDS model with service definition
srv/cat-service.js   #> service implementation used by default

cds. middlewares

For each service served at a certain protocol, the framework registers a configurable set of express middlewares by default like so:

app.use (cds.middlewares.before, protocol_adapter)

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 & .tenant
  ctx_model(), // fills in cds.context.model, in case of extensibility
]

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.

. context()

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

. trace()

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.

. auth()

By configuring an authentication strategy, a middleware is mounted that fulfills the configured strategy and subsequently adds the user and tenant identified by that strategy to cds.context.

. ctx_model()

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

.add(mw, pos?)

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.

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.

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_model,
  errors,
  trace,
  before = [
    context(),
    trace(),
    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 cds.context.user

You can register middlewares to customize cds.context.user. It must be done after authentication. If cds.context.tenant is manipulated as well, it must also be done before cds.context.model is set for the current request.

cds.middlewares.before = [
  cds.middlewares.context(),
  cds.middlewares.trace(),
  cds.middlewares.auth(),
  function ctx_user (_,__,next) {
    const ctx = cds.context
    ctx.user.id = '<my-idp>' + ctx.user.id
    next()
  },
  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.

cds.middlewares.before = [
  cds.middlewares.context(),
  cds.middlewares.trace(),
  cds.middlewares.auth(),
  function req_features (req,_,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.

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.

By default, the protocols are served at the following path:

protocol	path
OData V4	/odata/v4
REST	/rest
GraphQL	/graphql

@protocol

Configures at which protocol(s) a service is served.

@odata
service CatalogService {}
//> serves CatalogService at: /odata/v4/catalog

@protocol: 'odata'
service CatalogService {}
//> serves CatalogService at: /odata/v4/catalog

@protocol: ['odata', 'rest', 'graphql']
service CatalogService {}
//> serves CatalogService at: /odata/v4/catalog, /rest/catalog and /graphql

@protocol: [{ kind: 'odata', path: 'some/path' }]
service CatalogService {}
//> serves CatalogService at: /odata/v4/some/path

Note, that

• the shortcuts @rest, @odata, @graphql are only supported for services served at only one protocol.
• @protocol has precedence over the shortcuts.
• @protocol.path has precedence over @path.
• the default protocol is OData V4.
• odata is a shortcut for odata-v4.
• @protocol: 'none' will treat the service as internal.

@path

Configures the path at which a service is served.

@path: 'browse'
service CatalogService {}
//> serves CatalogService at: /odata/v4/browse

@path: '/browse'
service CatalogService {}
//> serves CatalogService at: /browse

Be aware that using an absolute path will disallow serving the service at multiple protocols.

Custom Protocol Adapter

Similar to the configuration of the GraphQL Adapter, you can plug in your own protocol. The impl property must point to the implementation of your protocol adapter. Additional options for the protocol adapter are provided on the same level.

cds.env.protocols = {
  'custom-protocol': { path: '/custom', impl: '<custom-impl.js>', ...options }
}

Current Limitations

• Configuration of protocols must be done programmatically.
• Additional protocols do not respect @protocol annotation yet.
• The configured protocols do not show up in the index.html yet.