wsContext in other formats

Author: oklemenz2

CHANGELOG.md

@@ -19,12 +19,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Clean websocket context from internal read-only attributes
 - Normalize client identifier on upgrade request `request.id`
 - Return 404 when url cannot be associated with a service in upgrade request
+- Parse string values according to operation parameter type in custom formats (e.g. `pcp`)
 
 ### Added
 
 - `reset` all contexts via `wsContext` flag `reset: true`
 - Support multiple contexts in `wsContext` with array value for `context`
 - Document usage of `srv.tx(req).emit` for tenant and user propagation in WS broadcasting
+- Document usage of `wsContext` for format `pcp` and `cloudevents`
 
 ## Version 1.5.2 - 2025-01-10
 

README.md

@@ -1010,6 +1010,30 @@ To configure the PCP message format the following annotations are available:
   - `@websocket.pcp.action, @ws.pcp.action: Boolean`: Expose the string value of the annotated event element as
     `pcp-action` field in the PCP message. Default `MESSAGE`.
 
+##### Manage Contexts
+
+To manage contexts in format `pcp`, `wsContext` event can be emitted in the following way:
+
+- Model `wsContext` CDS service operation as follows:
+  ```
+  @ws.pcp.action: 'wsContext'
+  action wsContext(context: String, exit: Boolean, reset: Boolean);
+  ```
+- Call `wsContext` message in `pcp` format like this:
+
+  ```
+  pcp-action:wsContext
+  pcp-body-type:text
+  context:context
+  exit:false
+  reset:true
+
+  wsContext
+  ```
+
+The PCP action needs to match an operation with annotation `@websocket.pcp.action` or `@ws.pcp.action`.
+Modeled action parameters `context`, `exit` and `reset` are mapped from `pcp` message fields.
+
 #### Cloud Events
 
 CDS WebSocket module supports the [Cloud Events](https://cloudevents.io) specification out-of-the-box according to
@@ -1237,6 +1261,32 @@ action sendCloudEventMap(
 Unmapped operation parameters are consumed as cloud event data section and can be skipped for cloud event data section
 via `@ws.ignore`, if not necessary.
 
+##### Manage Contexts
+
+To manage contexts in format `cloudevent`, `wsContext` event can be emitted in the following way:
+
+- Model `wsContext` CDS service operation as follows:
+  ```
+  @ws.cloudevent.name: 'event.ws.context'
+  action wsContext(context: String, exit: Boolean, reset: Boolean);
+  ```
+- Call `wsContext` message in `cloudevents` format like this:
+  ```
+  {
+    specversion: "1.0",
+    type: "event.ws.context",
+    source: "CloudEventService",
+    data: {
+      context: "context",
+      exit: false,
+      reset: true,
+    }
+  }
+  ```
+
+The cloud event type needs to match an operation with annotation `@websocket.cloudevent.name` or `@ws.cloudevent.name`.
+Modeled action parameters `context`, `exit` and `reset` are mapped from `cloudevent` message data section.
+
 ##### Cloud Event Format Alternative
 
 Alternatives for format `cloudevent` also allows to use the plural name `@websocket.format: 'cloudevents'` or `@ws.format: 'cloudevents'`,

src/format/generic.js

@@ -36,7 +36,7 @@ class GenericFormat extends BaseFormat {
         data: result,
       };
     }
-    this.LOG?.error(`Operation could not be determined`, data);
+    this.LOG?.error(`Operation could not be determined from name`, data);
     return {
       event: undefined,
       data: {},
@@ -283,6 +283,52 @@ class GenericFormat extends BaseFormat {
   serialize(data) {
     return this.origin === "json" ? data : JSON.stringify(data);
   }
+
+  /**
+   * Serialize value to string
+   * @param value Value
+   * @returns {string} String value
+   */
+  stringValue(value) {
+    if (value instanceof Date) {
+      return value.toISOString();
+    } else if (value instanceof Object) {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  }
+
+  /**
+   * Parse string value based on type
+   * @param value Value
+   * @param type Type
+   * @returns {string|boolean|number|Date} Parsed value
+   */
+  parseStringValue(value, type) {
+    if (value === undefined || value === null) {
+      return value;
+    }
+    if (type === "cds.Boolean" && ["false", "true"].includes(value)) {
+      return value === "true";
+    }
+    if (
+      (type.startsWith("cds.Int") ||
+        type.startsWith("cds.UInt") ||
+        type.startsWith("cds.Decimal") ||
+        type.startsWith("cds.Double")) &&
+      !isNaN(value)
+    ) {
+      return parseFloat(value);
+    }
+    if (
+      ["cds.Date", "cds.DateTime", "cds.Timestamp"].includes(type) &&
+      new Date(value) instanceof Date &&
+      !isNaN(new Date(value))
+    ) {
+      return new Date(value);
+    }
+    return value;
+  }
 }
 
 module.exports = GenericFormat;

src/format/pcp.js

@@ -24,7 +24,7 @@ class PCPFormat extends GenericFormat {
     if (splitPos !== -1) {
       const result = {};
       const message = data.substring(splitPos + SEPARATOR.length);
-      const pcpFields = extractPcpFields(data.substring(0, splitPos));
+      const pcpFields = this.extractPcpFields(data.substring(0, splitPos));
       const operation = Object.values(this.service.operations).find((operation) => {
         return (
           (operation["@websocket.pcp.action"] &&
@@ -41,14 +41,15 @@ class PCPFormat extends GenericFormat {
           if (param["@websocket.pcp.message"] || param["@ws.pcp.message"]) {
             result[param.name] = message;
           } else if (pcpFields[param.name] !== undefined) {
-            result[param.name] = pcpFields[param.name];
+            result[param.name] = this.parseStringValue(pcpFields[param.name], param.type);
           }
         }
         return {
           event: this.localName(operation.name),
           data: result,
         };
       }
+      this.LOG?.error(`Operation could not be determined from action`, data);
     }
     LOG?.error("Error parsing pcp format", data);
     return {
@@ -75,79 +76,70 @@ class PCPFormat extends GenericFormat {
     });
     const pcpEvent =
       eventDefinition?.["@websocket.pcp.event"] || eventDefinition?.["@ws.pcp.event"] ? event : undefined;
-    const pcpFields = serializePcpFields(data, typeof pcpMessage, pcpAction, pcpEvent, eventDefinition?.elements);
+    const pcpFields = this.serializePcpFields(data, typeof pcpMessage, pcpAction, pcpEvent, eventDefinition?.elements);
     return pcpFields + pcpMessage;
   }
-}
 
-const serializePcpFields = (pcpFields, messageType, pcpAction, pcpEvent, elements) => {
-  let pcpBodyType = "";
-  if (messageType === "string") {
-    pcpBodyType = "text";
-  } else if (messageType === "blob" || messageType === "arraybuffer") {
-    pcpBodyType = "binary";
-  }
-  let serialized = "";
-  if (pcpFields && typeof pcpFields === "object") {
-    for (const fieldName in pcpFields) {
-      const fieldValue = stringValue(pcpFields[fieldName]);
-      const element = elements?.[fieldName];
-      if (element) {
-        if (element["@websocket.ignore"] || element["@ws.ignore"]) {
-          continue;
-        }
-        if (fieldValue && fieldName.indexOf("pcp-") !== 0) {
-          serialized += escape(fieldName) + ":" + escape(fieldValue) + "\n";
+  serializePcpFields(pcpFields, messageType, pcpAction, pcpEvent, elements) {
+    let pcpBodyType = "";
+    if (messageType === "string") {
+      pcpBodyType = "text";
+    } else if (messageType === "blob" || messageType === "arraybuffer") {
+      pcpBodyType = "binary";
+    }
+    let serialized = "";
+    if (pcpFields && typeof pcpFields === "object") {
+      for (const fieldName in pcpFields) {
+        const fieldValue = this.stringValue(pcpFields[fieldName]);
+        const element = elements?.[fieldName];
+        if (element) {
+          if (element["@websocket.ignore"] || element["@ws.ignore"]) {
+            continue;
+          }
+          if (fieldValue && fieldName.indexOf("pcp-") !== 0) {
+            serialized += this.escape(fieldName) + ":" + this.escape(fieldValue) + "\n";
+          }
         }
       }
     }
+    return (
+      (pcpAction ? "pcp-action:" + pcpAction + "\n" : "") +
+      (pcpEvent ? "pcp-event:" + pcpEvent + "\n" : "") +
+      "pcp-body-type:" +
+      pcpBodyType +
+      "\n" +
+      serialized +
+      "\n"
+    );
   }
-  return (
-    (pcpAction ? "pcp-action:" + pcpAction + "\n" : "") +
-    (pcpEvent ? "pcp-event:" + pcpEvent + "\n" : "") +
-    "pcp-body-type:" +
-    pcpBodyType +
-    "\n" +
-    serialized +
-    "\n"
-  );
-};
 
-const extractPcpFields = (header) => {
-  const pcpFields = {};
-  for (const field of header.split("\n")) {
-    const lines = field.match(DESERIALIZE_REGEX);
-    if (lines && lines.length === 3) {
-      pcpFields[unescape(lines[1])] = unescape(lines[2]);
+  extractPcpFields(header) {
+    const pcpFields = {};
+    for (const field of header.split("\n")) {
+      const lines = field.match(DESERIALIZE_REGEX);
+      if (lines && lines.length === 3) {
+        pcpFields[this.unescape(lines[1])] = this.unescape(lines[2]);
+      }
     }
+    return pcpFields;
   }
-  return pcpFields;
-};
-
-const escape = (unescaped) => {
-  return unescaped.replace(/\\/g, "\\\\").replace(/:/g, "\\:").replace(/\n/g, "\\n");
-};
 
-const unescape = (escaped) => {
-  return escaped
-    .split("\u0008")
-    .map((part) => {
-      return part
-        .replace(/\\\\/g, "\u0008")
-        .replace(/\\:/g, ":")
-        .replace(/\\n/g, "\n")
-        .replace(/\u0008/g, "\\");
-    })
-    .join("\u0008");
-};
+  escape(unescaped) {
+    return unescaped.replace(/\\/g, "\\\\").replace(/:/g, "\\:").replace(/\n/g, "\\n");
+  }
 
-const stringValue = (value) => {
-  if (value instanceof Date) {
-    return value.toISOString();
-  } else if (value instanceof Object) {
-    return JSON.stringify(value);
+  unescape(escaped) {
+    return escaped
+      .split("\u0008")
+      .map((part) => {
+        return part
+          .replace(/\\\\/g, "\u0008")
+          .replace(/\\:/g, ":")
+          .replace(/\\n/g, "\n")
+          .replace(/\u0008/g, "\\");
+      })
+      .join("\u0008");
   }
-  return String(value);
-};
+}
 
 module.exports = PCPFormat;

test/_env/srv/cloudevent.cds

@@ -11,6 +11,9 @@ service CloudEventService {
         appinfoD : String;
     };
 
+    @ws.cloudevent.name: 'com.example.ws.context'
+    action wsContext(context: String, exit: Boolean, reset: Boolean);
+
     @ws.cloudevent.name: 'com.example.someevent.model'
     action sendCloudEventModel( specversion : String, type : String, source : String, subject : String, id : String, time : String, comexampleextension1 : String, comexampleothervalue : Integer, datacontenttype : String, data: CloudEventDataType) returns Boolean;
 
@@ -31,6 +34,9 @@ service CloudEventService {
                           appinfoC : Boolean,
                           @ws.ignore appinfoD : String) returns Boolean;
 
+    @ws.cloudevent.name: 'com.example.someevent.context'
+    action sendCloudEventContext() returns Boolean;
+
     event cloudEvent1 {
         appinfoA : String;
         appinfoB : Integer;

test/_env/srv/handlers/cloudevent.js

@@ -77,4 +77,18 @@ module.exports = (srv) => {
     });
     return true;
   });
+
+  srv.on("sendCloudEventContext", async (req) => {
+    await srv.emit(
+      "cloudEvent1",
+      {
+        appinfoA: "abcd",
+        appinfoB: 1234,
+        appinfoC: false,
+      },
+      {
+        context: "context",
+      },
+    );
+  });
 };

test/_env/srv/handlers/pcp.js

@@ -35,4 +35,18 @@ module.exports = (srv) => {
     );
     return true;
   });
+
+  srv.on("sendNotificationWithContext", async (req) => {
+    await srv.emit(
+      "notification1",
+      {
+        field1: req.data.field1 || "value1",
+        field2: req.data.field2 || "value2",
+      },
+      {
+        context: "context",
+      },
+    );
+    return true;
+  });
 };

test/_env/srv/pcp.cds

@@ -6,6 +6,12 @@ service PCPService {
     @ws.pcp.action: 'MESSAGE'
     action sendNotification(@ws.pcp.message message: String, field1: String, field2: String, @ws.ignore field3: String, ![pcp-action]: String) returns Boolean;
 
+    @ws.pcp.action: 'MESSAGE_CONTEXT'
+    action sendNotificationWithContext() returns Boolean;
+
+    @ws.pcp.action: 'wsContext'
+    action wsContext(context: String, exit: Boolean, reset: Boolean);
+
     @ws.pcp.event
     @ws.pcp.message: 'this is the body!'
     event notification1 {