@skyramp/skyramp 0.4.31

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Skyramp 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# skyramp
+
+`skyramp` is an npm module that provides utility functions for leveraging [skyramp CLI](https://skyramp.dev/docs/commands/skyramp/) commands. The `skyramp` module provides functionalities to create and apply mock configurations for both gRPC and REST APIs. It also offers features for testing and asserting scenarios in various test environments. The module exports the following classes: `RestEndpoint`, `GrpcEndpoint`, `Scenario`, and `SkyrampClient`.
+
+## Installation
+To install Skyramp, simply run the following command in your terminal:
+```bash
+npm install skyramp
+```
+
+## Usage
+Once you've installed Skyramp, you can import it into your project like this:
+
+```bash
+const { GrpcEndpoint, RestEndpoint, SkyrampClient, Scenario } = require('skyramp');
+```
+
+### SkyrampClient
+The `SkyrampClient` class is the main entry point to interact with the skyramp module. It allows you to apply configurations, start test scenarios, and deploy and delete workers. First, you must set up the `SkyrampClient` with a kubernetes cluster.
+
+**Example: Provision Local Cluster with Skyramp**
+```bash
+const skyrampClient = new SkyrampClient();
+skyrampClient.applyLocal().then(function() {
+  // Local cluster provisioned
+}).catch(function(error) {
+  // Error occurred during provisioning
+});
+```
+Once you have a `SkyrampClient` instance configured with a kubernetes cluster, you can deploy the Skyramp Worker in-cluster, for applying mocks and running tests.
+**Example: Deploy Skyramp Worker**
+```bash
+skyrampClient.deployWorker('my-namespace').then(function() {
+  // Worker deployed successfully
+}).catch(function(error) {
+  // Error occurred during deployment
+});
+```
+
+### RestEndpoint
+The `RestEndpoint` class represents a REST API endpoint and provides methods to configure mock responses to apply them to the `SkyrampClient`.
+
+**Example: Create REST Mock Configuration**
+```bash
+restEndpoint = new RestEndpoint('artists', 'artists-GET', 50050, 'api/openapi/artists.yaml');
+restEndpoint.mockMethodFromFile('artists-GET', 'files/rest-values.yaml');
+skyrampClient.mockerApply('my-namespace', restEndpoint).then(function() {
+  // Mock applied successfully
+}).catch(function(error) {
+  // Error occurred during mock application
+});
+```
+
+### GrpcEndpoint
+The `GrpcEndpoint` class represents a gRPC API endpoint and provides methods to configure mock responses to apply them to the `SkyrampClient`.
+
+**Example: Create gRPC Mock Configuration**
+```bash
+grpcEndpoint = new GrpcEndpoint('routeguide', 'RouteGuide', 50051, 'api/pb/routeguide.proto');
+grpcEndpoint.mockMethodFromFile('GetFeature', 'files/grpc-response.yaml');
+skyrampClient.mockerApply('my-namespace', grpcEndpoint).then(function() {
+  // Mock applied successfully
+}).catch(function(error) {
+  // Error occurred during mock application
+});
+```
+
+### Scenario
+The `Scenario` class allows you to define test scenarios by specifying a series of API requests and assertions to be made. Once a `Scenario` is created, you can start it using the `SkyrampClient` instance.
+
+**Example: Test Assert Scenario (REST)**
+```bash
+scenario = new Scenario('rest-test')
+step1 = scenario.addRequest(restEndpoint, 'artists-GET');
+step2 = scenario.addAssertEqual(`${step1}.res.items[0].artist_name`, 'abc');
+skyrampClient.testerStart('test-worker', scenario).then(function() {
+  // Test scenario started
+}).catch(function(error) {
+  // Error occurred during the test scenario
+});
+```
+
+**Example: Test Assert Scenario (gRPC)**
+```bash
+scenario = new Scenario('routeguide-assert-test')
+step1 = scenario.addRequestFromFile(grpcEndpoint, 'GetFeature', 'files/grpc-request.yaml');
+step2 = scenario.addAssertEqual(`${step1}.res.name`, 'test-feature');
+skyrampClient.testerStart('test-worker', scenario).then(function() {
+  // Test scenario started
+}).catch(function(error) {
+  // Error occurred during the test scenario
+});
+```

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@skyramp/skyramp",
+  "version": "0.4.31",
+  "description": "module for leveraging skyramp cli functionality",
+  "scripts": {
+    "pack": "npm pack"
+  },
+  "files": [
+    "lib/**",
+    "src/*.js",
+    "src/*.ts",
+    "src/classes/*.js",
+    "src/classes/*.ts"
+  ],
+  "main": "src/index.js",
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "fs": "^0.0.1-security",
+    "js-yaml": "^4.1.0",
+    "koffi": "^2.5.3"
+  }
+}

package/src/classes/Endpoint.d.ts

@@ -0,0 +1,6 @@
+export declare class Endpoint {
+  constructor(endpointData: string);
+  mockMethod(methodName: string, mockObject: string, dynamic?: boolean): void;
+  mockMethodFromFile(methodName: string, fileName: string): void;
+  writeMockConfigurationToFile(kubernetesService: string): Promise<void>;
+}

package/src/classes/Endpoint.js

@@ -0,0 +1,68 @@
+const lib = require('../lib');
+const { getYamlBytes, readDataFromFile } = require('../utils');
+const writeMockDescriptionWrapper = lib.func('writeMockDescriptionWrapper', 'string', ['string', 'string']);
+
+class Endpoint {
+  constructor(endpointData) {
+    try {
+      const endpoint = JSON.parse(endpointData);
+      this.services = endpoint.services;
+      this.endpoint = endpoint.endpoints[0];
+      for (const method of this.endpoint.methods) {
+        method.proxy = true;
+      }
+      this.responseValues = endpoint.responseValues;
+      this.mockDescription = {
+        services: this.services,
+        endpoints: [this.endpoint],
+        responseValues: this.responseValues
+      };
+    } catch(error) {
+      throw new Error(endpointData);
+    }
+  }
+
+  mockMethod(methodName, mockObject, dynamic=false) {
+    for (const method of this.endpoint.methods) {
+      if (method.name === methodName || method.type === methodName) {
+        const responseName = method.responseValue;
+        delete method.proxy;
+        for (const responseValue of this.responseValues) {
+          if (responseValue.name === responseName) {
+            if (dynamic) {
+              responseValue.javascriptPath = mockObject;
+              delete responseValue.blob;
+            } else {
+              responseValue.blob = mockObject.responseValue.blob;
+              delete responseValue.javascriptPath;
+            }
+            return;
+          }
+        }
+      }
+    }
+    throw new Error(`Method ${methodName} not found`);
+  }
+
+  mockMethodFromFile(methodName, fileName) {
+    const [jsonData, dynamic] = readDataFromFile(fileName);
+    return this.mockMethod(methodName, jsonData, dynamic);
+  }
+
+  writeMockConfigurationToFile(kubernetesService) {
+    const yamlContent = getYamlBytes(this.mockDescription);
+    return new Promise((resolve, reject) => {
+      writeMockDescriptionWrapper.async(yamlContent, kubernetesService, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+}
+
+module.exports = Endpoint;

package/src/classes/GrpcEndpoint.d.ts

@@ -0,0 +1,4 @@
+import { Endpoint } from './Endpoint';
+export declare class GrpcEndpoint extends Endpoint {
+  constructor(name: string, service: string, port: number, pbFile: string);
+}

package/src/classes/GrpcEndpoint.js

@@ -0,0 +1,12 @@
+const Endpoint = require('./Endpoint');
+const lib = require('../lib');
+const newGrpcEndpointWrapper = lib.func('newGrpcEndpointWrapper', 'string', ['string', 'string', 'int', 'string']);
+
+class GrpcEndpoint extends Endpoint {
+  constructor(name, service, port, pbFile) {
+    const response = newGrpcEndpointWrapper(name, service, port, pbFile);
+    super(response);
+  }
+}
+
+module.exports = GrpcEndpoint;

package/src/classes/RestEndpoint.d.ts

@@ -0,0 +1,4 @@
+import { Endpoint } from './Endpoint';
+export declare class RestEndpoint extends Endpoint {
+  constructor(name: string, openApiTag: string, port: number, openapiFile: string);
+}

package/src/classes/RestEndpoint.js

@@ -0,0 +1,12 @@
+const Endpoint = require('./Endpoint');
+const lib = require('../lib');
+const newRestEndpointWrapper = lib.func('newRestEndpointWrapper', 'string', ['string', 'string', 'int', 'string']);
+
+class RestEndpoint extends Endpoint {
+  constructor(name, openApiTag, port, openapiFile) {
+    const response = newRestEndpointWrapper(name, openApiTag, port, openapiFile);
+    super(response);
+  }
+}
+
+module.exports = RestEndpoint;

package/src/classes/Scenario.d.ts

@@ -0,0 +1,8 @@
+export declare class Scenario {
+  constructor(name: string);
+  addRequest(endpoint: any, methodName: string, requestObject?: string, dynamic?: boolean): string;
+  addRequestFromFile(endpoint: any, methodName: string, requestFile: string): string;
+  buildRequestsFromEndpoint(endpoint: any): void;
+  addAssertEqual(value1: string, value2: string): string;
+  writeTestConfigurationToFile(): Promise<void>;
+}

package/src/classes/Scenario.js

@@ -0,0 +1,80 @@
+const lib = require('../lib');
+const { createTestDescriptionFromScenario, getYamlBytes, readDataFromFile } = require('../utils');
+const buildRequestsWrapper = lib.func('buildRequestsWrapper', 'string', ['string']);
+const writeTestDescriptionWrapper = lib.func('writeTestDescriptionWrapper', 'string', ['string', 'string']);
+
+class Scenario {
+  constructor(name) {
+    this.name = name;
+    this.steps = [];
+    this.services = [];
+    this.endpoints = [];
+    this.requests = [];
+  }
+
+  addRequest(endpoint, methodName, requestObject=undefined, dynamic=false) {
+    this.buildRequestsFromEndpoint(endpoint);
+    for (const request of this.requests) {
+      if (request.method === methodName) {
+        if (dynamic) {
+          request.requestValue.javascriptPath = requestObject;
+          delete request.requestValue.blob;
+        } else if (requestObject !== undefined) {
+          request.requestValue = requestObject.requestValue;
+        }
+        this.steps.push({ request: request.name });
+        return request.name;
+      }
+    }
+    throw new Error(`Method ${methodName} not found`);
+  }
+
+  addRequestFromFile(endpoint, methodName, requestFile) {
+    const [jsonData, dynamic] = readDataFromFile(requestFile);
+    return this.addRequest(endpoint, methodName, jsonData, dynamic);
+  }
+
+  buildRequestsFromEndpoint(endpoint) {
+    if (this.endpoints.indexOf(endpoint.endpoint) !== -1) {
+      return;
+    }
+    const processedMethods = endpoint.endpoint.methods.map(method => {
+      const { responseValue, proxy, ...rest } = method;
+      return rest;
+    });
+    this.services.push(...endpoint.services);
+    this.endpoints.push({ ...endpoint.endpoint, methods: processedMethods });
+    const yamlContent = getYamlBytes(endpoint.mockDescription);
+    const response = buildRequestsWrapper(yamlContent);
+    try {
+      const requests = JSON.parse(response);
+      this.requests.push(requests[0]);
+    } catch (error) {
+      throw new Error(response);
+    }
+  }
+
+  addAssertEqual(value1, value2) {
+    const assertion = `requests.${value1} == "${value2}"`;
+    this.steps.push({ asserts: assertion });
+    return assertion;
+  }
+
+  writeTestConfigurationToFile() {
+    const testDescription = createTestDescriptionFromScenario(this);
+    const yamlContent = getYamlBytes(testDescription);
+    return new Promise((resolve, reject) => {
+      writeTestDescriptionWrapper.async(yamlContent, this.name, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+}
+
+module.exports = Scenario;

package/src/classes/SkyrampClient.d.ts

@@ -0,0 +1,17 @@
+import { Endpoint } from './Endpoint';
+import { Scenario } from './Scenario';
+export declare class SkyrampClient {
+  constructor(kubeconfigPath?: string, clusterName?: string, context?: string);
+  applyLocal(): Promise<void>;
+  addKubeconfig(context: string, clusterName: string, kubeconfigPath: string): Promise<void>;
+  removeCluster(clusterName?: string): Promise<void>;
+  removeLocal(): Promise<void>;
+  removeClusterFromConfig(clusterName: string): Promise<void>;
+  mockerApply(namespace: string, address: string, endpoint: Endpoint): Promise<void>;
+
+  mockerApplyFromFile(namespace: string, address: string, filePath: string): Promise<void>;
+  applyMockDescription(namespace: string, address: string, mockYamlContent: string): Promise<void>;
+  testerStart(namespace: string, address: string, scenario: Scenario): Promise<void>;
+  testerStartFromFile(namespace: string, address: string, filePath: string): Promise<void>;
+  runTesterStart(namespace: string, address: string, testYamlContent: string, generateReport: boolean): Promise<void>;
+}

package/src/classes/SkyrampClient.js

@@ -0,0 +1,200 @@
+const lib = require('../lib');
+const { createTestDescriptionFromScenario, getYamlBytes, readDataFromFile } = require('../utils');
+const applyLocalWrapper = lib.func('applyLocalWrapper', 'string', []);
+const addKubeconfigWrapper = lib.func('addKubeconfigWrapper', 'string', ['string', 'bool', 'string', 'string']);
+const deleteSkyrampWorkerWrapper = lib.func('deleteSkyrampWorkerWrapper', 'string', ['string'])
+const deploySkyrampWorkerWrapper = lib.func('deploySkyrampWorkerWrapper', 'string', ['string', 'string', 'bool']);
+const getKubeConfigPath = lib.func('getKubeConfigPath', 'string', []);
+const removeLocalWrapper = lib.func('removeLocalWrapper', 'string', []);
+const removeClusterFromConfigWrapper = lib.func('removeClusterFromConfigWrapper', 'string', ['string']);
+const runTesterStartWrapper = lib.func('runTesterStartWrapper', 'string', ['string', 'string', 'string', 'bool']);
+const applyMockDescriptionWrapper = lib.func('applyMockDescriptionWrapper', 'string', ['string', 'string', 'string']);
+
+class SkyrampClient {
+  constructor(kubeconfigPath, clusterName, context) {
+    this.workerNamespaces = [];
+    if (kubeconfigPath || clusterName || context) {
+      this.addKubeconfig(clusterName, context, kubeconfigPath);
+    }
+  }
+
+  async applyLocal() {
+    return new Promise((resolve, reject) => {
+      applyLocalWrapper.async((err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          this.kubeConfigPath = getKubeConfigPath();
+          if (this.kubeConfigPath == "") {
+              reject(new Error("no kubeconfig found"));
+          } else {
+              resolve();
+          }
+        }
+      });
+    });
+  }
+
+  async addKubeConfig(context, clusterName, kubeConfigPath) {
+    return new Promise((resolve, reject) => {
+      addKubeconfigWrapper.async(context, clusterName, kubeConfigPath, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+          this.kubeConfigPath = kubeConfigPath;
+        }
+      });
+    });
+  }
+
+  async removeCluster(clusterName) {
+    if (clusterName) {
+      return this.removeClusterFromConfig(clusterName);
+    } else {
+      return this.removeLocal();
+    }
+  }
+
+  async removeLocal() {
+    return new Promise((resolve, reject) => {
+      removeLocalWrapper.async((err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  async removeClusterFromConfig(clusterName) {
+    return new Promise((resolve, reject) => {
+      removeClusterFromConfigWrapper.async(clusterName, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  async deploySkyrampWorker(namespace, workerImage='', localImage=false) {
+    if (this.kubeConfigPath === null) {
+      throw new Error('No cluster to deploy worker to.');
+    }
+    return new Promise((resolve, reject) => {
+      deploySkyrampWorkerWrapper.async(namespace, workerImage, localImage, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          this.workerNamespaces.push(namespace);
+          resolve();
+        }
+      });
+    });
+  }
+
+  async deleteSkyrampWorker(namespace) {
+    if (this.kubeConfigPath === null) {
+      throw new Error('No cluster to delete worker from.');
+    }
+    const index = this.workerNamespaces.indexOf(namespace);
+    if (index === -1) {
+      throw new Error(`No worker to delete from ${namespace} namespace.`);
+    }
+    return new Promise((resolve, reject) => {
+      deleteSkyrampWorkerWrapper.async(namespace, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          this.workerNamespaces.splice(index, 1);
+          resolve();
+        }
+      });
+    });
+  }
+
+  async mockerApply(namespace, address, endpoint) {
+    try {
+      const yamlContent = getYamlBytes(endpoint.mockDescription);
+      await this.applyMockDescription(namespace, address, yamlContent);
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  // NPM only: for VS code extension use
+  async mockerApplyFromFile(namespace, address, filepath) {
+    try {
+      const yamlContent = getYamlBytes(readDataFromFile(filepath)[0]);
+      await this.applyMockDescription(namespace, address, yamlContent);
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  async applyMockDescription(namespace, address, yamlContent) {
+    return new Promise((resolve, reject) => {
+      applyMockDescriptionWrapper.async(namespace, address, yamlContent, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  async testerStart(namespace, address, scenario) {
+    try {
+      const testDescription = createTestDescriptionFromScenario(scenario);
+      const testYamlContent = getYamlBytes(testDescription);
+      await this.runTesterStart(namespace, address, testYamlContent, false);
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  // NPM only: for VS code extension use
+  async testerStartFromFile(namespace, address, filepath) {
+    try {
+      const testDescription = readDataFromFile(filepath)[0]
+      const testYamlContent = getYamlBytes(testDescription);
+      await this.runTesterStart(namespace, address, testYamlContent, true);
+    } catch (err) {
+      throw err;
+    }
+  }
+  
+  async runTesterStart(namespace, address, testYamlContent, generateReport) {
+    return new Promise((resolve, reject) => {
+      runTesterStartWrapper.async(namespace, address, testYamlContent, generateReport, (err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+}
+
+module.exports = SkyrampClient;

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './classes/Endpoint';
+export * from './classes/GrpcEndpoint';
+export * from './classes/RestEndpoint';
+export * from './classes/Scenario';
+export * from './classes/SkyrampClient';
+export * from './utils';

package/src/index.js

@@ -0,0 +1,11 @@
+const SkyrampClient = require('./classes/SkyrampClient');
+const GrpcEndpoint = require('./classes/GrpcEndpoint');
+const RestEndpoint = require('./classes/RestEndpoint');
+const Scenario = require('./classes/Scenario');
+
+module.exports = {
+  SkyrampClient,
+  GrpcEndpoint,
+  RestEndpoint,
+  Scenario
+}

package/src/lib.js

@@ -0,0 +1,30 @@
+const koffi = require('koffi');
+const path = require('path');
+
+const platform = process.platform;
+const arch = process.arch;
+let libPath = '';
+
+if (platform === 'linux') {
+  if (arch === 'x64') {
+    libPath = 'dev-linux-amd64.so';
+  } else if (arch === 'ia32') {
+    libPath = 'dev-linux-386.so';
+  }
+} else if (platform === 'darwin') {
+  if (arch === 'x64') {
+    libPath = 'dev-darwin-amd64.dylib';
+  } else if (arch === 'arm64') {
+    libPath = 'dev-darwin-arm64.dylib';
+  }
+} else if (platform === 'win32') {
+  libPath = 'dev-windows-amd64.dll';
+}
+
+if (!libPath) {
+  throw new Error(`Unsupported platform or architecture: ${platform}-${arch}`);
+}
+const libFullPath = path.join(__dirname, '..', 'lib', libPath);
+const lib = koffi.load(libFullPath);
+
+module.exports = lib;

package/src/utils.js

@@ -0,0 +1,58 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+function getYamlBytes(jsonObject) {
+  try {
+    const yamlContent = yaml.dump(jsonObject, {lineWidth: 100});
+    return yamlContent;
+  } catch (error) {
+    throw new Error('Error converting to YAML bytes:', error);
+  }
+}
+
+function createTestDescriptionFromScenario(scenario) {
+  return {
+    test: {
+      name: scenario.name,
+      testPattern: [{
+          startAt: 1,
+          scenario: scenario.name
+      }]
+    },
+    services: scenario.services,
+    endpoints: scenario.endpoints,
+    scenarios: [{
+      name: scenario.name,
+      steps: scenario.steps
+    }],
+    requests: scenario.requests
+  };
+}
+
+function readDataFromFile(filename) {
+  try {
+    const fileExtension = path.extname(filename);
+    let jsonData;
+    if (fileExtension === '.json') {
+      const jsonContent = fs.readFileSync(filename, 'utf8');
+      jsonData = JSON.parse(jsonContent);
+    } else if (fileExtension === '.yaml' || fileExtension === '.yml') {
+      const yamlContent = fs.readFileSync(filename, 'utf8');
+      jsonData = yaml.load(yamlContent);
+    } else if (fileExtension === '.js') {
+      return [filename, true];
+    } else {
+      throw new Error('Unsupported file format. Only .json, .yaml, and .js files are supported.');
+    }
+    return [jsonData, false];
+  } catch(error) {
+    throw new Error('Error reading or parsing file: ', error);
+  }
+}
+
+module.exports = {
+  createTestDescriptionFromScenario,
+  getYamlBytes,
+  readDataFromFile
+}