Service process improvements (#137)

Signed-off-by: Jonah Iden <jonah.iden@typefox.io>

Author: jonah-iden

.editorconfig

@@ -8,6 +8,9 @@ charset = utf-8
 insert_final_newline = true
 trim_trailing_whitespace = true
 
+[*.xml]
+indent_size = 2
+
 [*.yml]
 indent_size = 2
 

.vscode/launch.json

@@ -4,6 +4,13 @@
     // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
+        {
+          "type": "node",
+          "request": "attach",
+          "name": "Attach to Service Process",
+          "port": "${input:attachPort}",
+
+        },
         {
             "type": "node",
             "request": "launch",
@@ -85,5 +92,13 @@
             "sourceMaps": true,
             "outFiles": []
         }
+    ],
+    "inputs": [
+        {
+            "id": "attachPort",
+            "type": "promptString",
+            "description": "What port should the application use for debugging?",
+            "default": "23698"
+        }
     ]
 }

packages/open-collaboration-service-process/Readme.md

@@ -0,0 +1,76 @@
+# Open Collaboration Service Process
+
+Open Collaboration Tools is a collection of open source tools, libraries and extensions for live-sharing of IDE contents, designed to boost remote teamwork with open technologies. For more information about this project, please [read the announcement](https://www.typefox.io/blog/open-collaboration-tools-announcement/).
+
+This package is a standalone Node.js application, which helps to simplify integration of OCT with non-TypeScript environments, by providing a stdin/stdout based [JSON-RPC](https://www.jsonrpc.org/) API.
+
+It takes over encryption, session lifecycle management, and includes Yjs integration for collision-free real-time editing of documents,
+so client applications do not need to implement these complex features themselves.
+
+The artifact needs to be cjs to be able to be bundled and made into an SEA because of socket.io's dynamic requires.
+
+## Usage
+
+### Starting the Service Process
+
+Start the process by either using [Node.js](https://nodejs.org) to call `process.js` or use a prebuilt executable:
+
+```sh
+node ./lib/process.js --server-address http://localhost:8100 --auth-token <your-auth-token>
+```
+
+- `--server-address` (**required**): The address of the collaboration server to connect to (e.g., `https://api.open-collab.tools`).
+- `--auth-token` (**optional**): The authentication token to use for the session, if saved by the application from a previous login
+
+### Communication Protocol
+
+All communication happens via JSON-RPC 2.0 messages over stdin/stdout.
+See [messages.ts](src/messages.ts) for service process specific awareness or lifecycle messages. Other messages follow the open-collaboration-protocol.
+
+For specific examples see `service.process.test.ts` or the [IntellIJ integration](https://github.com/eclipse-oct/oct-intellij)
+
+### Sending and Receiving Binary Data
+
+- For efficient document and file transfer, binary data is supported.
+- Use the `BinaryData` type for parameters or results that contain binary content.
+- Binary data is encoded as base64-encoded [MessagePack](https://msgpack.org/) in the `data` field of a `BinaryData` object.
+
+#### Example: Sending Binary Data
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "awareness/getDocumentContent",
+  "params": ["path/to/file"]
+}
+```
+
+The response will be:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "type": "binaryData",
+    "data": "<base64-encoded-messagepack>"
+  }
+}
+```
+
+Or sending Binary Data as a Parameter:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "fileSystem/writeFile",
+  "params": [
+    {
+      "type": "binaryData",
+      "data": "<base64-encoded-messagepack>"
+    }
+  ]
+}
+```

packages/open-collaboration-service-process/package.json

@@ -30,7 +30,7 @@
   "scripts": {
     "start": "node lib/process.js",
     "start:direct": "tsx src/process.ts",
-    "build": "esbuild ./lib/process.js --bundle --platform=node --format=esm --outfile=lib/bundle.js",
+    "build": "esbuild ./src/process.ts --bundle --platform=node --format=cjs --outfile=lib/bundle.cjs",
     "create:executable": "npm run build && shx mkdir -p bin && node --experimental-sea-config sea-config.json && node scripts/sea-build.mjs"
   },
   "dependencies": {

packages/open-collaboration-service-process/scripts/sea-build.mjs

@@ -8,7 +8,7 @@ import { inject } from 'postject'
  * The resulting executable can be run as a standalone application without the need of nodejs being installed
  */
 
-var EXECUTABLE_NAME = 'oct-servcice-process'
+var EXECUTABLE_NAME = 'oct-service-process'
 
 if (process.platform === 'win32') {
     EXECUTABLE_NAME = EXECUTABLE_NAME + '.exe'