feat: support for @sap/cds^7 middlewares/protocols (#86)

* Rename protocols `path` config to `endpoint`

* Collect services and init adapter on served

* Extract service collection from `CDSGraphQLAdapter`

* Undo indentation

* Mount adapter at configured `endpoint`

* Remove newline

* Move services into options argument

* Bump required `@sap/cds` version to 7

* Allow newer major versions for `@sap/cds` devDependency

* Add changelog entries

* Add step to README about annotating services

* Add `@graphql` annotation to services used by `cds.test`

* Add tests for prorocol annotations and endpoint config

* Fix typos

* Add note about required protocol annotations to changelog entry

* Fix function name

* Fix path to `gql` tag util

* Fix path to annotations `cds.test` project

* Add missing `@graphql` annotation to test service

* Revert "Rename protocols `path` config to `endpoint`"

This reverts commit eca7148.

* Use `path` instead of `endpoint` as router path

* Extract `GraphQLAdapter` function as module

* Log serving protocol and path equivalent to cds 6

* Bump `cds` version in `devDependencies` to `>=7`

* Make `GraphQLAdapter` accessible via root `index.js`

* Import cds in CRUD resolvers

* Don't overwrite other configured protocols in annotations test project

* Adjust test project `server.js` files to not overwrite configured protocols

* Fix configured graphql path in tests

* Remove `GraphQLAdapter` exposed at root

* Adjust logging of mount path to match other protocols

* Improve function name

* Fix and improve changelog entries

* Improve function name

---------

Co-authored-by: Heiko Witteborg <[email protected]>
Co-authored-by: Johannes Vogel <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -5,14 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Version 0.6.0 - tbd
+## Version 0.6.0 - 2023-06-23
 
 ### Added
 
+- Support for `@sap/cds^7` middlewares and protocols. Note: services now need to be annotated with protocol annotations such as `@graphql` or `@protocol: 'graphql'`.
+
 ### Changed
 
+- Bump required `@sap/cds` version to `>=7`
+- `@cap-js/graphql/index.js` now collects individual services and mounts the adapter as a protocol middleware on the `cds.on('served', ...)` event
+- Moved the `GraphQLAdapter` module to `lib/GraphQLAdapter.js` and merged it with `CDSGraphQLAdapter` previously found in `index.js` in the root directory
 - Don't generate fields that represent compositions of aspects within mutation types that represent services
-- Moved the `GraphQLAdapter` module to the root directory (`index.js`), simplifying the import process and reducing the required typing.
 - Disabled conjunction on the same field for the following operators:
   + `eq` (Equal)
   + `gt` (Greater Than)

README.md

@@ -19,7 +19,9 @@ _**WARNING:** This package is in an early general availability state. This means
 > This will automatically plugin to `@sap/cds` runtime, enabling the new [middlewares architecture](https://cap.cloud.sap/docs/node.js/middlewares) in Node.js, and register a GraphQL endpoint at `/graphql` serving all CRUD requests for the application services found in your model. 
   
 2. Run your server as usual, e.g. using `cds watch`.
-> The runtime will automatically serve all services via GraphQL at the default configured endpoint.
+
+3. Annotate the services you want to serve, e.g. using `@graphql` or `@protocol: 'graphql'`.
+> The runtime will serve all annotated services via GraphQL at the default configured endpoint.
 
 ## Limitations
 

index.js

@@ -1,28 +1,18 @@
 const cds = require('@sap/cds')
-const LOG = cds.log('graphql')
-const express = require('express')
-const { createHandler } = require('graphql-http/lib/use/express')
-const { generateSchema4 } = require('./lib/schema')
-const graphiql = require('./app/graphiql')
-const { decodeURIComponent } = cds.utils
+const DEBUG = cds.debug('adapters')
+const GraphQLAdapter = require('./lib/GraphQLAdapter')
 
-function GraphQLAdapter(options) {
-  const router = express.Router()
-  const { services } = options
-  const defaults = { graphiql: true }
-  const schema = generateSchema4(services)
-  options = { ...defaults, ...options }
-
-  router
-    .use(express.json()) //> required by logger below
-    .use((req, _, next) => {
-      LOG.info(req.method, req.body?.query || decodeURIComponent(req.query.query))
-      next()
+let services
+const _collectServicesAndMountAdapter = (srv, options) => {
+  if (!services) {
+    services = {}
+    cds.on('served', () => {
+      options.services = services
+      cds.app.use (options.path, cds.middlewares.before, GraphQLAdapter(options), cds.middlewares.after)
+      DEBUG?.('app.use(', options.path, ', ... )')
     })
-
-  if (options.graphiql) router.get('/', graphiql)
-  router.use((req, res) => createHandler({ schema, context: { req, res }, ...options })(req, res))
-  return router
+  }
+  services[srv.name] = srv
 }
 
-module.exports = GraphQLAdapter
+module.exports = _collectServicesAndMountAdapter

lib/GraphQLAdapter.js

@@ -0,0 +1,28 @@
+const cds = require('@sap/cds')
+const LOG = cds.log('graphql')
+const express = require('express')
+const { createHandler } = require('graphql-http/lib/use/express')
+const { generateSchema4 } = require('./schema')
+const graphiql = require('../app/graphiql')
+const { decodeURIComponent } = cds.utils
+
+function GraphQLAdapter(options) {
+  const router = express.Router()
+  const { services } = options
+  const defaults = { graphiql: true }
+  const schema = generateSchema4(services)
+  options = { ...defaults, ...options }
+
+  router
+    .use(express.json()) //> required by logger below
+    .use((req, _, next) => {
+      LOG.info(req.method, req.body?.query || decodeURIComponent(req.query.query))
+      next()
+    })
+
+  if (options.graphiql) router.get('/', graphiql)
+  router.use((req, res) => createHandler({ schema, context: { req, res }, ...options })(req, res))
+  return router
+}
+
+module.exports = GraphQLAdapter

lib/resolvers/crud/create.js

@@ -1,3 +1,4 @@
+const cds = require('@sap/cds/lib')
 const { INSERT } = cds.ql
 const { ARGS } = require('../../constants')
 const { getArgumentByName, astToEntries } = require('../parse/ast2cqn')

lib/resolvers/crud/delete.js

@@ -1,3 +1,4 @@
+const cds = require('@sap/cds/lib')
 const { DELETE } = cds.ql
 const { ARGS } = require('../../constants')
 const { getArgumentByName, astToWhere } = require('../parse/ast2cqn')

lib/resolvers/crud/read.js

@@ -1,3 +1,4 @@
+const cds = require('@sap/cds/lib')
 const { SELECT } = cds.ql
 const { ARGS, CONNECTION_FIELDS } = require('../../constants')
 const { getArgumentByName, astToColumns, astToWhere, astToOrderBy, astToLimit } = require('../parse/ast2cqn')

lib/resolvers/crud/update.js

@@ -1,3 +1,4 @@
+const cds = require('@sap/cds/lib')
 const { SELECT, UPDATE } = cds.ql
 const { ARGS } = require('../../constants')
 const { getArgumentByName, astToColumns, astToWhere, astToEntries } = require('../parse/ast2cqn')

package.json

@@ -36,7 +36,7 @@
     "graphql-http": "^1.16.0"
   },
   "peerDependencies": {
-    "@sap/cds": ">=6.3"
+    "@sap/cds": ">=7"
   },
   "devDependencies": {
     "axios": ">=0.24",

test/resources/annotations/server.js

@@ -0,0 +1,6 @@
+const cds = require('@sap/cds')
+const path = require('path')
+const protocols = cds.env.protocols ??= {}
+if (!protocols.graphql) protocols.graphql = {
+  path: '/custom-graphql-path', impl: path.join(__dirname, '../../../index.js')
+}