ep_performance_test_hooks 0.0.57 → 0.0.59

package/.github/workflows/automerge.yml

@@ -24,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Automerge
         id: automerge

package/.github/workflows/backend-tests.yml

@@ -16,20 +16,20 @@ jobs:
     steps:
       -
         name: Install libreoffice
-        uses: awalsh128/cache-apt-pkgs-action@v1.6.0
+        uses: awalsh128/cache-apt-pkgs-action@v1.6.1
         with:
           packages: libreoffice libreoffice-pdfimport
           version: 1.0
       -
         name: Install etherpad core
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           repository: ether/etherpad-lite
           path: etherpad-lite
       - uses: actions/setup-node@v6
         name: Install Node.js
         with:
-          node-version: 22
+          node-version: 25
       - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
@@ -48,7 +48,7 @@ jobs:
             ${{ runner.os }}-pnpm-store-
       -
         name: Checkout plugin repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           path: plugin
       - name: Remove tests

package/.github/workflows/frontend-tests.yml

@@ -12,14 +12,14 @@ jobs:
     steps:
       -
         name: Check out Etherpad core
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           repository: ether/etherpad-lite
           path: etherpad-lite
       - uses: actions/setup-node@v6
         name: Install Node.js
         with:
-          node-version: 22
+          node-version: 25
       - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
@@ -38,7 +38,7 @@ jobs:
             ${{ runner.os }}-pnpm-store-
       -
         name: Checkout plugin repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           path: plugin
       -

package/.github/workflows/npmpublish.yml

@@ -23,12 +23,12 @@ jobs:
           # OIDC trusted publishing needs npm >= 11.5.1, which requires
           # Node >= 20.17.0. setup-node's `20` resolves to the latest
           # 20.x, which satisfies that.
-          node-version: 20
+          node-version: 25
           registry-url: https://registry.npmjs.org/
       - name: Upgrade npm to >=11.5.1 (required for trusted publishing)
         run: npm install -g npm@latest
       - name: Check out Etherpad core
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           repository: ether/etherpad-lite
       - uses: pnpm/action-setup@v6
@@ -47,7 +47,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pnpm-store-
       -
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       -

package/README.md

@@ -2,11 +2,90 @@
 
 # Performance Test Hooks for Etherpad
 
-A plugin to get test data to help improve the performance of Etherpad.
+**See exactly how long your Etherpad takes to become editable — and which assets weigh it down — straight from the browser, with no external APM.**
+
+This plugin instruments the client lifecycle: it times every Etherpad boot hook (`documentReady` → `postAceInit`) and records the load time and byte size of every resource the pad, outer frame, and inner editor request. The data is exposed as JSON at `/stats`, ready to graph, alert on, or diff between releases.
+
+## Why you'd want it
+
+- **Find the slow phase of pad load.** The boot waterfall (`etherpadHooksDuration`) shows the cost of each lifecycle stage, so you know whether time goes to the editor, the toolbar, or plugin init — not just a single opaque "load time".
+- **Catch asset bloat before users do.** Per-resource decoded/encoded/transfer sizes make it obvious when a font, locale bundle, or plugin asset balloons.
+- **Spot regressions across releases.** `/stats` is plain JSON, so you can snapshot it in CI and fail the build when boot time or payload size creeps up.
+- **No third-party APM.** Everything is collected with the browser's own `PerformanceResourceTiming` API and stays on your server.
+
+## The data
+
+Open any pad (this is what populates the metrics), then `GET /stats`. The plugin's output lives under the `ep_performance_test_hooks` key. Below is a **real response** from an Etherpad running this plugin — the values are exactly as captured; only explanatory `//` comments have been added and the `loadTimes`/`loadSizes` maps truncated (the full response carries every resource across all three frames — 49 + 49 + 46 in this capture):
+
+```jsonc
+{
+  "ep_performance_test_hooks": {
+    // Wall-clock timestamp each lifecycle hook fired
+    "etherpadHooks": {
+      "documentReady": 1781864859040,
+      "aceInitInnerdocbodyHead": 1781864859200,
+      "aceInitialized": 1781864859220,
+      "postToolbarInit": 1781864859250,
+      "postAceInit": 1781864859323
+    },
+    // The boot waterfall: ms from documentReady to each hook
+    "etherpadHooksDuration": {
+      "documentReady": 0,
+      "aceInitInnerdocbodyHead": 160,
+      "aceInitialized": 180,
+      "postToolbarInit": 210,
+      "postAceInit": 283          // editor interactive 283 ms after documentReady
+    },
+    // Per-resource timing for the main / outer / inner frames (2 of 49 shown)
+    "loadTimes": {
+      "main": {
+        "/static/css/pad.css": {
+          "redirectTime": 0, "domainLookupTime": 0, "tcpTime": 0,
+          "secureConnectionTime": "0", "responseTime": 0,
+          "fetchUntilResponseEndTime": 0,
+          "requestStartUntilResponseEndTime": 0,
+          "startUntilResponseEndTime": 0
+        }
+      }
+    },
+    // Per-resource byte sizes (2 of 49 shown)
+    "loadSizes": {
+      "main": {
+        "/static/css/pad.css":               { "decodedBodySize": 9279, "encodedBodySize": 9279, "transferSize": 0 },
+        "/static/skins/colibris/pad.css":    { "decodedBodySize": 2145, "encodedBodySize": 2145, "transferSize": 0 }
+      }
+    }
+  }
+}
+```
+
+## What's measured
+
+| Field | What it tells you |
+| --- | --- |
+| `etherpadHooks` | Wall-clock timestamp each lifecycle hook fired |
+| `etherpadHooksDuration` | Milliseconds from `documentReady` to each hook — the **boot waterfall** |
+| `loadTimes.{main,outer,inner}` | Redirect / DNS / TCP / TLS / response timings per resource, for each of the three pad frames |
+| `loadSizes.{main,outer,inner}` | `decodedBodySize` / `encodedBodySize` / `transferSize` per resource |
+| `performance` | The page's `navigation` PerformanceEntry |
 
 ## Usage
 
-See the collected stats at ``/stats``
+The plugin only emits data — render or alert on it however you like. For example, fail CI if the editor takes too long to become interactive:
+
+```sh
+curl -s http://localhost:9001/stats \
+  | jq '.ep_performance_test_hooks.etherpadHooksDuration.postAceInit'   # -> 283
+```
+
+…or find your heaviest assets:
+
+```sh
+curl -s http://localhost:9001/stats \
+  | jq -r '.ep_performance_test_hooks.loadSizes.main
+           | to_entries | sort_by(-.value.decodedBodySize)[:10][]
+           | "\(.value.decodedBodySize)\t\(.key)"'
+```
 
 ## Installation
 

package/package.json

@@ -39,7 +39,7 @@
     "type": "git",
     "url": "git+https://github.com/ether/ep_performance_test_hooks.git"
   },
-  "version": "0.0.57",
+  "version": "0.0.59",
   "devDependencies": {
     "eslint": "^8.57.1",
     "eslint-config-etherpad": "^4.0.5",

package/static/js/performance.js

@@ -5,22 +5,29 @@
 // was false, it was only when minify was set to true that I needed to do this hack.
 // CRITICAL TODO: This causes a global leak which causes the tests to fail.
 
+// Lazily get (and create) the shared namespace. `documentReady` only fires on the
+// pad page (pad.html), never in the timeslider bootstrap, so hooks that also fire in
+// the timeslider (postToolbarInit, postTimesliderInit) used to throw
+// `TypeError: Cannot set properties of undefined` there. Those uncaught errors
+// surfaced as error toasts and broke core's timeslider specs. Ensuring the namespace
+// exists makes every hook safe regardless of which page fired it.
+const hooks = () => (window.top.etherpadHooks = window.top.etherpadHooks || {});
+
 exports.documentReady = () => {
-  window.top.etherpadHooks = {};
-  window.top.etherpadHooks.documentReady = Date.now();
+  hooks().documentReady = Date.now();
 };
-exports.aceAttribClasses = () => window.top.etherpadHooks.aceAttribClasses = Date.now();
-exports.aceEditorCSS = () => window.top.etherpadHooks.aceEditorCSS = Date.now();
+exports.aceAttribClasses = () => hooks().aceAttribClasses = Date.now();
+exports.aceEditorCSS = () => hooks().aceEditorCSS = Date.now();
 exports.aceInitInnerdocbodyHead =
-    () => window.top.etherpadHooks.aceInitInnerdocbodyHead = Date.now();
-exports.aceInitialized = () => window.top.etherpadHooks.aceInitialized = Date.now();
-exports.postToolbarInit = () => window.top.etherpadHooks.postToolbarInit = Date.now();
-exports.postTimesliderInit = () => window.top.etherpadHooks.postTimesliderInit = Date.now();
+    () => hooks().aceInitInnerdocbodyHead = Date.now();
+exports.aceInitialized = () => hooks().aceInitialized = Date.now();
+exports.postToolbarInit = () => hooks().postToolbarInit = Date.now();
+exports.postTimesliderInit = () => hooks().postTimesliderInit = Date.now();
 
 exports.postAceInit = () => {
-  window.top.etherpadHooks.postAceInit = Date.now();
+  hooks().postAceInit = Date.now();
   const perf = {};
-  perf.etherpadHooks = window.top.etherpadHooks;
+  perf.etherpadHooks = hooks();
   perf.etherpadHooksDuration = {};
 
   // Takes previous hook times and stores a duration