Java API Documentation

CHANGELOG.md

@@ -8,6 +8,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+* Added Java language binding documentation to the API reference. ([#1734](https://github.com/finos/FDC3/pull/1734))
+* Added a notes field to Trade type ([#1563](https://github.com/finos/FDC3/pull/1563))
+* Added a notes field to Order and Product types ([#1597](https://github.com/finos/FDC3/pull/1597))
 * Added a classification field to Instrument context type ([#1665](https://github.com/finos/FDC3/pull/1665))
 * Added Go language binding. ([#1483](https://github.com/finos/FDC3/pull/1483))
 * Added details of and procedures for resolving fully-qualified appIds and unqualified appIds in the API and Bridging Parts of the Standard. ([#1523](https://github.com/finos/FDC3/pull/1523))
@@ -24,6 +27,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 * DACP `ContextMetadata` in `api.schema.json` now allows optional `antiReplay` claims on the wire (e.g. merged into `raiseIntentResultResponse.resultMetadata`). The agent proxy and reference web implementation forward `antiReplay` from app metadata on `raiseIntent` / `raiseIntentForContext` and merge it from `intentResultRequest` metadata into the intent result delivered to the raising app. Cucumber steps and features cover `iat` / `exp` / `jti` alongside signatures.
 
+* Refactored the WebSocket Connection Protocol (WSCP) to use role-specific connect messages with order determined by TCP initiator. `sharedSecret` is sent by the initiator only; acceptors MUST NOT echo it. Assigned app identity is carried in `implementationMetadata.appMetadata`.
+
 * Updated "Releasing FDC3 to NPM" instructions in README to reflect the current GitHub Actions release workflow. ([#1864](https://github.com/finos/FDC3/pull/1864))
 
 ### Deprecated

packages/fdc3-agent-proxy/src/listeners/DefaultIntentListener.ts

@@ -67,7 +67,7 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
         intentEventUuid: m.meta.eventUuid,
         raiseIntentRequestUuid: m.payload.raiseIntentRequestUuid,
         ...(appMetadata !== undefined && { metadata: appMetadata }),
-      }
+      },
     };
 
     return out;

packages/fdc3-schema/schemas/api/WSCPApplicationConnect.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/api/WSCPApplicationConnect.schema.json",
+  "title": "WebSocket Connection Protocol Application Connect",
+  "description": "Connect message sent by a native application during the WSCP handshake. When the application is the TCP initiator it MUST include sharedSecret. When the application is the acceptor (responding to WSCPDesktopAgentConnect) it MUST NOT include sharedSecret.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/$defs/WSCPApplicationConnectBase"
+    },
+    {
+      "$ref": "WSCPConnectionStep.schema.json"
+    }
+  ],
+  "$defs": {
+    "WSCPApplicationConnectBase": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "title": "WSCPApplicationConnect Message Type",
+          "const": "WSCPApplicationConnect"
+        },
+        "payload": {
+          "title": "WSCPApplicationConnect Payload",
+          "type": "object",
+          "properties": {
+            "protocolVersion": {
+              "title": "Protocol version",
+              "description": "WSCP protocol version.",
+              "type": "string",
+              "const": "1.0"
+            },
+            "sharedSecret": {
+              "title": "Shared secret",
+              "description": "Pairing credential scoped to a single (fdc3Session, appInstance) pair. MUST be included when the application is the TCP initiator. MUST NOT be included when the application is the acceptor.",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false,
+          "required": ["protocolVersion"]
+        },
+        "meta": {
+          "$ref": "WSCPConnectionStep.schema.json#/$defs/ConnectionStepMeta"
+        }
+      },
+      "required": ["type", "payload", "meta"],
+      "additionalProperties": false
+    }
+  }
+}

packages/fdc3-schema/schemas/api/WSCPConnectFailed.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/api/WSCPConnectFailed.schema.json",
+  "title": "WebSocket Connection Protocol Connect Failed",
+  "description": "Message sent by the acceptor if the WSCP handshake fails.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/$defs/WSCPConnectFailedBase"
+    },
+    {
+      "$ref": "WSCPConnectionStep.schema.json"
+    }
+  ],
+  "$defs": {
+    "WSCPConnectFailedBase": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "title": "WSCPConnectFailed Message Type",
+          "const": "WSCPConnectFailed"
+        },
+        "payload": {
+          "title": "WSCPConnectFailed Payload",
+          "type": "object",
+          "properties": {
+            "message": {
+              "title": "Connection failed message",
+              "description": "Human-readable description of why the handshake failed.",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false,
+          "required": ["message"]
+        },
+        "meta": {
+          "$ref": "WSCPConnectionStep.schema.json#/$defs/ConnectionStepMeta"
+        }
+      },
+      "required": ["type", "payload", "meta"],
+      "additionalProperties": false
+    }
+  }
+}

packages/fdc3-schema/schemas/api/WSCPConnectionStep.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/api/WSCPConnectionStep.schema.json",
+  "title": "WebSocket Connection Protocol Message",
+  "type": "object",
+  "description": "A message used during the WebSocket connection flow between a native application and a Desktop Agent. Used for messages sent in either direction.",
+  "properties": {
+    "type": {
+      "title": "Connection Step Message type",
+      "type": "string",
+      "enum": [
+        "WSCPApplicationConnect",
+        "WSCPDesktopAgentConnect",
+        "WSCPConnectFailed",
+        "WSCPGoodbye"
+      ],
+      "description": "Identifies the type of the WebSocket connection step message."
+    },
+    "payload": {
+      "title": "Message payload",
+      "type": "object",
+      "description": "The message payload, containing data pertaining to this connection step.",
+      "additionalProperties": true
+    },
+    "meta": {
+      "title": "Connection Step Metadata",
+      "description": "Metadata for a WebSocket Connection Protocol message.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/DisconnectStepMeta"
+        },
+        {
+          "$ref": "#/$defs/ConnectionStepMeta"
+        }
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "meta"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "ConnectionStepMeta": {
+      "type": "object",
+      "properties": {
+        "connectionAttemptUuid": {
+          "$ref": "common.schema.json#/$defs/ConnectionAttemptUuid"
+        },
+        "timestamp": {
+          "$ref": "common.schema.json#/$defs/Timestamp"
+        }
+      },
+      "required": [
+        "timestamp",
+        "connectionAttemptUuid"
+      ],
+      "additionalProperties": false
+    },
+    "DisconnectStepMeta": {
+      "type": "object",
+      "properties": {
+        "timestamp": {
+          "$ref": "common.schema.json#/$defs/Timestamp"
+        }
+      },
+      "required": [
+        "timestamp"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

packages/fdc3-schema/schemas/api/WSCPDesktopAgentConnect.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/api/WSCPDesktopAgentConnect.schema.json",
+  "title": "WebSocket Connection Protocol Desktop Agent Connect",
+  "description": "Connect message sent by a Desktop Agent during the WSCP handshake. When the Desktop Agent is the TCP initiator it MUST include sharedSecret. When the Desktop Agent is the acceptor (responding to WSCPApplicationConnect) it MUST NOT include sharedSecret.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/$defs/WSCPDesktopAgentConnectBase"
+    },
+    {
+      "$ref": "WSCPConnectionStep.schema.json"
+    }
+  ],
+  "$defs": {
+    "WSCPDesktopAgentConnectBase": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "title": "WSCPDesktopAgentConnect Message Type",
+          "const": "WSCPDesktopAgentConnect"
+        },
+        "payload": {
+          "title": "WSCPDesktopAgentConnect Payload",
+          "type": "object",
+          "properties": {
+            "protocolVersion": {
+              "title": "Protocol version",
+              "description": "WSCP protocol version.",
+              "type": "string",
+              "const": "1.0"
+            },
+            "sharedSecret": {
+              "title": "Shared secret",
+              "description": "Pairing credential scoped to a single (fdc3Session, appInstance) pair. MUST be included when the Desktop Agent is the TCP initiator. MUST NOT be included when the Desktop Agent is the acceptor.",
+              "type": "string"
+            },
+            "implementationMetadata": {
+              "title": "ImplementationMetadata",
+              "description": "Implementation metadata for the Desktop Agent, including the connecting application instance's appMetadata (MUST include at least appId and instanceId). Same shape as returned by fdc3.getInfo().",
+              "$ref": "api.schema.json#/definitions/ImplementationMetadata"
+            }
+          },
+          "additionalProperties": false,
+          "required": ["protocolVersion", "implementationMetadata"]
+        },
+        "meta": {
+          "$ref": "WSCPConnectionStep.schema.json#/$defs/ConnectionStepMeta"
+        }
+      },
+      "required": ["type", "payload", "meta"],
+      "additionalProperties": false
+    }
+  }
+}

packages/fdc3-schema/schemas/api/WSCPGoodbye.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/api/WSCPGoodbye.schema.json",
+  "title": "WebSocket Connection Protocol Goodbye",
+  "description": "Goodbye message to be sent when disconnecting a WebSocket connection. The acceptor should close the connection after receiving this message but retain the sharedSecret mapping for the app instance so that a subsequent connect can resume the session.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/$defs/WSCPGoodbyeBase"
+    },
+    {
+      "$ref": "WSCPConnectionStep.schema.json"
+    }
+  ],
+  "$defs": {
+    "WSCPGoodbyeBase": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "title": "WSCPGoodbye Message Type",
+          "const": "WSCPGoodbye"
+        },
+        "meta": {
+          "$ref": "WSCPConnectionStep.schema.json#/$defs/DisconnectStepMeta"
+        }
+      },
+      "required": ["type", "meta"],
+      "additionalProperties": false
+    }
+  }
+}