Scope-sharing capabilities for multi-protocol collections (#1101)

* WIP: feat: Scope sharing capabilities for multi-protocol collections

* Handle for response type based response class getter

* Add sanitization for execution.event for backwards compatibility

* Pass forward responseType for nested executions

* Support init options with createContext

Accepts template value and boolean for disableLegacyAPIs

* Update received template object + Its handling

* fix: Incorrect target for initializing execution

* Add support for templates as map

* fix: getProtocolMetadata not utilized

* fix: Incorrect target property for execution class

* Have disableLegacyAPIs as a picked param

* Update tests

* Make the logic to get protocol name from target more future-safe

* Add tests for multiple templates and chai plugin

* fix: templateName to be passed by consumer for any custom handling

* Add both `template` and `templates` option for init

* Add changelog

* Add templateName as a parameter to sandbox.execute args

* Streamline sandbox scope sharing capabilities

* test: Error dispatched as expected for execution without a templateName param

* Update tests + execute api

* Refactor execute block

Author: deve-sh

CHANGELOG.yaml

@@ -1,3 +1,8 @@
+unreleased:
+  new features:
+    - GH-1101 Add support for multiple item-type templates and explicitly passed
+       chai plugin in one sandbox instance
+
 6.3.0:
   date: 2025-12-01
   new features:

lib/index.js

@@ -1,7 +1,9 @@
 const _ = require('lodash'),
     bootcode = require('./bootcode'),
     PostmanSandbox = require('./postman-sandbox'),
-    PostmanSandboxFleet = require('./postman-sandbox-fleet');
+    PostmanSandboxFleet = require('./postman-sandbox-fleet'),
+
+    INIT_OPTIONS_AVAILABLE = ['disableLegacyAPIs', 'disabledAPIs', 'template', 'templates', 'chaiPlugin'];
 
 module.exports = {
     /**
@@ -16,14 +18,16 @@ module.exports = {
             options = {};
         }
 
-        options = _.clone(options);
+        const initOptions = _.pick(options, INIT_OPTIONS_AVAILABLE),
+            connectOptions = _.omit(options, INIT_OPTIONS_AVAILABLE);
+
         bootcode((err, code) => {
             if (err) { return callback(err); }
             if (!code) { return callback(new Error('sandbox: bootcode missing!')); }
 
-            options.bootCode = code; // assign the code in options
+            connectOptions.bootCode = code; // assign the code in connect options
 
-            new PostmanSandbox().initialize({}, options, callback);
+            new PostmanSandbox().initialize(initOptions, connectOptions, callback);
         });
     },
 

lib/postman-sandbox.js

@@ -71,6 +71,7 @@ class PostmanSandbox extends UniversalVM {
      * @param {Number} options.timeout -
      * @param {Object} options.cursor -
      * @param {Object} options.context -
+     * @param {String} options.templateName -
      * @param {Boolean} options.serializeLogs -
      * @param {Function} callback -
      */
@@ -98,6 +99,7 @@ class PostmanSandbox extends UniversalVM {
             cursor = _.clone(_.get(options, 'cursor', {})), // clone the cursor as it travels through IPC for mutation
             resolvedPackages = _.get(options, 'resolvedPackages'),
             debugMode = _.has(options, 'debug') ? options.debug : this.debug,
+            templateName = _.get(options, 'templateName'),
 
             // send the code to the sandbox to be intercepted and executed
             dispatchExecute = () => {
@@ -107,7 +109,8 @@ class PostmanSandbox extends UniversalVM {
                     timeout: executionTimeout,
                     resolvedPackages: resolvedPackages,
                     legacy: _.get(options, 'legacy'),
-                    disabledAPIs: options.disabledAPIs
+                    disabledAPIs: options.disabledAPIs,
+                    templateName: templateName
                 });
             };
 

lib/sandbox/execute.js

@@ -30,6 +30,30 @@ const _ = require('lodash'),
 
     executeContext = require('./execute-context');
 
+function execTemplate (template) {
+    return new Promise((resolve, reject) => {
+        const _module = { exports: {} },
+            scope = Scope.create({
+                eval: true,
+                ignore: ['require'],
+                block: ['bridge']
+            });
+
+        scope.import({
+            Buffer: require('buffer').Buffer,
+            module: _module
+        });
+
+        scope.exec(template, (err) => {
+            if (err) {
+                return reject(err);
+            }
+
+            return resolve(_module?.exports || {});
+        });
+    });
+}
+
 module.exports = function (bridge, glob) {
     // @note we use a common scope for all executions. this causes issues when scripts are run inside the sandbox
     // in parallel, but we still use this way for the legacy "persistent" behaviour needed in environment
@@ -42,53 +66,70 @@ module.exports = function (bridge, glob) {
     // For caching required information provided during
     // initialization which will be used during execution
     let initializationOptions = {},
-        initializeExecution;
+        templatesRegistry = {},
+        getProtocolMetadata = (protocolName) => {
+            return templatesRegistry[protocolName] || templatesRegistry._default || null;
+        };
 
     /**
      * @param {Object} options
-     * @param {String} [options.template]
+     * @param {String} [options.template] - Template string - To be deprecated, use `templates` instead
+     * @param {Record<String, String>} [options.templates] - Map of template names to template strings
+     * @param {String} [options.chaiPlugin]
      * @param {Boolean} [options.disableLegacyAPIs]
      * @param {Array.<String>} [options.disabledAPIs]
      */
-    bridge.once('initialize', ({ template, ...initOptions }) => {
+    bridge.once('initialize', async (initOptions) => {
         initializationOptions = initOptions || {};
 
-        // If no custom template is provided, go ahead with the default steps
-        if (!template) {
+        const { template, templates, chaiPlugin } = initializationOptions,
+            availableTemplates = templates || (template ? { _default: template } : {}),
+            templateNames = Object.keys(availableTemplates),
+            promises = templateNames.map((name) => {
+                return execTemplate(availableTemplates[name]);
+            });
+
+        // If no custom template or chai plugin is provided, go ahead with the default steps
+        if (!templates && !template && !chaiPlugin) {
             chai.use(require('chai-postman')(sdk, _, Ajv));
 
             return bridge.dispatch('initialize');
         }
 
-        const _module = { exports: {} },
-            scope = Scope.create({
-                eval: true,
-                ignore: ['require'],
-                block: ['bridge']
-            });
+        // Templates can pass a chai plugin as a string or a function
+        // or a chaiPlugin arg is supported that works with all templates and receives the registry as an argument
+        promises.push(chaiPlugin ? execTemplate(chaiPlugin) : Promise.resolve(null));
 
-        scope.import({
-            Buffer: require('buffer').Buffer,
-            module: _module
-        });
+        try {
+            const results = await Promise.all(promises),
+                templateChaiPlugins = [],
+                chaiPluginResult = results.pop();
 
-        scope.exec(template, (err) => {
-            if (err) {
-                return bridge.dispatch('initialize', err);
-            }
+            for (let i = 0; i < results.length; i++) {
+                const result = results[i];
 
-            const { chaiPlugin, initializeExecution: setupExecution } = (_module && _module.exports) || {};
+                templatesRegistry[templateNames[i]] = result;
 
-            if (_.isFunction(chaiPlugin)) {
-                chai.use(chaiPlugin);
+                if (_.isFunction(result.chaiPlugin)) {
+                    templateChaiPlugins.push(result.chaiPlugin);
+                }
             }
 
-            if (_.isFunction(setupExecution)) {
-                initializeExecution = setupExecution;
+            if (_.isFunction(chaiPluginResult)) {
+                chai.use(chaiPluginResult(templatesRegistry));
+            }
+            else if (templateChaiPlugins.length === 1) {
+                chai.use(templateChaiPlugins[0]);
+            }
+            else if (templateChaiPlugins.length > 1) {
+                throw new Error('sandbox: multiple chai plugins are not supported');
             }
 
             bridge.dispatch('initialize');
-        });
+        }
+        catch (error) {
+            return bridge.dispatch('initialize', error);
+        }
     });
 
     /**
@@ -108,6 +149,10 @@ module.exports = function (bridge, glob) {
             return bridge.dispatch('error', new Error('sandbox: execution identifier parameter(s) missing'));
         }
 
+        if (initializationOptions.templates && !(options.templateName && _.isString(options.templateName))) {
+            return bridge.dispatch('error', new Error('sandbox: template name parameter is missing from options'));
+        }
+
         !options && (options = {});
         !context && (context = {});
         event = (new PostmanEvent(event));
@@ -137,8 +182,10 @@ module.exports = function (bridge, glob) {
                 return isNonLegacySandbox(code) ? `${getNonLegacyCodeMarker()}${asyncCode}` : asyncCode;
             })(event.script?.toSource()),
 
+            protocolMetadata = getProtocolMetadata(options.templateName),
+
             // create the execution object
-            execution = new Execution(id, event, context, { ...options, initializeExecution }),
+            execution = new Execution(id, event, context, { ...options, protocolMetadata }),
 
             disabledAPIs = [
                 ...(initializationOptions.disabledAPIs || []),
@@ -242,7 +289,7 @@ module.exports = function (bridge, glob) {
         bridge.on(runRequestResponseEventName, function (id, err, response, results) {
             // Apply variable mutations from the scripts executed via pm.execution.runRequest
             // to the current execution scope
-            const { variableMutations = {}, skipResponseCasting = false } = results || {};
+            const { variableMutations = {}, responseType } = results || {};
 
             CONTEXT_VARIABLE_SCOPES.forEach(function (variableType) {
                 let mutableVariableScope = execution[variableType],
@@ -264,7 +311,7 @@ module.exports = function (bridge, glob) {
                 });
             });
 
-            timers.clearEvent(id, err, response, { skipResponseCasting });
+            timers.clearEvent(id, err, response, { responseType });
         });
 
         // handle cookies event from outside sandbox
@@ -331,7 +378,7 @@ module.exports = function (bridge, glob) {
                             context);
                     },
                     createPostmanRequire(options.resolvedPackages, scope),
-                    { disabledAPIs })
+                    { disabledAPIs, getProtocolMetadata })
             ),
             dispatchAssertions,
             { disableLegacyAPIs: initializationOptions.disableLegacyAPIs });

lib/sandbox/execution.js

@@ -29,7 +29,6 @@ class Execution {
         this.target = event.listen || PROPERTY.SCRIPT;
         this.legacy = options.legacy || {};
         this.cursor = _.isObject(options.cursor) ? options.cursor : {};
-
         this.data = _.get(context, PROPERTY.DATA, {});
         this.cookies = new sdk.CookieList(null, context.cookies);
 
@@ -42,14 +41,17 @@ class Execution {
             this[variableScope].enableTracking(trackingOptions);
         });
 
-        if (options.initializeExecution) {
-            const { request, response, message } = options.initializeExecution(this.target, context) || {};
+        if (options.protocolMetadata && options.protocolMetadata.initializeExecution) {
+            const { request, response, message } = options.protocolMetadata
+                .initializeExecution(this.target, context) || {};
 
             this.request = request;
             this.response = response;
             this.message = message;
         }
         else {
+            // If the associated item type does not have an initializer, then fallback to the defaults (HTTP-SDK).
+
             if (TARGETS_WITH_REQUEST[this.target] || _.has(context, PROPERTY.REQUEST)) {
                 /**
                  * @note:

lib/sandbox/pmapi.js

@@ -421,7 +421,7 @@ function Postman (execution,
                     }
 
                     onRunRequest(requestId, options || {},
-                        function (err, resp, context = { skipResponseCasting: false }) {
+                        function (err, resp, context) {
                             if (err) {
                                 return reject(err);
                             }
@@ -433,15 +433,15 @@ function Postman (execution,
                                 return resolve(null);
                             }
 
-                            // Temp
-                            // TODO: Make this work via custom response classes based on the response types
-                            // passed from consumers.
-                            if (!context || !context.skipResponseCasting) {
-                                resolve(PostmanResponse.isResponse(resp) ? resp : (new PostmanResponse(resp)));
-                            }
-                            else {
-                                resolve(resp);
+                            const ResponseClass = context && context.responseType ?
+                                options.getProtocolMetadata(context.responseType)?.Response :
+                                PostmanResponse;
+
+                            if (!ResponseClass) {
+                                return resolve(resp);
                             }
+
+                            resolve(ResponseClass.isResponse(resp) ? resp : (new ResponseClass(resp)));
                         });
                 });
             }

test/unit/sandbox-libraries/pm.test.js

@@ -1479,29 +1479,52 @@ describe('sandbox library - pm api', function () {
             });
 
             it('should handle response types for multi-protocol:others', function (done) {
-                const executionId = '8',
-                    sampleRequestToRunId = '5d559eb8-cd89-43a3-b93c-1e398d79c670';
+                const executionId = '1',
+                    individualTemplate = `
+                        class Response {
+                            constructor(response) {
+                                this.statusCode = response.statusCode;
+                                this.responseTime = response.responseTime;
+                                this.isCustomGRPCResponseClass = true;
+                            }
+                        }
 
-                context.on('execution.run_collection_request.' + executionId,
-                    function (cursor, id, reqId) {
-                        context.dispatch(`execution.run_collection_request_response.${id}`, reqId, null, {
-                            statusCode: 0, responseTime: 100
-                        }, { skipResponseCasting: true });
-                    });
+                        module.exports = { Response };
+                    `;
+
+                Sandbox.createContext({
+                    templates: { grpc: individualTemplate }
+                }, (errorInitializingSandbox, sandboxContext) => {
+                    if (errorInitializingSandbox) { return done(errorInitializingSandbox); }
+
+                    sandboxContext.on('execution.run_collection_request.' + executionId,
+                        function (_cursor, id, reqId) {
+                            sandboxContext.dispatch(`execution.run_collection_request_response.${id}`,
+                                reqId,
+                                null,
+                                { statusCode: 0, responseTime: 100 },
+                                { responseType: 'grpc' });
+                        });
 
-                let consoleMessage = '';
+                    let consoleMessage = '';
 
-                context.on('console', (_cursor, _level, message) => {
-                    consoleMessage = message;
-                });
+                    sandboxContext.on('console', (_cursor, _level, message) => {
+                        consoleMessage = message;
+                        expect(consoleMessage).to.eql({
+                            statusCode: 0,
+                            responseTime: 100,
+                            isCustomGRPCResponseClass: true
+                        });
+                    });
 
-                context.execute(`
-                    const grpcRequestResponse = await pm.execution.runRequest('${sampleRequestToRunId}');
-                    console.log(grpcRequestResponse);
-                `, { id: executionId }, function () {
-                    // No processing for non-http protocol responses, logged as is
-                    expect(consoleMessage).to.eql({ statusCode: 0, responseTime: 100 });
-                    done();
+                    sandboxContext.execute(`
+                        const grpcRequestResponse = await pm.execution.runRequest('sample-request-id');
+                        console.log(grpcRequestResponse);`,
+                    { id: executionId, templateName: 'grpc' },
+                    function (err) {
+                        done(err);
+                        sandboxContext.dispose();
+                    });
                 });
             });
         });