WebSocket Adapter for CDS

About this Project

Exposes a WebSocket protocol via WebSocket standard or Socket.IO for CDS services. Runs in the context of the SAP Cloud Application Programming Model (CAP) using @sap/cds (CDS Node.js).

Table of Contents

• Getting Started
• Usage
  • Server
  • Client
• Options
• Documentation
  • Architecture Overview
  • Protocol Annotations
  • WebSocket Server
  • WebSocket Implementation
    • WebSocket Service
    • WebSocket Mixin
  • Server Socket
  • Upgrade Request
  • Service Facade
  • Middlewares
  • Tenant Isolation
  • Authentication & Authorization
  • Invocation Context
  • Transactional Safety
    • CDS Persistent Queue
  • Client Determination
    • Filtering Operators
    • Event Users
    • Event Roles
    • Event Contexts
    • Event Client Identifiers
    • Event Emit Headers
    • Value Aggregation
    • Format Headers
    • Ignore Definitions
  • WebSocket Format
    • Push Channel Protocol (PCP)
    • Event-Driven Side Effects
    • Cloud Events
    • Custom Format
    • Generic Format
  • Connect & Disconnect
  • Server Client Service
  • Approuter
    • Paths
  • Operations
    • Operation Results
    • Unbound Operations
    • Special Operations
    • Bound Operations
    • CRUD Operations
  • Examples
    • Fiori (UI5)
    • Todo (UI5)
    • Chat (HTML)
  • Unit-Tests
  • Adapters
    • WS Standard Adapters
    • Socket.IO Adapters
  • Deployment
• Support, Feedback, Contributing
• Code of Conduct
• Licensing

Getting Started

• Run npm add @cap-js-community/websocket in @sap/cds project
• Add a WebSocket-enabled CDS service:

  @ws
  service ChatService {
    event received {
      text: String;
    }
  }
  

• Emit event from business logic:

  await srv.emit("received", { text: "Hello World!" });
  

• Start server via cds-serve
• Access the service endpoint via the WebSocket client

Usage

Server

• Run npm add @cap-js-community/websocket in @sap/cds project
• Create a service to be exposed as websocket protocol: srv/chat-service.cds

  @protocol: 'websocket'
  service ChatService {
    function message(text: String) returns String;
    event received {
      text: String;
    }
  }
  

• Implement CDS websocket service: srv/chat-service.js

  module.exports = (srv) => {
    srv.on("message", async (req) => {
      await srv.emit("received", req.data);
      return req.data.text;
    });
  };
  

Client

In browser environment implement the websocket client: index.html

WebSocket Standard (kind: ws)

• Connect with WebSocket

  const protocol = window.location.protocol === "https:" ? "wss://" : "ws://";
  const socket = new WebSocket(protocol + window.location.host + "/ws/chat");
  

• Emit event

  socket.send(
    JSON.stringify({
      event: "message",
      data: { text: input.value },
    }),
  );
  

• Listen to event

  socket.addEventListener("message", (message) => {
    const payload = JSON.parse(message.data);
    switch (payload.event) {
      case "received":
        console.log(payload.data.text);
        break;
    }
  });
  

Socket.IO (kind: socket.io)

• Connect with the Socket.IO client

  const socket = io("/ws/chat");
  

• Emit event

  socket.emit("message", { text: "Hello World" });
  

• Listen to event

  socket.on("received", (message) => {
    console.log(message.text);
  });
  

Options

The CDS websocket modules can be configured with the following options:

• kind: String: Websocket implementation kind (ws, socket.io). Default is 'ws'.
• impl: String: Websocket implementation path. Module provides default for kind.
• options: Object: Websocket implementation configuration options. Default is {}.
• adapter: Object: Websocket adapter configuration options. Default is {}.
• adapter.impl: String: Websocket adapter implementation (redis, @socket.io/redis-adapter, @socket.io/redis-streams-adapter). Default is ''.
• adapter.options: Object: Websocket adapter implementation options. Default is {}.
• adapter.options.key: String: Websocket adapter channel prefix. Default is websocket.
• adapter.config: Object: Websocket adapter implementation configurations (i.e. Redis client options). Default is {}.
• adapter.active: Boolean: Enable websocket adapter. Default is true.
• adapter.local: Boolean: Enable websocket adapter in local environment. Default is false.

All CDS Websocket options can also be specified as part of CDS project-specific configuration under section cds.websocket and accessed during runtime via cds.env.websocket.

Documentation

Architecture Overview

The CDS Websocket module supports the following use-cases:

• Connect multiple websocket clients (browser and non-browser) to CAP server websockets
• Process websockets messages as CDS entity CRUD, action and function calls
• Broadcast CDS events across local server websockets and multi-instance server websockets (via Redis)
• Broadcast CDS events across multiple CAP server applications and application instances (via Redis)
• Tenant-ware emits/broadcasts CDS events from server websockets to websocket clients (browser and non-browser)
• Emit/Broadcast CDS events to a subset of websocket clients leveraging users, event contexts or client identifiers
• Websocket events support different formats (JSON, PCP, CloudEvents or custom format)

Protocol Annotations

The CDS WebSocket module supports the following protocol definitions options in CDS:

• @ws
• @websocket
• @protocol: 'ws'
• @protocol: 'websocket'
• @protocol: [{ kind: 'ws', path: 'chat' }]
• @protocol: [{ kind: 'websocket', path: 'chat' }]

If a protocol path is not specified (e.g., via @path), it is determined from service name.

If the specified path is relative (i.e., does not start with a slash /), it is appended to the default protocol path e.g. /ws. If the path is absolute (i.e., starts with a slash /), it is used as is.

Examples:

• @path: 'chat: Service is exposed at /ws/chat
• @path: '/chat: Service is exposed at /chat

WebSocket Server

The CDS websocket server is exposed on cds object implementation-independent at cds.ws and implementation-specific at cds.wss for WebSocket Standard or cds.io for Socket.IO. Additional listeners can be registered bypassing CDS definitions and runtime. WebSocket server options can be provided via cds.websocket.options.

Default protocol path is /ws and can be overwritten via cds.env.protocols.websocket.path resp. cds.env.protocols.ws.path;

WebSocket Implementation

The CDS websocket server supports the following two websocket implementations:

• WebSocket Standard (via Node.js ws package): cds.websocket.kind: "ws" (default)
• Socket.IO: cds.websocket.kind: "socket.io"
• Custom Server: A custom websocket server implementation can be provided via a path relative to the project root with the configuration cds.websocket.impl (e.g. cds.websocket.impl: './server/xyz.js').

The server implementation abstracts from the concrete websocket implementation. The websocket client still needs to be implemented websocket-implementation-specific.

WebSocket Service

Annotated services with websocket protocol are exposed at endpoint: /ws/<service-path>:

Websocket client connection happens as follows for exposed endpoints:

• WS: const socket = new WebSocket("ws://localhost:4004/ws/chat");
• Socket.IO: const socket = io("ws/chat")

WebSocket Mixin

Non-websocket services can contain events and operations that are exposed or accessible as websocket events via the concept of mixin websocket services. Mixin event and operations need to be annotated with @websocket or @ws.

**Hi