Add Prompt Variables (#616)

Author: theerapatcha

README.md

@@ -24,9 +24,10 @@ REST Client allows you to send HTTP request and view the response in Visual Stud
     - AWS Signature v4
 * Environments and custom/system variables support
     - Use variables in any place of request(_URL_, _Headers_, _Body_)
-    - Support both __environment__, __file__ and __request__ custom variables
+    - Support __environment__, __file__, __request__ and __prompt__ custom variables
+    - Interactively assign __prompt__ custom variables per request
     - Auto completion and hover support for both __environment__, __file__ and __request__ custom variables
-    - Diagnostic support for __request__ and __file__ custom variables
+    - Diagnostic support for __request__, __file__ and __prompt__ custom variables
     - Go to definition support for __request__ and __file__ custom variables
     - Find all references support _ONLY_ for __file__ custom variables
     - Provide system dynamic variables
@@ -413,7 +414,7 @@ Environments give you the ability to customize requests using variables, and you
 Environments and including variables are defined directly in `Visual Studio Code` setting file, so you can create/update/delete environments and variables at any time you wish. If you __DO NOT__ want to use any environment, you can choose `No Environment` in the environment list. Notice that if you select `No Environment`, variables defined in shared environment are still available. See [Environment Variables](#environment-variables) for more details about environment variables.
 
 ## Variables
-We support two types of variables, one is __Custom Variables__ which is defined by user and can be further divided into __Environment Variables__, __File Variables__ and __Request Variables__, the other is __System Variables__ which is a predefined set of variables out-of-box.
+We support two types of variables, one is __Custom Variables__ which is defined by user and can be further divided into __Environment Variables__, __File Variables__, __Prompt Variables__, and __Request Variables__, the other is __System Variables__ which is a predefined set of variables out-of-box.
 
 The reference syntax of system and custom variables types has a subtle difference, for the former the syntax is `{{$SystemVariableName}}`, while for the latter the syntax is `{{CustomVariableName}}`, without preceding `$` before variable name. The definition syntax and location for different types of custom variables are different. Notice that when the same name used for custom variables, request variables takes higher resolving precedence over file variables, file variables takes higher precedence over environment variables.
 
@@ -480,6 +481,32 @@ Content-Type: {{contentType}}
 
 ```
 
+#### Prompt Variables
+With prompt variables, user can input the variables to be used when sending a request. This gives a flexibility to change most dynamic variables without having to change the `http` file. User can specify more than one prompt variables. The definition syntax of prompt variables is like a single-line comment by adding the syntax before the desired request url with the following syntax __`// @prompt {var1}`__ or __`# @prompt {var1}`__. A variable description is also assignable using __`// @prompt {var1} {description}`__ or __`# @prompt {var1} {description}`__ which will prompt an input popup with a desired description message.
+ 
+ 
+ The reference syntax is the same as others, follows __`{{var}}`__. The prompt variable will override any preceding assigned variable and will never be stored to be used in other requests.
+
+```http
+@hostname = api.example.com
+@port = 8080
+@host = {{hostname}}:{{port}}
+@contentType = application/json
+
+###
+# @prompt username
+# @prompt refCode Your reference code display on webpage
+# @prompt otp Your one-time password in your mailbox
+POST https://{{host}}/verify-otp/{{refCode}} HTTP/1.1
+Content-Type: {{contentType}}
+
+{
+    "username": "{{username}}",
+    "otp": "{{otp}}"
+}
+
+```
+
 #### Request Variables
 Request variables are similar to file variables in some aspects like scope and definition location. However, they have some obvious differences. The definition syntax of request variables is just like a single-line comment, and follows __`// @name requestName`__ or __`# @name requestName`__ just before the desired request url. You can think of request variable as attaching a *name metadata* to the underlying request, and this kind of requests can be called with **Named Request**, while normal requests can be called with **Anonymous Request**. Other requests can use `requestName` as an identifier to reference the expected part of the named request or its latest response. Notice that if you want to refer the response of a named request, you need to manually trigger the named request to retrieve its response first, otherwise the plain text of variable reference like `{{requestName.response.body.$.id}}` will be sent instead.
 

src/common/constants.ts

@@ -70,4 +70,6 @@ export const RequestVariableDefinitionWithNameRegexFactory = (name: string, flag
 
 export const RequestVariableDefinitionRegex: RegExp = RequestVariableDefinitionWithNameRegexFactory("\\w+", "m");
 
+export const PromptCommentRegex = /^\s*(?:#{1,}|\/{2,})\s*@prompt\s+([^\s]+)(?:\s+(.*))?\s*$/;
+
 export const LineSplitterRegex: RegExp = /\r?\n/g;

src/models/httpElement.ts

@@ -31,5 +31,6 @@ export enum ElementType {
     SystemVariable,
     EnvironmentCustomVariable,
     FileCustomVariable,
-    RequestCustomVariable
+    RequestCustomVariable,
+    PromptVariable
 }

src/models/requestMetadata.ts

@@ -16,6 +16,11 @@ export enum RequestMetadata {
      * Represents the cookie jar is disabled for this request
      */
     NoCookieJar = 'no-cookie-jar',
+
+    /**
+     * Used to allow user to interactively input variables for this request
+     */
+    Prompt = 'prompt',
 }
 
 export function fromString(value: string): RequestMetadata | undefined {

src/providers/customVariableDiagnosticsProvider.ts

@@ -8,6 +8,7 @@ import { disposeAll } from '../utils/dispose';
 import { RequestVariableCache } from "../utils/requestVariableCache";
 import { RequestVariableCacheValueProcessor } from "../utils/requestVariableCacheValueProcessor";
 import { Selector } from '../utils/selector';
+
 import { VariableProcessor } from "../utils/variableProcessor";
 
 interface VariableWithPosition {
@@ -17,6 +18,11 @@ interface VariableWithPosition {
     end: Position;
 }
 
+interface PromptVariableDefinitionWithRange {
+    name: string;
+    range: [number, number];
+}
+
 export class CustomVariableDiagnosticsProvider {
     private httpDiagnosticCollection: DiagnosticCollection = languages.createDiagnosticCollection();
 
@@ -82,16 +88,20 @@ export class CustomVariableDiagnosticsProvider {
             const diagnostics: Diagnostic[] = [];
 
             const allAvailableVariables = await VariableProcessor.getAllVariablesDefinitions(document);
+            const promptVariableDefinitions = this.findPromptVariableDefinitions(document);
             const variableReferences = this.findVariableReferences(document);
 
             // Variable not found
             [...variableReferences.entries()]
                 .filter(([name]) => !allAvailableVariables.has(name))
                 .forEach(([, variables]) => {
-                    variables.forEach(({name, begin, end}) => {
-                        diagnostics.push(
-                            new Diagnostic(new Range(begin, end), `${name} is not found`, DiagnosticSeverity.Error));
-                    });
+                    variables
+                        .filter(variable => !this.hasPromptVariableDefintion(promptVariableDefinitions, variable))
+                        .forEach(({ name, begin, end }) => {
+                            diagnostics.push(
+                                new Diagnostic(new Range(begin, end), `${name} is not found`, DiagnosticSeverity.Error));
+
+                        });
                 });
 
             // Request variable not active
@@ -101,7 +111,7 @@ export class CustomVariableDiagnosticsProvider {
                     && allAvailableVariables.get(name)![0] === VariableType.Request
                     && !RequestVariableCache.has(document, name))
                 .forEach(([, variables]) => {
-                    variables.forEach(({name, begin, end}) => {
+                    variables.forEach(({ name, begin, end }) => {
                         diagnostics.push(
                             new Diagnostic(new Range(begin, end), `Request '${name}' has not been sent`, DiagnosticSeverity.Information));
                     });
@@ -115,7 +125,7 @@ export class CustomVariableDiagnosticsProvider {
                     && RequestVariableCache.has(document, name))
                 .forEach(([name, variables]) => {
                     const value = RequestVariableCache.get(document, name);
-                    variables.forEach(({path, begin, end}) => {
+                    variables.forEach(({ path, begin, end }) => {
                         path = path.replace(/^\{{2}\s*/, '').replace(/\s*\}{2}$/, '');
                         const result = RequestVariableCacheValueProcessor.resolveRequestVariable(value, path);
                         if (result.state !== ResolveState.Success) {
@@ -166,4 +176,33 @@ export class CustomVariableDiagnosticsProvider {
 
         return vars;
     }
+
+    private findPromptVariableDefinitions(document: TextDocument): Map<string, PromptVariableDefinitionWithRange[]> {
+        const defs = new Map<string, PromptVariableDefinitionWithRange[]>();
+        const rawLines = document.getText().split(Constants.LineSplitterRegex);
+        const requestRanges = Selector.getRequestRanges(rawLines, { ignoreCommentLine: false });
+        for (const [start, end] of requestRanges) {
+            const scopedLines = rawLines.slice(start, end + 1);
+            for (const line of scopedLines) {
+                const matched = line.match(Constants.PromptCommentRegex);
+                if (matched) {
+                    const name = matched[1];
+                    if (defs.has(name)) {
+                        defs.get(name)!.push({ name, range: [start, end] });
+                    } else {
+                        defs.set(name, [{ name, range: [start, end] }]);
+                    }
+                }
+            }
+        }
+        return defs;
+    }
+    private hasPromptVariableDefintion(defs: Map<string, PromptVariableDefinitionWithRange[]>, variable: VariableWithPosition): boolean {
+        const { name, begin, end } = variable;
+        return defs.get(name)?.some(({ name, range: [rangeStart, rangeEnd] }) => {
+            return name === name
+                && rangeStart <= begin.line
+                && end.line <= rangeEnd;
+        }) || false;
+    }
 }

src/utils/httpElementFactory.ts

@@ -1,10 +1,12 @@
 import * as url from 'url';
-import { MarkdownString, SnippetString, TextDocument } from 'vscode';
+import { MarkdownString, SnippetString, TextDocument, window } from 'vscode';
 import * as Constants from '../common/constants';
 import { ElementType, HttpElement } from '../models/httpElement';
+import { RequestMetadata } from '../models/requestMetadata';
 import { EnvironmentVariableProvider } from './httpVariableProviders/environmentVariableProvider';
 import { FileVariableProvider } from './httpVariableProviders/fileVariableProvider';
 import { RequestVariableProvider } from './httpVariableProviders/requestVariableProvider';
+import { Selector } from './selector';
 import { UserDataManager } from './userDataManager';
 
 export class HttpElementFactory {
@@ -180,6 +182,32 @@ export class HttpElementFactory {
                     new SnippetString(`{{${name}.\${1|request,response|}.\${2|headers,body|}.\${3:Header Name, *(Full Body), JSONPath or XPath}}}`)));
         }
 
+        // add active editor elements
+        const editor = window.activeTextEditor;
+        if (editor) {
+            const activeLine =  editor.selection.active.line;
+            const selectedText = Selector.getDelimitedText(editor.document.getText(), activeLine);
+
+            if (selectedText) {
+                // convert request text into lines
+                const lines = selectedText.split(Constants.LineSplitterRegex);
+                const metadatas = Selector.parseReqMetadatas(lines);
+
+                // add prompt variables
+                const promptVariablesDefinitions = Selector.parsePromptMetadataForVariableDefinitions(metadatas.get(RequestMetadata.Prompt));
+                for (const { name, description } of promptVariablesDefinitions) {
+                    const v = new MarkdownString(`${description ? `Description: ${description}` : `Prompt Variable: \`${name}\``}`);
+                    originalElements.push(
+                        new HttpElement(
+                            name,
+                            ElementType.PromptVariable,
+                            '^\\s*[^@]',
+                            v,
+                            new SnippetString(`{{${name}}}`)));
+                }
+            }
+        }
+
         // add urls from history
         const historyItems = await UserDataManager.getRequestHistory();
         const distinctRequestUrls = new Set(historyItems.map(item => item.url));
@@ -216,4 +244,5 @@ export class HttpElementFactory {
 
         return elements;
     }
+
 }

src/utils/selector.ts

@@ -1,5 +1,5 @@
 import { EOL } from 'os';
-import { Range, TextEditor } from 'vscode';
+import { Range, TextEditor, window } from 'vscode';
 import * as Constants from '../common/constants';
 import { fromString as ParseReqMetaKey, RequestMetadata } from '../models/requestMetadata';
 import { SelectedRequest } from '../models/SelectedRequest';
@@ -12,6 +12,11 @@ export interface RequestRangeOptions {
     ignoreResponseRange?: boolean;
 }
 
+interface PromptVariableDefinition {
+    name: string;
+    description?: string;
+}
+
 export class Selector {
     private static readonly responseStatusLineRegex = /^\s*HTTP\/[\d.]+/;
 
@@ -38,6 +43,13 @@ export class Selector {
         // parse request metadata
         const metadatas = this.parseReqMetadatas(lines);
 
+        // process #@prompt comment metadata
+        const promptVariablesDefinitions = this.parsePromptMetadataForVariableDefinitions(metadatas.get(RequestMetadata.Prompt));
+        const promptVariables = await this.promptForInput(promptVariablesDefinitions);
+        if (!promptVariables) {
+            return null;
+        }
+
         // parse actual request lines
         const rawLines = lines.filter(l => !this.isCommentLine(l));
         const requestRange = this.getRequestRanges(rawLines)[0];
@@ -48,7 +60,7 @@ export class Selector {
         selectedText = rawLines.slice(requestRange[0], requestRange[1] + 1).join(EOL);
 
         // variables replacement
-        selectedText = await VariableProcessor.processRawRequest(selectedText);
+        selectedText = await VariableProcessor.processRawRequest(selectedText, promptVariables);
 
         return {
             text: selectedText,
@@ -78,19 +90,24 @@ export class Selector {
             const metaValue = matched[2];
             const metadata = ParseReqMetaKey(metaKey);
             if (metadata) {
-                metadatas.set(metadata, metaValue || undefined);
+                if (metadata === RequestMetadata.Prompt) {
+                    this.handlePromptMetadata(metadatas, line);
+                } else {
+                    metadatas.set(metadata, metaValue || undefined);
+                }
             }
         }
         return metadatas;
     }
 
     public static getRequestRanges(lines: string[], options?: RequestRangeOptions): [number, number][] {
         options = {
-                ignoreCommentLine: true,
-                ignoreEmptyLine: true,
-                ignoreFileVariableDefinitionLine: true,
-                ignoreResponseRange: true,
-            ...options};
+            ignoreCommentLine: true,
+            ignoreEmptyLine: true,
+            ignoreFileVariableDefinitionLine: true,
+            ignoreResponseRange: true,
+            ...options
+        };
         const requestRanges: [number, number][] = [];
         const delimitedLines = this.getDelimiterRows(lines);
         delimitedLines.push(lines.length);
@@ -153,7 +170,31 @@ export class Selector {
         return matched?.[1];
     }
 
-    private static getDelimitedText(fullText: string, currentLine: number): string | null {
+    public static getPrompVariableDefinition(text: string): PromptVariableDefinition | undefined {
+        const matched = text.match(Constants.PromptCommentRegex);
+        if (matched) {
+            const name = matched[1];
+            const description = matched[2];
+            return { name, description };
+        }
+    }
+
+    public static parsePromptMetadataForVariableDefinitions(text: string | undefined) : PromptVariableDefinition[] {
+        const varDefs : PromptVariableDefinition[] = [];
+        const parsedDefs = JSON.parse(text || "[]");
+        if (Array.isArray(parsedDefs)) {
+            for (const parsedDef of parsedDefs) {
+                varDefs.push({
+                    name: parsedDef['name'],
+                    description: parsedDef['description']
+                });
+            }
+        }
+
+        return varDefs;
+    }
+
+    public static getDelimitedText(fullText: string, currentLine: number): string | null {
         const lines: string[] = fullText.split(Constants.LineSplitterRegex);
         const delimiterLineNumbers: number[] = this.getDelimiterRows(lines);
         if (delimiterLineNumbers.length === 0) {
@@ -189,4 +230,30 @@ export class Selector {
             .filter(([, value]) => /^#{3,}/.test(value))
             .map(([index, ]) => +index);
     }
+
+    private static handlePromptMetadata(metadatas: Map<RequestMetadata, string | undefined> , text: string) {
+        const promptVarDef = this.getPrompVariableDefinition(text);
+        if (promptVarDef) {
+            const varDefs = this.parsePromptMetadataForVariableDefinitions(metadatas.get(RequestMetadata.Prompt));
+            varDefs.push(promptVarDef);
+            metadatas.set(RequestMetadata.Prompt, JSON.stringify(varDefs));
+        }
+    }
+
+    private static async promptForInput(defs: PromptVariableDefinition[]): Promise<Map<string, string> | null> {
+        const promptVariables = new Map<string, string>();
+        for (const { name, description } of defs) {
+            const value = await window.showInputBox({
+                prompt: `Input value for "${name}"`,
+                placeHolder: description
+            });
+            if (value !== undefined) {
+                promptVariables.set(name, value);
+            } else {
+                return null;
+            }
+        }
+        return promptVariables;
+    }
+
 }

src/utils/variableProcessor.ts

@@ -16,12 +16,11 @@ export class VariableProcessor {
         [EnvironmentVariableProvider.Instance, true],
     ];
 
-    public static async processRawRequest(request: string) {
+    public static async processRawRequest(request: string, resolvedVariables: Map<string, string> = new Map<string, string>()) {
         const variableReferenceRegex = /\{{2}(.+?)\}{2}/g;
         let result = '';
         let match: RegExpExecArray | null;
         let lastIndex = 0;
-        const resolvedVariables = new Map<string, string>();
         variable:
         while (match = variableReferenceRegex.exec(request)) {
             result += request.substring(lastIndex, match.index);