caldera

Author: 1rgs

.eslintignore

@@ -0,0 +1 @@
+src/generated/*.js

.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  parser: "@typescript-eslint/parser",
+  extends: [
+    "react-app",
+    "prettier/@typescript-eslint",
+    "plugin:prettier/recommended"
+  ],
+  parserOptions: {
+    ecmaVersion: 2019,
+    sourceType: "module",
+    ecmaFeatures: {
+      jsx: true
+    }
+  },
+  settings: {
+    react: {
+      version: "detect"
+    }
+  }
+};

.gitignore

@@ -0,0 +1,5 @@
+dist/
+public/
+node_modules/
+.DS_Store
+db/

.prettierrc

@@ -0,0 +1 @@
+{ "tabWidth": 2, "singleQuote": false }

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "editor.formatOnSave": true,
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "eslint.enable": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    { "language": "typescript", "autoFix": true },
+    { "language": "typescriptreact", "autoFix": true }
+  ],
+  "eslint.autoFixOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  }
+}

docs/architecture.md

@@ -0,0 +1,11 @@
+# Caldera server architecture
+
+Caldera is a custom React renderer built on top of the React Reconciler API. Instead of mutating a real DOM stored on the server, it sends the mutations over WebSockets to a client which performs them on the real DOM. I haven't benchmarked the current renderer, but it maintains essentially the same amount of state as a simple no-op renderer and was able to run 250000 concurrent instances (all running timers) in 1.7GB of real heap. This should make it reasonably safe to maintain disconnected instances in memory for a non-trivial amount of time, and is way cheaper than maintaining a real DOM (JSDOM, undom, or similar) on top of the React virtual dom.
+
+## Philosophy
+
+In one sentence: maintain as little non-React state on the server as possible. This means:
+
+1. All component state should be in the React tree - this means all inputs are controlled (https://reactjs.org/docs/forms.html)
+2. Don't maintain any tree - the virtual dom already contains everything necessary for operation
+3. Punt serialization/hydration as far back as possible - because Fiber instances are really cheap, disconnected sessions can be maintained for quite a while.

docs/event-propagation.md

@@ -0,0 +1,24 @@
+# Event propagation
+
+React exposes an event abstraction which includes a feature subset of the real DOM event system. The constraints are namely:
+
+- At most one listener for an event type is registered for any given node
+- Event propagation bubbles _up_ the tree and doesn't _capture_ down the tree (to do capture, pass in stuff like onClickCapture - this is uncommonly used and we don't need to support right now but the method is similar)
+
+To support this abstraction on the server without a real DOM while avoiding the n+1 problem, the propagation path to walk is handled on the client (we will deal with validation later, but this is unlikely to pose a security issue). This works as follows:
+
+1. When a callback is registered, preventDefault if the event is _cancelable_ but do not stopPropagation. Ignore and stopPropagation if isTrusted is not true.
+2. When an event is dispatched, store the current node ID at each callback handler when hit in an array (single element if `event.bubbles` is false). Send the contents of that array over RPC when the event hits `document.body`, along with the node ID of the original target element.
+3. On the server, we walk up the callbacks of the corresponding server node instances until stopPropagation is called. When stopPropagation is called or all nodes in the list are processed, if preventDefault was not called and the original event was _cancelable_ we send a virtual event dispatch message to the client, and the client permits the side-effect but stops propagation (as detailed in step 1).
+
+Ideally we would be able to implement a useful subset of the [SyntheticEvent](https://reactjs.org/docs/events.html) wrapper.
+
+## Cancelabiity
+
+- Non-trusted DOM events (save for `click`) don't cause default side-effects when dispatched. We work around this by supporting only a subset of cancellable events that have a corresponding redispatch method (currently submit, focus, blur, click). React Flare is relying on a similar type of async cancellation/default preventDefaulted, so it's worth investigating their implementation (https://github.com/facebook/react/issues/15257)
+
+## Potential validation methods
+
+- Use some ID generation scheme that lets you easily check if a node is a child of another node (harder)
+- Pass reference to instance up the tree with registered callback (easier, but updating this may be harder)
+- Walk React Fiber instance parent references (slow, may need to walk entire app tree per event process, but updating is handled automatically)