websocket-text-relay 1.0.0 → 1.1.0

package/README.md

@@ -1,40 +1,41 @@
 # websocket-text-relay (WTR)
 
-## Alpha
-
-Note: This tool is still in alpha state. Some features like the VsCode extension and vite plugin have not been published yet. Documentation is still a work in progress
-
 This application connects to your text editor using the Language Server Protocol (LSP) and then starts a websocket
 server that front end clients can connect to and subscribe to file change events. This allows users to see their
 front end changes evaluated immediately as they type, without having to first save the file to disk or reload the browser.
 It's a similar concept to sites like CodePen and JsFiddle, except you can develop locally using your own text editor with all
 of your personalized plugins instead of having to use an in browser code editor.
 
+## Alpha
+
+Note: This tool is still in alpha state. Some features like the VsCode extension have not been published yet. Documentation is still a work in progress
+
 ## Usage
 
 ### 1. Install the extension for your text editor
 
 WTR currently has plugins for Neovim and VSCode.
-    * Installation instructions for Neovim
-    * Installation instructions for VSCode
+ - [websocket-text-relay.nvim](https://github.com/niels4/websocket-text-relay.nvim)
+ - VSCode extension coming soon!
 
-If you wish to create a plugin for a new editor, the process is fairly straight forward if the editor has
-LSP support. See the [developer guide to creating a WTR text editor plugin](./docs/creating-text-editor-plugin.md)
+### 2. Verify the webserver is running with the status UI
 
-### 2. Connect to the websocket server from the front end application
+The websocket server hosts its own status UI on the same port as the websocket server. You can view
+the status UI and verify everything is running by first starting up your text editor and then opening your browser to [http://localhost:38378](http://localhost:38378)
+
+### 3. Connect to the websocket server from the front end application
 
 To use this on a professional level project that gives you the option to use modules, typescript, and react, I recommend using vite along with
-the plugin **vite-plugin-websocket-text-relay**. This plugin gives you all the power of vite when developing while also hooking
+the plugin [vite-plugin-websocket-text-relay](https://github.com/niels4/vite-plugin-websocket-text-relay). This plugin gives you all the power of vite when developing while also hooking
 the live text updates into Vite's hot module reload system.
 
 If you want to use this as a learning tool to play around with UI concepts using simple projects involving 1 html, css, and javascript file,
-then check out this **Simple WTR reference project**. This is a great setup for following along with any short and focused web development tutorials.
+then check out this [simple reference project](https://github.com/niels4/wtr-simple-example). This is a great setup for following along with any short and focused web development tutorials.
 
-And finally, the [status UI for this project](http://localhost:38378) was also created using live updates from websocket-text-relay.
+And finally, the status UI for this project was also created using live updates from websocket-text-relay.
 In addition to giving you live feedback on the status and activity of the application, it is also meant to serve as a
 reference UI project that is more complicated than a single javascript file, but still doesn't use any external dependencies.
 
-
 ## Developing
 
 If you are a developer looking to run websocket-text-relay from source and make modifications, follow the [Developer Getting Started Guide](./docs/dev-getting-started.md)

package/changelog.md

@@ -0,0 +1,25 @@
+## 1.1.0 - 2024/04/07
+
+Increased default security.
+
+By default, the http and websocket server will only accept incoming connections from your local machine. If you
+wish to allow network access you must set the `allow_network_access` option to true when configuring your editor plugin.
+
+### For Neovim clients
+
+```lua
+  { 'niels4/websocket-text-relay.nvim', opts = {
+      allow_network_access = true
+  }},
+```
+
+By default, the http and websocket server will only accept connections where the hostname is `localhost`. If you wish
+to allow other hosts to connect to the websocket server, you must explicitly allow them using the `allowed_hosts` option when configuring your editor plugin.
+
+### For Neovim clients
+
+```lua
+  { 'niels4/websocket-text-relay.nvim', opts = {
+      allowed_hosts = { "some-allowed-host.test", "some-other-host.test" },
+  }},
+```

package/docs/code-structure.md

@@ -75,3 +75,50 @@ to start the http server will be the new main server, the rest of the instances
 proceed to connect to the new server in client mode again.
 
 All init messages are resent when a websocket client reconnects.
+
+## Status UI
+
+The HTTP server created in `src/websocket-interface/httpServer.js` is also used to host the static files that make up the status UI.
+
+The root of the static site is the `src/ui` directory.
+
+### index.html
+
+The UI is entirely made up of SVG elements, so the only thing the index.html file has to do is set up the root
+SVG element with some groups to act as containers for the different components to use.
+
+### js/index.js
+
+ - Sets up the websocket-text-relay client with handlers for css and javascript files.
+ - initializes the simple dependency management system that allows the UI to be split into several javascript files.
+ - Hooks up events to handle resizing the SVG element on window resize.
+ - emit data and activity events that the UI components can hook into
+
+Whenever a javascript file is edited, its exports are updated and the main.js file is rerun.
+
+### js/util/DependencyManager.js
+
+This is a very quick and simple dependency management system. The dependency container is just an object in the global scope.
+An exportDeps function is created to make it easy to specify which objects in scope are to be exported.
+
+An onEvent function is also created and exported here, it prevents event leaks by cleaning up any registered event handlers whenever the javascript is reevaluated.
+
+### js/util/drawing.js
+
+This is the base utility class for drawing different shapes in SVG. It contains functions to help with drawing
+wedges and other shapes using polar coordinates.
+
+When dealing with polar coordinates, instead of angles being from 0 to 2 * PI, 
+the angle is scaled from 0 to 1, angles 0 and 1 pointing down the positive direciton of the x axis. 0.25 points straight up, 0.5 straight left and 0.75 straight down.
+
+The center of the UI is at (0, 0) with a minimum height and width of 2. Having a good understanding of the unit circle makes dealing with polar coordinates fairly simple.
+
+### js/components/
+
+The components directory contains the javascript classes that render the different elements on the screen.
+
+Each class handles the state for its component and has a draw function that renders it to the screen.
+
+Any components affected by data updates will also have an update function. When called the component will update the elements it manages with the new data.
+
+Some components also respond to text update activity, these components will have a triggerActivity function as well.

package/docs/dev-getting-started.md

@@ -1,8 +1,64 @@
 # Developers Guide: Getting Started
 
-Placeholder for instructions on how to:
-    * check out repo
-    * run tests
-    * point your text editor plugin to use your checked out code
-    * run the chrome debugger and set breakpoints
-    * understanding the code structure
+In this tutorial you will learn how to:
+ - Check out the repo and run unit tests
+ - Configure your editor to run the language server from local source
+ - Start in debugging mode and use the chrome inspector to set breakpoints and step through code
+ - Live edit the status UI
+
+## Check out the repo
+
+In this example we will be checking out the repo into the `~/dev/src` directory.
+
+```
+mkdir -p ~/dev/src
+cd ~/dev/src
+git clone https://github.com/niels4/websocket-text-relay.git
+cd websocket-text-relay
+npm install
+npm test
+```
+
+## Configure your editor
+
+### Neovim
+
+You can override the command to start up the language server using the setup options.
+
+```lua
+
+local home_dir = vim.fn.resolve(os.getenv("HOME"))
+
+require('lazy').setup {
+
+  { 'niels4/websocket-text-relay.nvim', opts = {
+    cmd = { "node", "--inspect",  home_dir .. "/dev/src/websocket-text-relay/start.js" }
+  }}
+
+}
+
+```
+
+If you wish to pause the language server on startup so you can set break points on the init functions,
+you should use the `--inspect-brk` option instead. You will need to open the chrome debugger and choose
+to continue the execution before the language server will start up if you choose this option.
+
+```lua
+    cmd = { "node", "--inspect-brk",  home_dir .. "/dev/src/websocket-text-relay/start.js" }
+```
+
+## Edit Status UI
+
+With the language server running, you can connect to the status UI by opening your browser to [http://localhost:38378](http://localhost:38378)
+
+You should be able to see at least 1 editor and 1 client (the status UI itself)
+
+The UI was built using websocket-text-relay, so we can live edit the UI as its running.
+
+Open up the file `src/ui/js/util/constants.js`. Make changes to the outer and inner ring radius variables. You should see the UI update as you make changes.
+
+You can do the same with the main.css file. Try changing around some of the colors.
+
+## Understanding the code structure
+
+To effectively make any changes to the application, you will need to understand the [overall code structure](./code-structure.md)

package/index.js

@@ -34,6 +34,7 @@ const lspInitializeResponse = {
 
 export const startLanguageServer = (options = {}) => {
   const {inputStream: inputStreamParam, outputStream: outputStreamParam, port: portParam} = options
+
   const jsonRpc = new JsonRpcInterface(resolveIoStreams({inputStreamParam, outputStreamParam}))
 
   const wsInterface = new WebsocketInterface({port: resolvePort(portParam)})
@@ -52,6 +53,10 @@ export const startLanguageServer = (options = {}) => {
       lsPid: process.pid
     }
 
+    const initOptions = params.initializationOptions || {}
+    wsInterface.setAllowedHosts(initOptions.allowedHosts)
+    wsInterface.setAllowNetworkAccess(initOptions.allowNetworkAccess)
+    wsInterface.startInterface()
     wsInterface.sendInitMessage(wsInitMessage)
 
     return lspInitializeResponse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "websocket-text-relay",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "An LSP server for sending live file updates from your text editor to the front end via websockets.",
   "bin": {
     "websocket-text-relay": "./start.js"

package/src/ui/js/index.js

@@ -3,8 +3,6 @@ import "./util/DependencyManager.js"
 
 const { cleanupEventHandlers, statusDataEmitter } = window.__WTR__
 
-const PORT = 38378
-
 const FILE_PREFIX = "websocket-text-relay/src/ui/"
 const CSS_FILE = "css/main.css"
 const cssEndsWith = FILE_PREFIX + CSS_FILE
@@ -28,7 +26,9 @@ const jsFiles = [
 const svgRoot = document.getElementById('svg_root')
 const cssElement = document.getElementById('main_style')
 
-const ws = new WebsocketClient({port: PORT})
+const {hostname, port, protocol} = window.location
+const wsProtocol = protocol === "http:" ? "ws" : "wss"
+const ws = new WebsocketClient({port: port, host: hostname, protocol: wsProtocol})
 
 const handleCss = (contents) => {
   cssElement.innerText = contents
@@ -94,7 +94,7 @@ const subscribeWatchers = () => {
   ws.sendMessage({method: "watch-log-messages"})
   ws.sendMessage({method: "watch-wtr-status"})
   ws.sendMessage({method: "watch-wtr-activity"})
-  ws.sendMessage({ method: "init", name: "beta-status-ui" })
+  ws.sendMessage({ method: "init", name: "status-ui" })
   ws.sendMessage({ method: "watch-file", endsWith: cssEndsWith })
   jsFiles.forEach((jsFile) => {
     const jsEndsWith = FILE_PREFIX + jsFile

package/src/websocket-interface/WebsocketInterface.js

@@ -14,11 +14,10 @@ export class WebsocketInterface {
     this.openFileListMessage = null
     this.serverSession = null
     this.wsClient = null
+    this.allowNetworkAccess = false
 
     this._onSocketClose = this._onSocketClose.bind(this)
     this._sendQueuedMessages = this._sendQueuedMessages.bind(this)
-
-    this._startInterface()
   }
 
   sendInitMessage (initMessage) {
@@ -36,9 +35,19 @@ export class WebsocketInterface {
     this._sendMessageToServer(sendTextMessage)
   }
 
-  async _startInterface () {
+  setAllowedHosts (allowedHostsList) {
+    this.allowedHosts = new Set(allowedHostsList)
+  }
+
+  setAllowNetworkAccess (allowNetworkAccessParam) {
+    if (allowNetworkAccessParam != null) {
+      this.allowNetworkAccess = allowNetworkAccessParam
+    }
+  }
+
+  async startInterface () {
     try {
-      await createWebsocketServer(this.port)
+      await createWebsocketServer({port: this.port, allowedHosts: this.allowedHosts, allowNetworkAccess: this.allowNetworkAccess })
       this.serverSession = new WtrSession({apiMethods, wsInterfaceEmitter: this.emitter})
       this._sendQueuedMessages()
     } catch (e) {
@@ -52,7 +61,7 @@ export class WebsocketInterface {
     this.wsClient.socket.removeEventListener("close", this._onSocketClose)
     this.wsClient.socket.removeEventListener("open", this._sendQueuedMessages)
     this.wsClient = null
-    this._startInterface()
+    this.startInterface()
   }
 
   _sendQueuedMessages () {

package/src/websocket-interface/httpServer.js

@@ -2,6 +2,7 @@ import { createServer } from 'node:http'
 import path from 'node:path'
 import fs from 'node:fs'
 import * as url from 'node:url'
+import { isValidOrigin } from './util.js'
 const parentDir = url.fileURLToPath(new URL('..', import.meta.url))
 
 const uiDirName = "ui"
@@ -27,7 +28,12 @@ const getFileType = (fileUrl) => {
   return fileUrl.substring(lastDotIndex + 1)
 }
 
-const requestHandler = (req, res) => {
+const requestHandler = (allowedHosts) => (req, res) => {
+  if (!isValidOrigin(allowedHosts, req)) {
+    res.writeHead(403)
+    res.end("FORBIDDEN!")
+    return
+  }
   const filePath = getFilePath(req.url)
   const fileType = getFileType(filePath)
   const contentType = allowedFileTypes.get(fileType)
@@ -42,16 +48,18 @@ const requestHandler = (req, res) => {
   fileStream.pipe(res)
 }
 
-export const createHttpServer = (port) => {
+export const createHttpServer = ({port, allowedHosts, allowNetworkAccess}) => {
   return new Promise((resolve, reject) => {
     
-    const server = createServer(requestHandler)
+    const server = createServer(requestHandler(allowedHosts))
 
     server.on("error", (e) => {
       reject(e)
     })
 
-    server.listen(port, () => {
+    const listenAddress = allowNetworkAccess ? "0.0.0.0" : "127.0.0.1"
+
+    server.listen(port, listenAddress, () => {
       resolve(server)
     })
   })

package/src/websocket-interface/util.js

@@ -10,3 +10,19 @@ export const debounce = (timeout, func) => {
 // first ID returned is 0 and increases every time function is called
 let currentId = 0
 export const getNextId = () => currentId++
+
+const defaultAllowedHost = "localhost"
+
+export const isValidOrigin = (allowedHosts, req) => {
+  const {host, origin} = req.headers
+  let hostname
+
+  if (origin == null || origin.length === 0) {
+    hostname = host.split(":")[0]
+  } else {
+    const url = new URL(origin)
+    hostname = url.hostname
+  }
+
+  return hostname === defaultAllowedHost || allowedHosts.has(hostname)
+}

package/src/websocket-interface/websocketServer.js

@@ -2,15 +2,20 @@ import { WebSocketServer } from 'ws'
 import { createHttpServer } from "./httpServer.js"
 import { apiMethods } from "./websocketApi.js"
 import { WtrSession } from './WtrSession.js'
+import { isValidOrigin } from './util.js'
 
-export const createWebsocketServer = async (port) => {
-  const httpServer = await createHttpServer(port) // promise will reject if can't start HTTP server on specified port
+export const createWebsocketServer = async ({port, allowedHosts, allowNetworkAccess}) => {
+  const httpServer = await createHttpServer({port, allowedHosts, allowNetworkAccess}) // promise will reject if can't start HTTP server on specified port
 
   const websocketServer = new WebSocketServer({ server: httpServer })
   
   websocketServer.on('error', () =>  { })
 
-  websocketServer.on('connection', (wsConnection) => {
+  websocketServer.on('connection', (wsConnection, request) => {
+    if (!isValidOrigin(allowedHosts, request)) {
+      wsConnection.close()
+      return
+    }
     new WtrSession({apiMethods, wsConnection})
   })