@usebruno/js 0.51.0 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usebruno/js",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "license": "MIT",
   "main": "src/index.js",
   "files": [
@@ -14,12 +14,12 @@
     "prepack": "npm run test"
   },
   "dependencies": {
-    "@usebruno/common": "0.25.0",
+    "@usebruno/common": "0.26.0",
     "@usebruno/query": "0.2.2",
-    "ajv": "^8.12.0",
+    "ajv": "^8.18.0",
     "ajv-formats": "^2.1.1",
     "atob": "^2.1.2",
-    "axios": "1.16.0",
+    "axios": "1.18.0",
     "btoa": "^1.2.1",
     "chai": "^4.3.7",
     "chai-string": "^1.5.0",
@@ -30,7 +30,7 @@
     "jsonwebtoken": "^9.0.3",
     "lodash": "4.18.1",
     "moment": "^2.29.4",
-    "nanoid": "3.3.8",
+    "nanoid": "3.3.18",
     "node-fetch": "^2.7.0",
     "path": "^0.12.7",
     "quickjs-emscripten": "^0.32.0",
@@ -38,7 +38,7 @@
     "uuid": "^10.0.0",
     "xml-formatter": "^3.5.0",
     "xml2js": "^0.6.2",
-    "yaml": "^2.3.4"
+    "yaml": "2.3.4"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^23.0.2",

package/src/bru.js

@@ -38,6 +38,15 @@ const SAFE_HBS_OPTIONS = new Set([
 ]);
 const variableNameRegex = /^[\w-.]*$/;
 
+const assertValidVariableName = (key) => {
+  if (variableNameRegex.test(key) === false) {
+    throw new Error(
+      `Variable name: "${key}" contains invalid characters!`
+      + ' Names must only contain alpha-numeric characters, "-", "_", "."'
+    );
+  }
+};
+
 class Bru {
   /**
    * @param {object} options - Single options object (destructured)
@@ -248,11 +257,7 @@ class Bru {
       throw new Error('Creating a env variable without specifying a name is not allowed.');
     }
 
-    if (variableNameRegex.test(key) === false) {
-      throw new Error(
-        `Variable name: "${key}" contains invalid characters! Names must only contain alpha-numeric characters, "-", "_", "."`
-      );
-    }
+    assertValidVariableName(key);
 
     // Deep-equal compare so object/array writes that mutate in place
     // (e.g. `const c = bru.getEnvVar('cfg'); c.port = 4000; bru.setEnvVar('cfg', c);`)
@@ -302,6 +307,8 @@ class Bru {
       throw new Error('Creating a env variable without specifying a name is not allowed.');
     }
 
+    assertValidVariableName(key);
+
     if (!Object.hasOwn(this.globalEnvironmentVariables, key) || !isEqual(this.globalEnvironmentVariables[key], value)) {
       this.globalEnvironmentVariables[key] = value;
       this._globalEnvDirty = true;
@@ -359,12 +366,7 @@ class Bru {
       throw new Error('Creating a variable without specifying a name is not allowed.');
     }
 
-    if (variableNameRegex.test(key) === false) {
-      throw new Error(
-        `Variable name: "${key}" contains invalid characters!`
-        + ' Names must only contain alpha-numeric characters, "-", "_", "."'
-      );
-    }
+    assertValidVariableName(key);
 
     if (!Object.hasOwn(this.runtimeVariables, key) || !isEqual(this.runtimeVariables[key], value)) {
       this.runtimeVariables[key] = value;
@@ -373,12 +375,7 @@ class Bru {
   }
 
   getVar(key) {
-    if (variableNameRegex.test(key) === false) {
-      throw new Error(
-        `Variable name: "${key}" contains invalid characters!`
-        + ' Names must only contain alpha-numeric characters, "-", "_", "."'
-      );
-    }
+    assertValidVariableName(key);
 
     return this.interpolate(this.runtimeVariables[key]);
   }
@@ -412,12 +409,7 @@ class Bru {
       throw new Error('Creating a variable without specifying a name is not allowed.');
     }
 
-    if (variableNameRegex.test(key) === false) {
-      throw new Error(
-        `Variable name: "${key}" contains invalid characters!`
-        + ' Names must only contain alpha-numeric characters, "-", "_", "."'
-      );
-    }
+    assertValidVariableName(key);
 
     if (!Object.hasOwn(this.collectionVariables, key) || !isEqual(this.collectionVariables[key], value)) {
       this.collectionVariables[key] = value;

package/src/bruno-request.js

@@ -139,6 +139,10 @@ class BrunoRequest {
     return this.req.headers;
   }
 
+  /**
+   * Replaces the whole header set, dropping headers set at collection/folder level.
+   * TODO: make this upsert instead, since setHeaders is the bulk form of setHeader.
+   */
   setHeaders(headers) {
     this.req.headers = headers;
   }

package/src/grpc/bruno-grpc-request.js

@@ -0,0 +1,52 @@
+const GrpcMetadataList = require('./grpc-metadata-list');
+const GrpcMessageList = require('./grpc-message-list');
+const GrpcMessage = require('./grpc-message');
+
+/**
+ * Reached from a hook as `bru.grpc.request`.
+ *
+ * scalar values are un-interpolated placeholders and become stale values after interpolation
+ * similar to the http workflow
+ *
+ * Keep quickjs shim up to date on any updates to this class
+ */
+class BrunoGrpcRequest {
+  #request;
+
+  /**
+   * @param {object} request - The prepared gRPC request
+   * @param {object} [options]
+   * @param {boolean} [options.metadataWritable=false] - When true, `metadata` accepts writes
+   * @param {object[]} [options.sentMessages=[]] - What the call sent, as `{ data, timestamp }`.
+   *   `messages` always answers with these, never with the messages authored in the UI — the two
+   *   differ whenever the user streams a subset of the authored messages, or none. It is therefore
+   *   empty in `beforeCallStart`, where the call has yet to send anything.
+   * @param {object} [options.message] - The single message about to be sent, as `{ data, timestamp }`.
+   *   Supplied only by `beforeMessageSend`; in the call hooks the `message` property is absent from
+   *   the model entirely, so `'message' in bru.grpc.request` is `false` there.
+   */
+  constructor(request, { metadataWritable = false, sentMessages = [], message } = {}) {
+    this.#request = request;
+    this.url = request.url;
+    this.method = request.method;
+    this.methodType = request.methodType;
+    this.authMode = request.authMode || 'none';
+    this.protoPath = request.protoPath;
+    this.name = request.name;
+    this.metadata = new GrpcMetadataList(() => this.#metadataEntries(), { writable: metadataWritable });
+    // The list clones what it is given, so a hook editing a message cannot reach what the call sent.
+    this.messages = new GrpcMessageList(sentMessages);
+    if (message) {
+      this.message = new GrpcMessage(message);
+    }
+  }
+
+  // Provides reference for in-memory edits on setters
+  #metadataEntries() {
+    this.#request.headers ??= {};
+
+    return this.#request.headers;
+  }
+}
+
+module.exports = BrunoGrpcRequest;

package/src/grpc/bruno-grpc-response.js

@@ -0,0 +1,43 @@
+const { toMetadataObject } = require('./grpc-metadata');
+const GrpcMetadataList = require('./grpc-metadata-list');
+const GrpcMessageList = require('./grpc-message-list');
+const GrpcMessage = require('./grpc-message');
+
+/**
+ * Reached from hooks as `bru.grpc.response`.
+ *
+ * `messages`, `metadata` and `trailers` are the same list types `bru.grpc.request` uses, always
+ * read-only here.
+ *
+ * Scalar values have interpolated values unlike the request counterpart.
+ * Keep quickjs shim up to date on any updates to this class
+ */
+class BrunoGrpcResponse {
+  #response;
+
+  /**
+   * @param {object} response - The call so far; complete in `afterCallEnd`, partial in `afterMessageReceive`
+   * @param {object} [options]
+   * @param {object} [options.message] - The single message just received, as `{ data, timestamp }`.
+   *   Supplied only by `afterMessageReceive`
+   */
+  constructor(response, { message } = {}) {
+    this.#response = response;
+    this.statusCode = response.statusCode;
+    this.statusText = response.statusText;
+    this.messages = new GrpcMessageList(response.messages);
+    this.metadata = new GrpcMetadataList(() => toMetadataObject(this.#response.metadata), { writable: false });
+    this.trailers = new GrpcMetadataList(() => toMetadataObject(this.#response.trailers), { writable: false });
+    this.duration = response.duration;
+
+    // Assigned conditionally, as on the request, so `afterCallEnd` has no such property at all.
+    if (message) {
+      this.message = new GrpcMessage(message);
+    }
+
+    // Deliberately a plain object, where HTTP's `BrunoResponse` returns a callable so `res('user.id')`
+    // queries the body. gRPC body (messages) will vary based on method type, so skipping here.
+  }
+}
+
+module.exports = BrunoGrpcResponse;

package/src/grpc/grpc-message-list.js

@@ -0,0 +1,74 @@
+const { cloneDeep } = require('lodash');
+
+/**
+ * GrpcMessageList — the `bru.grpc.request.messages` and `bru.grpc.response.messages` API in
+ * hooks, and the only way a hook reads gRPC messages. Read-only: both lists report what the call
+ * sent and received, so the class exposes no way to change either.
+ * Keep quickjs shim up to date on any updates to this class
+ */
+class GrpcMessageList {
+  #messages;
+
+  /**
+   * @param {object[]} [messages] - The backing messages, deep-cloned once here so a hook editing
+   *   a message cannot reach what the call actually sent or received. A list is built fresh for each
+   *   hook run, so this snapshot is never stale.
+   */
+  constructor(messages) {
+    this.#messages = cloneDeep(messages) ?? [];
+  }
+
+  /** @returns {Array} — a copy, so the snapshot cannot be edited through it */
+  all() {
+    return [...this.#messages];
+  }
+
+  /**
+   * The message at `index`. Unary and server-streaming calls have exactly one, hence the default.
+   * @param {number} [index=0]
+   * @returns {*}
+   */
+  get(index = 0) {
+    return this.all()[index];
+  }
+
+  /** @returns {number} */
+  count() {
+    return this.all().length;
+  }
+
+  /** @param {Function} fn @param {*} [context] @returns {*} */
+  find(fn, context) {
+    return this.all().find(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [context] @returns {Array} */
+  filter(fn, context) {
+    return this.all().filter(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [context] @returns {Array} */
+  map(fn, context) {
+    return this.all().map(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [context] */
+  each(fn, context) {
+    this.all().forEach(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [accumulator] @param {*} [context] @returns {*} */
+  reduce(fn, ...args) {
+    const bound = args.length > 1 ? fn.bind(args[1]) : fn;
+    const messages = this.all();
+
+    return args.length ? messages.reduce(bound, args[0]) : messages.reduce(bound);
+  }
+
+  /** @returns {Array} — same as `all()`, so `JSON.stringify` yields the messages */
+  toJSON() {
+    return this.all();
+  }
+}
+
+module.exports = GrpcMessageList;

package/src/grpc/grpc-message.js

@@ -0,0 +1,20 @@
+const { cloneDeep } = require('lodash');
+
+/**
+ * `bru.grpc.request.message` / `bru.grpc.response.message` in the message hooks — the single message
+ * being sent or received, as opposed to the `GrpcMessageList` of all of them.
+ */
+class GrpcMessage {
+  /**
+   * @param {object} [message]
+   * @param {*} [message.data] - The parsed message payload
+   * @param {number} [message.timestamp] - Epoch ms
+   */
+  constructor({ data, timestamp } = {}) {
+    // Cloned for immutability during script execution
+    this.data = cloneDeep(data);
+    this.timestamp = timestamp;
+  }
+}
+
+module.exports = GrpcMessage;

package/src/grpc/grpc-metadata-list.js

@@ -0,0 +1,214 @@
+const ReadOnlyPropertyList = require('../readonly-property-list');
+const { setMetadataKey } = require('./grpc-metadata');
+
+// Extends ReadOnlyPropertyList in dynamic mode: entries are read through the accessor (live headers) on every access.
+// Keep quickjs shim up to date on any updates to this class
+class GrpcMetadataList extends ReadOnlyPropertyList {
+  #readMetadata;
+  #writable;
+
+  /**
+   * @param {Function} readMetadata - Returns the `{ key: value }` map backing the list. A writable
+   *   list needs it to return the same live object every call, since that object is what writes edit.
+   * @param {object} [options]
+   * @param {boolean} [options.writable=false] - When false, write methods throw
+   */
+  constructor(readMetadata, { writable = false } = {}) {
+    super({
+      keyProperty: 'key',
+      valueProperty: 'value',
+      dataSource: () => Object.entries(readMetadata()).map(([key, value]) => ({ key, value }))
+    });
+    this.#readMetadata = readMetadata;
+    this.#writable = writable;
+  }
+
+  // Positional access is deliberately removed from ReadOnlyPropertyList.
+  idx = undefined;
+
+  #assertWritable(method) {
+    if (!this.#writable) {
+      throw new Error(
+        `metadata.${method}() is not available once the call has been sent — change metadata in the beforeCallStart hook`
+      );
+    }
+  }
+
+  #findKey(name) {
+    if (typeof name !== 'string') {
+      return undefined;
+    }
+
+    const target = name.toLowerCase();
+
+    return Object.keys(this.#readMetadata()).find((key) => key.toLowerCase() === target);
+  }
+
+  /**
+   * Get the value of an entry by key.
+   * @param {string} key
+   * @returns {*}
+   */
+  get(key) {
+    const match = this.#findKey(key);
+
+    return match === undefined ? undefined : this.#readMetadata()[match];
+  }
+
+  /**
+   * Get the full entry by key.
+   * @param {string} key
+   * @returns {object|undefined}
+   */
+  one(key) {
+    const match = this.#findKey(key);
+
+    return match === undefined ? undefined : { key: match, value: this.#readMetadata()[match] };
+  }
+
+  /**
+   * Check whether an entry exists, optionally matching its value too.
+   * @param {string} key
+   * @param {*} [value]
+   * @returns {boolean}
+   */
+  has(key, value) {
+    const match = this.#findKey(key);
+
+    if (match === undefined) {
+      return false;
+    }
+
+    return value === undefined || this.#readMetadata()[match] === value;
+  }
+
+  /**
+   * Get the index of an entry, by key string or by `{ key, value }`.
+   * @param {string|object} item
+   * @returns {number} -1 if not found
+   */
+  indexOf(item) {
+    const match = this.#findKey(typeof item === 'string' ? item : item?.key);
+
+    if (match === undefined) {
+      return -1;
+    }
+
+    const entries = this.all();
+
+    if (typeof item === 'string') {
+      return entries.findIndex((entry) => entry.key === match);
+    }
+
+    return entries.findIndex((entry) => entry.key === match && entry.value === item.value);
+  }
+
+  // ── Iteration overrides (optional context binding) ────────────────────
+
+  /** @param {Function} fn @param {*} [context] */
+  each(fn, context) {
+    super.each(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [context] @returns {object|undefined} */
+  find(fn, context) {
+    return super.find(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [context] @returns {Array} */
+  filter(fn, context) {
+    return super.filter(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [context] @returns {Array} */
+  map(fn, context) {
+    return super.map(context !== undefined ? fn.bind(context) : fn);
+  }
+
+  /** @param {Function} fn @param {*} [accumulator] @param {*} [context] @returns {*} */
+  reduce(fn, ...args) {
+    const bound = args.length > 1 ? fn.bind(args[1]) : fn;
+
+    return args.length ? super.reduce(bound, args[0]) : super.reduce(bound);
+  }
+
+  // ── Transform override ────────────────────────────────────────────────
+
+  /** `key: value` per line — how metadata travels as HTTP/2 headers. */
+  toString() {
+    return this.all()
+      .map((entry) => `${entry.key}: ${entry.value}`)
+      .join('\n');
+  }
+
+  // ── Write methods (edit the backing map) ──────────────────────────────
+
+  /**
+   * Insert a key, or update it in place when it already exists.
+   *
+   * @param {string} key
+   * @param {*} value
+   */
+  upsert(key, value) {
+    this.#assertWritable('upsert');
+
+    if (typeof key !== 'string' || !key.length) {
+      return;
+    }
+
+    const metadata = this.#readMetadata();
+    const existing = this.#findKey(key);
+
+    // A server reads `X-Token` and `x-token` as one key, so a re-cased upsert replaces instead of
+    // leaving two entries the transport would send as duplicates.
+    if (existing !== undefined && existing !== key) {
+      delete metadata[existing];
+    }
+
+    setMetadataKey(metadata, key, value);
+  }
+
+  /**
+   * Upsert an entry from the `{ key, value }` shape `all()` returns, so an entry read from one list
+   * can be handed straight to another.
+   *
+   * @param {object} item
+   */
+  add(item) {
+    this.#assertWritable('add');
+
+    if (!item || typeof item !== 'object') {
+      return;
+    }
+
+    this.upsert(item.key, item.value);
+  }
+
+  /**
+   * Remove the entry with the given key.
+   * @param {string} key
+   */
+  remove(key) {
+    this.#assertWritable('remove');
+
+    const existing = this.#findKey(key);
+
+    if (existing !== undefined) {
+      delete this.#readMetadata()[existing];
+    }
+  }
+
+  /** Remove every entry. */
+  clear() {
+    this.#assertWritable('clear');
+
+    const metadata = this.#readMetadata();
+
+    // Emptied in place rather than reassigned
+    for (const key of Object.keys(metadata)) {
+      delete metadata[key];
+    }
+  }
+}
+
+module.exports = GrpcMetadataList;

package/src/grpc/grpc-metadata.js

@@ -0,0 +1,21 @@
+// assigning for a reserved key like '__proto__' works with defineProperty by not polluting the object prototype.
+const setMetadataKey = (target, key, value) => {
+  Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+};
+
+/**
+ * Normalizes the `[{ name, value }]` display shape the response pane renders into a plain object.
+ * Multi-valued keys are already joined into one comma-separated string upstream.
+ */
+const toMetadataObject = (entries) => {
+  if (!Array.isArray(entries)) {
+    return {};
+  }
+
+  return entries.reduce((acc, { name, value }) => {
+    setMetadataKey(acc, name, value);
+    return acc;
+  }, {});
+};
+
+module.exports = { toMetadataObject, setMetadataKey };