@cap-js-community/odata-v2-adapter
Advanced tools
Exposes a full-fledged OData V2 service, converting OData V2 requests to CDS OData V4 service calls and responses back. Runs in context of the SAP Cloud Application Programming Model (CAP) using CDS Node.js module @sap/cds or CDS Java modules com.sap.cds.
npm add @cap-js-community/odata-v2-adapter in @sap/cds projectcds-serve to start server
The OData V2 adapter for CDS instantiates an Express router. The following options are available:
true.true.''.'odata/v2'. Default path is 'v2' for CDS <7 or middlewares deactivated.'all'.4004.'auto' to infer the target from server url after listening. Default is e.g. 'auto'.'odata/v4'. Default path is '' for CDS <7 or middlewares deactivated.{}.false.'/mtx/v1'.true.10485760 (10 MB).false.false.false.false.false.false.'100mb'.true.true.true.true.'/#TRANSIENT#'.false.false.'attachment'.false.true.false.'info'.'json'.x-forwarded headers are processed. Default is true.true.'memory'.listening event instead of registering routes immediately. Default is true.All OData V2 adapter for CDS options can also be specified as part of CDS project-specific configuration under section
cds.cov2apand accessed during runtime viacds.env.cov2ap.
Options can also be passed as command line environment variable, by converting the camel-cased option name to snake-case. Underscores (
_) need then to be escaped as double underscore (__) when provided via command line environment variable.Example:
- path => CDS_COV2AP_PATH=odatav2
- quoteSearch => quote_search => CDS_COV2AP_QUOTE__SEARCH=false
CDS OData V2 adapter is instantiated via CDS plugin as singleton, which is exposed at:
const cds = require("@sap/cds");
cds.cov2ap;
The singleton can also be instantiated manually and accessed in custom server via:
const cov2ap = require("@cap-js-community/odata-v2-adapter");
cov2ap.singleton();
Before middleware routes can be registered on the OData V2 adapter for CDS singleton, to be executed before the main route processing. The before middleware routes can be registered as single function or as array of route functions.
Single before route can be registered as follows:
const cds = require("@sap/cds");
cds.on("bootstrap", (app) => {
cds.cov2ap.before = (req, res, next) => {
// custom route processing
next();
};
});
Multiple before routes can be registered as follows:
const cds = require("@sap/cds");
cds.on("bootstrap", (app) => {
cds.cov2ap.before = [
(req, res, next) => {
// custom route processing
next();
},
(req, res, next) => {
// custom route processing
next();
},
];
});
./srv/server.js:
const cds = require("@sap/cds");
const cov2ap = require("@cap-js-community/odata-v2-adapter");
cds.on("bootstrap", (app) => app.use(cov2ap()));
module.exports = cds.server;
Logging is based on cds.log, therefore CDS logging configurations apply.
| Component | Module Name(s) |
|---|---|
| OData V2 adapter for CDS | cov2ap |
In order to enable Kibana friendly logging for cds.log
feature toggle cds.features.kibana_formatter: true needs to be set.
Debug mode can be activated to log requests and responses processed (V2) and initiated (V4) by OData V2 adapter for CDS. The following information can be retrieved for analysis:
Debug log level can be activated
CDS_LOG_LEVELS_COV2AP=debugcds.env in code: cds.env.log.levels.cov2ap = "debug"Details on how to set CDS environment can be found at cds.env.
Logging can be configured to respect the following log levels:
[cov2ap] - Proxy: Proxy processing error[cov2ap] - Cache: Metadata cache error[cov2ap] - Authorization: Authorization header parsing error[cov2ap] - MetadataRequest: Metadata request processing error[cov2ap] - Request: Request processing error[cov2ap] - Response: Response processing error[cov2ap] - Batch: Batch processing error[cov2ap] - AggregationKey: Aggregation key error[cov2ap] - MediaStream: Media stream processing error[cov2ap] - FileUpload: File upload processing error[cov2ap] - Service: Invalid service definition (name, path)[cov2ap] - Context: Invalid (sub-)definition (name, path)[cov2ap] - ContentDisposition: Content disposition warning[cov2ap] - Batch: Changeset order deviation (req, res)[cov2ap] - Request: Log OData V2 client request (url, headers, body)[cov2ap] - ProxyRequest: Log OData V4 proxy request (url, headers, body)[cov2ap] - ProxyResponse: Log OData V4 proxy response (status code/message, headers, body)[cov2ap] - Response: Log OData V2 client response (status code/message, headers, body)[cov2ap] - [HPM]: Proxy middleware processing logsThe following OData V2 adapter for CDS specific annotations are supported:
Service Level:
@protocol: [{ kind: 'odata-v2', path: '<path>' }]: Specifies an additional custom relative OData V2 protocol service path (prepending OData V2 protocol prefix)@protocol: [{ kind: 'odata-v2', path: '/<path>' }]: Specifies an additional custom absolute OData V2 protocol service path (ignoring OData V2 protocol prefix)@cov2ap.ignore: Exclude service from OData V2 adapter conversion (service is not exposed as OData V2 service)Entity Level:
@cov2ap.analytics: false: Suppress analytics conversion for the annotated entity, if set to false.@cov2ap.analytics.skipForKey: Suppress analytical conversion for the annotated entity, if all dimension key elements are requested@cov2ap.deltaResponse: 'timestamp': Delta response '__delta' is added to response data of annotated entity with current timestamp information.@cov2ap.isoTime: Values of type cds.Time (Edm.Time) are represented in ISO 8601 format for annotated entity.@cov2ap.isoDate: Values of type cds.Date (Edm.DateTime) are represented in ISO 8601 format for annotated entity.@cov2ap.isoDateTime: Values of type cds.DateTime (Edm.DateTimeOffset) are represented in ISO 8601 format for annotated entity.@cov2ap.isoTimestamp: Values of type cds.Timestamp (Edm.DateTimeOffset) are represented in ISO 8601 format for annotated entity.@cov2ap.isoDateTimeOffset: Values of type Edm.DateTimeOffset (cds.DateTime, cds.Timestamp) are represented in ISO 8601 format for annotated entity.Entity Element Level:
@Core.ContentDisposition.Filename: <element>: Specifies entity element, representing the filename during file upload/download.@Core.ContentDisposition.Type: '<value>': Controls the content disposition behavior in client/browser (inline or attachment).@cov2ap.headerDecode: [...]: Array of sequential decoding procedures ('uri', 'uriComponent', 'base64') used for media entity upload header.CDS project configuration cds.odata.version shall be set to v4, as OData V2 maps to OData V4.
CDS supports modelling features that are not compatible with OData V2 standard:
@odata.singleton is not supported in combination with OData V2cds.odata.structs: true is not supported in combination with OData V2cds.Map is not supported in combination with OData V2array of or many in entity element definitions lead to CDS compilation error: Element must not be an "array of" for OData V2To provide an OData V2 service based on the OData V2 adapter for CDS, those CDS modelling features must not be used. In general any CDS OData API flavor must not be used in combination with OData V2 adapter for CDS.
Per default, those modelling incompatibilities are reported as Warning and will not stop the compilation.
The resulting EDMX V2 may be invalid and not processable by an OData V2 client. To prevent this situation and fail
early to detect modelling incompatibilities, the severity for respective codes can be increased to Error,
by setting the following environment variables:
{
"cdsc": {
"severities": {
"odata-spec-violation-array": "Error",
"odata-spec-violation-param": "Error",
"odata-spec-violation-returns": "Error",
"odata-spec-violation-assoc": "Error",
"odata-spec-violation-constraints": "Error"
}
}
}
When deploying the OData V2 adapter for CDS to Cloud Foundry, make sure that it has access to the whole CDS model.
Especially, it’s the case, that normally the Node.js server is only based on folder srv and folder db is then missing on Cloud Foundry.
To come around this situation, trigger a cds build during development time, that generates a csn.json at location gen/srv/srv/csn.json.
Point your Cloud Foundry deployment of the OData V2 adapter for CDS to the folder gen/srv (using manifest.json or MTA), so that
the CDS models can be found via file srv/csn.json, during runtime execution on Cloud Foundry.
Make sure, that all i18n property files reside next to the csn.json in a i18n or _i18n folder, to be detected by localization.
OData V2 adapter for CDS supports multitenant scenarios. Basic extensibility is already supported in combination with the CDS MTX module. More advanced extensibility scenarios and feature toggles are supported in combination with the CDS Streamlined MTX services.
In order to provide the feature toggle vector to be used to build-up the corresponding CSN and EDMX metadata documents,
the Express request object req needs to enhanced by feature definitions.
To add support for a specific feature toggles management you can add a simple Express middleware as follows, for example, in your server.js:
const cds = require("@sap/cds");
cds.on(
"bootstrap",
(app) =>
(cds.cov2ap.before = (req, res, next) => {
req.features = req.features || ["advanced"];
next();
}),
);
CDS OData V2 adapter includes an CDS build task, that allows to prepare the OData V2 EDMX files for MTX sidecar app.
The build task is automatically active, in case project is running in multi-tenant context including MTX sidecar.
It can be deactivated using option cds.cov2ap.build: false.
This repository comes with a suite of unit-tests covering the complete proxy implementation. The tests can be executed as follows:
npm run test:unit (source)test-hana/_env/db/default-services.json in format:
{
"hana": [
{
"credentials": {}
}
]
}
npm run deploy:hananpm run test:hana (source)5432postgresnpm run deploy:postgresnpm run test:postgres (source)npm testAll tests are executed as part of the GitHub Actions Continuous Integration (CI) pipeline.
The OData V2 service provided by the OData V2 adapter for CDS can be used to serve an SAP Fiori Elements V2 UI.
SAP Fiori Elements V2 examples:
Examples can be tested as follows:
npm startnpm run start:hananpm run start:postgresResponse compressions can be enabled, by registering the compression Node.js
module in Express app at bootstrap time, e.g. in srv/server.js:
const cds = require("@sap/cds");
const compression = require("compression");
cds.on("bootstrap", (app) => {
cds.cov2ap.before = [compression({ filter: shouldCompress })];
});
function shouldCompress(req, res) {
const type = res.getHeader("Content-Type");
if (type && typeof type === "string" && type.startsWith("multipart/mixed")) {
return true;
}
// fallback to standard filter function
return compression.filter(req, res);
}
The shown compression filter function enables compression including
OData Batch ($batch) calls with content type multipart/mixed.
@sap/approuter now support out-of-the-box compression for OData $batch calls with multipart/mixed.
It's disabled by default, but can be enabled using option compressResponseMixedTypeContent.
npm install @cap-js-community/odata-v2-adapter -s in @sap/cds project./srv/index.js:const express = require("express");
const cds = require("@sap/cds");
const cov2ap = require("@cap-js-community/odata-v2-adapter");
const host = "0.0.0.0";
const port = process.env.PORT || 4004;
(async () => {
const app = express();
// OData V2
app.use(cov2ap());
// OData V4
await cds.connect.to("db");
await cds.serve("all").in(app);
const server = app.listen(port, host, () => console.info(`app is listing at ${host}:${port}`));
server.on("error", (error) => console.error(error.stack));
})();
node srv/index from the project root to start the server:
Note that @sap/cds is a peer dependency and needs to be available as module as well.
For CAP Java projects prefer the Native CDS OData V2 Adapter (com.sap.cds/cds-adapter-odata-v2).
npm install @cap-js-community/odata-v2-adapter -s in @sap/cds projectdb, srv, app) or compile a generated CSN (see details below)./srv/index.js:const express = require("express");
const cov2ap = require("@cap-js-community/odata-v2-adapter");
const host = "0.0.0.0";
const port = process.env.PORT || 4004;
(async () => {
const app = express();
// OData V2
app.use(
cov2ap({
target: "<odata-v4-backend-url>", // locally e.g. http://localhost:8080
services: {
"<odata-v4-service-path>": "<qualified.ServiceName>",
},
registerOnListening: false,
}),
);
const server = app.listen(port, host, () => console.info(`app is listing at ${host}:${port}`));
server.on("error", (error) => console.error(error.stack));
})();
node srv/index from the project root to start the server:
target set to the deployed OData V4 backend URL.
This can be retrieved from the Cloud Foundry environment using process.env, for example,
from the destinations environment variable. Locally e.g. http://localhost:8080 can be used.services, every OData V4 service URL path needs to mapped to
the corresponding fully qualified CDS service name, e.g. "/odata/v4/MainService/": "test.MainService",
to establish the back-link connection between OData URL and its CDS service.db, srv, add folders, or a compiled (untransformed) srv.json is provided.
This can be generated by using the following command: cds srv -s all -o .cds build can be triggered as described in section "Cloud Foundry Deployment".model (especially if csn.json/srv.json option is used).csn.json in a i18n or _i18n folder, to be detected by localization.mtxEndpoint) by setting option mtxRemote: true.mtxEndpoint can be specified as absolute url (starting with http:// or https://), to be able to address MTX Sidecar
possibly available under a target different from OData v4 backend URL. If not specified absolutely, target is prepended to mtxEndpoint.npm testnpm start
http://localhost:4004/odata/v2/mainhttp://localhost:4004/odata/v2/main/$metadatahttp://localhost:4004/odata/v2/main/Header?$expand=ItemsFor more details see CONTRIBUTION guide.
What’s New in OData Version 4.0
This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.
Copyright 2024 SAP SE or an SAP affiliate company and contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.
FAQs
OData V2 adapter for CDS
We found that @cap-js-community/odata-v2-adapter demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.