@lionweb/delta-protocol-repository-ws 0.7.0-beta.21

package/src/repository-impl.ts

@@ -0,0 +1,151 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    Command,
+    Event,
+    QueryMessage,
+    RepositoryReceivedMessage,
+    SemanticLogger,
+    semanticLoggerFunctionFrom,
+    SignOffRequest,
+    SignOffResponse,
+    SignOnRequest,
+    SignOnResponse
+} from "@lionweb/delta-protocol-common"
+import { LionWebId } from "@lionweb/json"
+
+import { createWebSocketServer, LowLevelServer } from "./server.js"
+import { commandAsEvent } from "./command-to-event.js"
+
+
+export type LionWebRepositoryParameters = {
+    port: number
+    semanticLogger?: SemanticLogger
+}
+
+type ClientMetadata = {
+    participationId: LionWebId
+    clientId: LionWebId
+}
+
+export class LionWebRepository {
+
+    constructor(private readonly lowLevelServer: LowLevelServer<Event>) {}
+
+    static async create({port, semanticLogger}: LionWebRepositoryParameters) {
+        const log = semanticLoggerFunctionFrom(semanticLogger)
+
+        let nextParticipationIdSequenceNumber = 0
+        const receiveMessageOnRepository = (clientMetadata: Partial<ClientMetadata>, message: Command | QueryMessage) => {
+            log(new RepositoryReceivedMessage({ ...clientMetadata}, message))
+            const checkedClientMetadata = (): ClientMetadata => {
+                if (clientMetadata.participationId === undefined) {
+                    throw new Error(`can't process an event if no participation has started`)   // TODO  instead: log an item, and fall through
+                }
+                // (now .clientId must be !== undefined too:)
+                return clientMetadata as ClientMetadata
+            }
+            switch (message.messageKind) {
+                case "SignOnRequest": {
+                    const { clientId, queryId } = message as SignOnRequest
+                    clientMetadata.participationId = `participation-${String.fromCharCode(97 + (nextParticipationIdSequenceNumber++))}`
+                    clientMetadata.clientId = clientId
+                    return {
+                        messageKind: "SignOnResponse",
+                        queryId,
+                        participationId: clientMetadata.participationId,
+                        protocolMessages: []
+                    } as SignOnResponse
+                }
+                case "SignOffRequest": {
+                    const { queryId } = message as SignOffRequest
+                    clientMetadata.participationId = undefined
+                    return {
+                        messageKind: "SignOffResponse",
+                        queryId,
+                        protocolMessages: []
+                    } as SignOffResponse
+                }
+                // all commands, in order of the specification (§ 6.5):
+                /*
+                 * **DEV note**: run
+                 *
+                 *  $ node src/code-reading/command-message-kinds.js
+                 *
+                 * inside the build package to generate the following cases.
+                 */
+                case "AddPartition":
+                case "DeletePartition":
+                case "ChangeClassifier":
+                case "AddProperty":
+                case "DeleteProperty":
+                case "ChangeProperty":
+                case "AddChild":
+                case "DeleteChild":
+                case "ReplaceChild":
+                case "MoveChildFromOtherContainment":
+                case "MoveChildFromOtherContainmentInSameParent":
+                case "MoveChildInSameContainment":
+                case "MoveAndReplaceChildFromOtherContainment":
+                case "MoveAndReplaceChildFromOtherContainmentInSameParent":
+                case "MoveAndReplaceChildInSameContainment":
+                case "AddAnnotation":
+                case "DeleteAnnotation":
+                case "ReplaceAnnotation":
+                case "MoveAnnotationFromOtherParent":
+                case "MoveAnnotationInSameParent":
+                case "MoveAndReplaceAnnotationFromOtherParent":
+                case "MoveAndReplaceAnnotationInSameParent":
+                case "AddReference":
+                case "DeleteReference":
+                case "ChangeReference":
+                case "MoveEntryFromOtherReference":
+                case "MoveEntryFromOtherReferenceInSameParent":
+                case "MoveEntryInSameReference":
+                case "MoveAndReplaceEntryFromOtherReference":
+                case "MoveAndReplaceEntryFromOtherReferenceInSameParent":
+                case "MoveAndReplaceEntryInSameReference":
+                case "AddReferenceResolveInfo":
+                case "DeleteReferenceResolveInfo":
+                case "ChangeReferenceResolveInfo":
+                case "AddReferenceTarget":
+                case "DeleteReferenceTarget":
+                case "ChangeReferenceTarget":
+                case "CompositeCommand":
+                {
+                    lowLevelServer.broadcastMessage(commandAsEvent(message as Command, checkedClientMetadata().participationId))    // FIXME  not correct: message to broadcast to a particular client holds sequence number for that particular participation
+                    return undefined
+                }
+                default:
+                    throw new Error(`can't handle message of kind "${message.messageKind}"`)   // TODO  instead: log an item, and fall through
+            }
+        }
+        const lowLevelServer = createWebSocketServer<Partial<ClientMetadata>, (Command | QueryMessage), (void | QueryMessage), Event>(
+            port,
+            (_) => ({}), // (leave values undefined – they're set later)
+            receiveMessageOnRepository
+        )
+        return new LionWebRepository(lowLevelServer)
+    }
+
+    async shutdown() {
+        await this.lowLevelServer.shutdown()
+    }
+
+}
+

package/src/server.ts

@@ -0,0 +1,104 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    TextualLogger,
+    textualLoggerFunctionFrom,
+    tryParseJson,
+    wrappedAsPromise
+} from "@lionweb/delta-protocol-common"
+import { asMinimalJsonString } from "@lionweb/ts-utils"
+import { IncomingMessage } from "http"
+import { WebSocketServer } from "ws"
+
+
+import { setMap } from "./set.js"
+
+
+/**
+ * Type definition for a low“-level” server that's able to broadcast messages.
+ * “Low-level” essentially means “wire protocol”, here.
+ */
+export type LowLevelServer<TBroadcastMessage> = {
+    broadcastMessage: (message: TBroadcastMessage) => Promise<void> // TODO  in general, we want to modify the message _per client_!
+    shutdown: () => Promise<void>
+}
+
+/**
+ * @return a WebSocket-driven {@link server}.
+ * @param port The port for clients to connect.
+ * @param clientMetadataFrom A function that computes metadata for a (just-)connected client from the associated {@link IncomingMessage request object}.
+ * @param receiveMessageOnServer A function that's called with the client's metadata and a received message.
+ * @param optionalTextualLogger An optional {@link TextualLogger textual logger}.
+ */
+export const createWebSocketServer = <TClientMetadata, TMessageForServer, TResponse, TBroadcastMessage>(
+    port: number,
+    clientMetadataFrom: (request: IncomingMessage) => TClientMetadata,
+    receiveMessageOnServer: (clientMetadata: TClientMetadata, message: TMessageForServer) => TResponse,
+    optionalTextualLogger?: TextualLogger
+): LowLevelServer<TBroadcastMessage> => {
+    const webSocketServer = new WebSocketServer({ port })
+    const log = textualLoggerFunctionFrom(optionalTextualLogger)
+    log("WebSocketServer started")
+    webSocketServer.on("connection", (webSocket, request) => {
+        log(`a client connected`)
+        const clientMetadata = clientMetadataFrom(request)
+        webSocket.on("message", (messageText: string) => {
+            log(`received a message from client: ${messageText}`)
+            const response = receiveMessageOnServer(clientMetadata, tryParseJson(messageText, log) as TMessageForServer)
+            if (response !== undefined) {
+                const responseText = asMinimalJsonString(response)
+                // send back to this client (only):
+                webSocket.send(responseText)    // TODO  handle error
+            }
+        })
+    })
+    return {
+        // TODO  rethink broadcasting: need to make a different message _per client_, based on its metadata (which then should include nextSequenceNumber)
+        broadcastMessage: async (message: TBroadcastMessage) => {
+            const messageText = asMinimalJsonString(message)
+            log(`broadcasting message to all clients: ${messageText}`)
+            await Promise.all(setMap(webSocketServer.clients, (client) =>
+                wrappedAsPromise((callback) => {
+                    client.send(messageText, callback)
+                })
+            ))
+        },
+        shutdown: () => {
+            log(`shutting down server`)
+            return wrappedAsPromise((callback) => {
+                webSocketServer.clients.forEach((webSocket) => {
+                    webSocket.close()
+                    process.nextTick(() => {
+                        const state = webSocket.readyState
+                        if (state === webSocket.OPEN || state === webSocket.CLOSING) {
+                            webSocket.terminate()
+                        }
+                    })
+                })
+                webSocketServer.close(callback)
+            })
+        }
+    }
+}
+
+
+/**
+ * @return the URL for a WebSocket server hosted on `localhost` on the given `port`.
+ */
+export const wsLocalhostUrl = (port: number) => `ws://localhost:${port}`
+

package/src/set.ts

@@ -0,0 +1,28 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @return an array of the mapped values of the given set.
+ */
+export const setMap = <T, R>(set: Set<T>, mapFunc: (t: T) => R): R[] => {
+    const rs: R[] = []
+    set.forEach((t) => {
+        rs.push(mapFunc(t))
+    })
+    return rs
+}
+