@keepsnappy/agent 0.0.0-stage → 0.1.0-alpha.11

package/maestro/perflab/send-markers.js

@@ -0,0 +1,124 @@
+// Posts the step markers step.js recorded during the iteration, after it ended (end-run.yaml), so sending them never
+// changes the test's pace. Farm mode only: POST <api>/v1/markers with the marker's own run token as Bearer (local mode
+// posts at once from step.js). ES5 only (older Maestro builds run Rhino). Must not throw.
+// One request per token carries all its markers ({markers: [...]}, at most 500 each), so a long journey stays far
+// under the API's per-run rate limit; a request that fails on the network, 429 or 5xx is tried 3 times (Retry-After
+// honoured, else 1 s then 2 s). An API from before batches answers 400 without per-item results: the markers then go
+// one by one, as they used to.
+// Clock round trips (plan 51 G1.4): each answer carries the API's receive/send times; that trip rides with the next
+// request of the same token, and what is left goes to <api>/v1/clock at the end, as a short chain of CLOCK_PROBES
+// requests whose answers are trips too, so a token still reports several round trips although its markers now go in
+// one request. A trip whose POST failed or came back without a clock (an older API) stays pending, so nothing
+// measured is dropped.
+try {
+  var g = typeof globalThis !== 'undefined' ? globalThis : this;
+  var pick = function (name, dflt) {
+    var modern = name.replace(/^PERFLAB_/, 'KEEPSNAPPY_');
+    var names = modern === name ? [name, 'MAESTRO_' + name] : [modern, 'MAESTRO_' + modern, name, 'MAESTRO_' + name];
+    for (var i = 0; i < names.length; i++) {
+      var v = g[names[i]];
+      if (typeof v === 'string' && (v !== '' || names[i].indexOf('KEEPSNAPPY_') >= 0)) return v;
+    }
+    return dflt;
+  };
+  var MAX_SAMPLES = 16;
+  var PER_REQUEST = 500;
+  var TRIES = 3;
+  var RETRY_CAP_MS = 30000;
+  var CLOCK_PROBES = 4;
+  var out = typeof output !== 'undefined' && output ? output : {};
+  var list = out.perflabMarkers || [];
+  out.perflabMarkers = [];
+  var api = pick('PERFLAB_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '').replace(/\/+$/, '');
+  var wait = function (ms) {
+    try {
+      java.lang.Thread.sleep(ms);
+      return;
+    } catch (e0) {
+      // no Java bridge: wait on the clock
+    }
+    var until = Date.now() + ms;
+    while (Date.now() < until) {
+      // nothing
+    }
+  };
+  var header = function (res, name) {
+    var h = res && res.headers;
+    if (!h) return null;
+    var v = h[name] !== undefined ? h[name] : h[name.toLowerCase()];
+    return v === undefined || v === null ? null : String(v);
+  };
+  // One POST: the answer's status and parsed body, the clock trip when the answer has one; null when it threw.
+  var postOnce = function (path, token, body) {
+    var t0 = Date.now();
+    var res = http.post(api + path, {
+      headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + token },
+      body: JSON.stringify(body),
+    });
+    var t3 = Date.now();
+    var parsed = null;
+    try {
+      parsed = res && res.body ? JSON.parse(res.body) : null;
+    } catch (e1) {
+      // not JSON
+    }
+    var c = parsed ? parsed.clock : null;
+    var trip = c && typeof c.recv_ms === 'number' && typeof c.send_ms === 'number' ? { t0: t0, t1: c.recv_ms, t2: c.send_ms, t3: t3 } : null;
+    return { status: res && typeof res.status === 'number' ? res.status : null, body: parsed, trip: trip, retryAfter: Number(header(res, 'Retry-After')) };
+  };
+  var postRetry = function (path, token, body) {
+    var a = null;
+    for (var attempt = 0; attempt < TRIES; attempt++) {
+      if (attempt > 0) wait(Math.min(a && a.retryAfter > 0 ? a.retryAfter * 1000 : 1000 * Math.pow(2, attempt - 1), RETRY_CAP_MS));
+      try {
+        a = postOnce(path, token, body);
+      } catch (e2) {
+        a = null;
+      }
+      if (a && a.status !== 429 && !(a.status >= 500)) return a;
+    }
+    return a;
+  };
+  var pending = {};
+  var tokens = [];
+  var byToken = {};
+  for (var k = 0; k < list.length && api !== ''; k++) {
+    var m = list[k];
+    if (!m || typeof m.token !== 'string' || m.token === '') continue;
+    if (!byToken[m.token]) {
+      byToken[m.token] = [];
+      pending[m.token] = [];
+      tokens.push(m.token);
+    }
+    byToken[m.token].push({ step: m.step, phase: m.phase, t_host: m.t_host });
+  }
+  var send = function (token, body) {
+    if (pending[token].length) body.clock = pending[token].slice(-MAX_SAMPLES);
+    var a = postRetry('/v1/markers', token, body);
+    if (a && a.trip) pending[token] = [a.trip];
+    return a;
+  };
+  for (var t = 0; t < tokens.length; t++) {
+    var mine = byToken[tokens[t]];
+    for (var i = 0; i < mine.length; i += PER_REQUEST) {
+      var chunk = mine.slice(i, i + PER_REQUEST);
+      var a = send(tokens[t], { markers: chunk });
+      if (!a || a.status !== 400 || (a.body && a.body.results)) continue;
+      for (var j = 0; j < chunk.length; j++) send(tokens[t], chunk[j]);
+    }
+  }
+  for (var p = 0; p < tokens.length; p++) {
+    for (var n = 0; n < CLOCK_PROBES && pending[tokens[p]].length; n++) {
+      try {
+        var probe = postOnce('/v1/clock', tokens[p], { source: 'host', samples: pending[tokens[p]].slice(-MAX_SAMPLES) });
+        if (!probe.trip) break;
+        pending[tokens[p]] = [probe.trip];
+      } catch (e3) {
+        // an older API has no /v1/clock
+        break;
+      }
+    }
+  }
+} catch (e) {
+  // swallowed on purpose
+}

package/maestro/perflab/step.js

@@ -0,0 +1,39 @@
+// Declared step marker. Runs on the Maestro HOST, so it never touches the device. ES5 only (older Maestro builds run
+// Rhino). Must not throw: a marker is never a test failure.
+// Inputs: STEP, PHASE (from step.yaml). t_host is taken now, when the action happens, whenever the marker is sent.
+// Farm mode (`perflab farm open`): the flow has set `output.perflabToken` (one run token per iteration, from the
+// generated tokens.js) and the API base comes from `output.perflabApi` or PERFLAB_API_URL. The marker is only recorded
+// in the flow's memory; send-markers.js (end-run.yaml) posts the iteration's markers to <api>/v1/markers after it
+// ended, so the test never waits on the network between actions.
+// Local mode (`perflab run` / `measure`): PERFLAB_MARKER_URL, PERFLAB_RUN_ID point at the CLI's own endpoint on this
+// host, posted at once (local flows have no end-run step). Maestro only forwards host env vars with the MAESTRO_ prefix,
+// unprefixed, so both spellings are read (docs/research/28).
+try {
+  var g = typeof globalThis !== 'undefined' ? globalThis : this;
+  var pick = function (name, dflt) {
+    var modern = name.replace(/^PERFLAB_/, 'KEEPSNAPPY_');
+    var names = modern === name ? [name, 'MAESTRO_' + name] : [modern, 'MAESTRO_' + modern, name, 'MAESTRO_' + name];
+    for (var i = 0; i < names.length; i++) {
+      var v = g[names[i]];
+      if (typeof v === 'string' && (v !== '' || names[i].indexOf('KEEPSNAPPY_') >= 0)) return v;
+    }
+    return dflt;
+  };
+  var out = typeof output !== 'undefined' && output ? output : {};
+  var step = pick('STEP', '');
+  var phase = pick('PHASE', '');
+  var token = typeof out.perflabToken === 'string' ? out.perflabToken : '';
+  var api = pick('PERFLAB_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '');
+  if (token !== '' && api !== '') {
+    out.perflabMarkers = out.perflabMarkers || [];
+    out.perflabMarkers.push({ token: token, step: step, phase: phase, t_host: Date.now() });
+  } else {
+    var base = pick('PERFLAB_MARKER_URL', 'http://127.0.0.1:47321');
+    http.post(base + '/marker', {
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ run: pick('PERFLAB_RUN_ID', ''), step: step, phase: phase, t_host: Date.now() }),
+    });
+  }
+} catch (e) {
+  // swallowed on purpose
+}

package/maestro/perflab/step.yaml

@@ -0,0 +1,11 @@
+# PerfLab step marker. Call with env STEP (name) and PHASE (start|end):
+#   - runFlow: { file: perflab/step.yaml, env: { STEP: chat.open, PHASE: start } }
+# Never fails the surrounding flow, even when no PerfLab CLI is listening. On the farm it only records the marker:
+# run send-markers.js at the end of each iteration (examples/farm/flows/perflab/end-run.yaml).
+appId: any
+---
+- runScript:
+    file: step.js
+    env:
+      STEP: ${STEP}
+      PHASE: ${PHASE}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@keepsnappy/agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.11",
+  "description": "KeepSnappy CLI: runs your app journeys, measures from inside the app and reports More work / Less work / No change per step.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arekkubaczkowski/keepsnappy.git",
+    "directory": "apps/agent"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "keepsnappy": "dist/keepsnappy.js",
+    "perflab": "dist/keepsnappy.js"
+  },
+  "files": [
+    "dist",
+    "maestro",
+    "examples",
+    "README.md"
+  ]
+}