mirror/insomnia
1
0
Fork 0
mirror of https://github.com/Kong/insomnia.git synced 2026-05-19 06:12:37 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs(sdk): add docs for proxy-config (#8647)

Browse Source
This commit is contained in:
George
2025-04-28 17:35:11 +08:00
committed by Jay Wu
parent d82236e3dd
commit ca52fd9b79
1 changed files with 159 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
packages/insomnia-scripting-environment/src/objects/proxy-configs.ts
View File

@@ -3,6 +3,20 @@ import { Property, PropertyList } from './properties';
import type { Url } from './urls';
import { UrlMatchPattern, UrlMatchPatternList } from './urls';
/**
* Represents the configuration options for a proxy.
*
* @property match - A string pattern to match URLs for which the proxy should be used. It is used to initialize the {@link UrlMatchPattern} object internally.
* @property host - The hostname or IP address of the proxy server.
* @property port - (Optional) The port number of the proxy server.
* @property tunnel - A boolean indicating whether to use tunneling for the proxy connection.
* @property disabled - (Optional) A boolean indicating whether the proxy is disabled, default is false.
* @property authenticate - A boolean indicating whether authentication is required for the proxy.
* @property username - The username for proxy authentication.
* @property password - The password for proxy authentication.
* @property bypass - (Optional) An array of strings specifying hostnames or IPs to bypass the proxy.
* @property protocol - The protocol used by the proxy.
*/
export interface ProxyConfigOptions {
match: string;
host: string;
@@ -17,34 +31,100 @@ export interface ProxyConfigOptions {
protocol: string;
}
/**
* Represents a proxy configuration object used to define the settings for a proxy server.
*
* This class provides methods to construct, update, and test proxy configurations, as well
* as retrieve information such as the proxy URL and supported protocols.
*
* The proxy configuration includes properties such as the host, port, authentication
* credentials, tunneling options, and bypass list.
*
* @extends Property
*/
export class ProxyConfig extends Property {
/** @ignore */
override _kind = 'ProxyConfig';
type: string;
/**
* The hostname or IP address of the proxy server.
*/
host: string;
/**
* A string pattern used to match specific criteria or conditions.
* This can be used for filtering or identifying relevant configurations.
*/
match: string;
/**
* The port number to be used for the proxy configuration.
* This is an optional property and, if not specified, the default port
* for the protocol being used will be applied.
*/
port?: number;
tunnel: boolean;
/**
* Indicates whether authentication is required for the proxy configuration.
*/
authenticate: boolean;
/**
* The username associated with the proxy configuration.
*/
username: string;
/**
* The password associated with the proxy configuration.
*/
password: string;
/**
* A list of hostnames or IP addresses to bypass the proxy for.
*/
bypass: string[]; // it is for compatibility with Insomnia's bypass list
/**
* The protocol used in the proxy configuration, such as "http" or "https".
*/
protocol: string;
// following properties are hidden as they are not used while must be exposed
/** @ignore */
static authenticate = false;
/** @ignore */
static bypass: UrlMatchPatternList<UrlMatchPattern> = new UrlMatchPatternList<UrlMatchPattern>(undefined, []);
/** @ignore */
static host = '';
/** @ignore */
static match = '';
/** @ignore */
static password = '';
/** @ignore */
static port?: number = undefined;
/** @ignore */
static tunnel = false; // unsupported
/** @ignore */
static username = '';
/** @ignore */
static protocol = 'https:';
/**
* Constructs a new instance of the proxy configuration object.
*
* @param def - The definition object containing the proxy configuration properties.
* @param def.id - (Optional) The unique identifier for the proxy configuration.
* @param def.name - (Optional) The name of the proxy configuration.
* @param def.match - The match pattern for the proxy configuration. It is used to initialize the {@link UrlMatchPattern} object internally.
* @param def.host - The host address of the proxy server.
* @param def.port - (Optional) The port number of the proxy server.
* @param def.tunnel - Indicates whether the proxy uses tunneling.
* @param def.disabled - (Optional) Indicates whether the proxy configuration is disabled.
* @param def.authenticate - Indicates whether the proxy requires authentication.
* @param def.username - The username for proxy authentication.
* @param def.password - The password for proxy authentication.
* @param def.bypass - (Optional) A list of hosts to bypass the proxy.
* @param def.protocol - The protocol used by the proxy (e.g., HTTP, HTTPS).
*/
constructor(def: {
id?: string;
name?: string;
type?: string;
match: string;
host: string;
@@ -61,7 +141,6 @@ export class ProxyConfig extends Property {
this.id = def.id ? def.id : '';
this.name = def.name ? def.name : '';
this.type = def.type ? def.type : '';
this.disabled = def.disabled ? def.disabled : false;
this.host = def.host;
@@ -77,16 +156,40 @@ export class ProxyConfig extends Property {
static override _index = 'key';
/**
* Determines if the given object is a ProxyConfig.
* @param obj - The object to check.
* @returns `true` if the object is a ProxyConfig, otherwise `false`.
*/
static isProxyConfig(obj: object) {
return '_kind' in obj && obj._kind === 'ProxyConfig';
}
/**
* Retrieves the list of protocols specified in the match pattern.
*
* The match pattern is expected to follow a format such as
* 'http+https://example.com/*', where protocols are separated by a '+'.
* This method parses the match pattern and extracts the protocols.
*
* @returns {string[]} An array of protocol strings extracted from the match pattern.
*/
getProtocols(): string[] {
// match field example: 'http+https://example.com/*'
const urlMatch = new UrlMatchPattern(this.match);
return urlMatch.getProtocols();
}
/**
* Constructs and returns the full proxy URL as a string.
*
* The URL is built based on the protocol, host, port, and optional
* authentication credentials (username and password) of the proxy.
*
* @returns {string} The full proxy URL in the format:
* - With authentication: `protocol://username:password@host:port`
* - Without authentication: `protocol://host:port`
*/
getProxyUrl(): string {
// http://proxy_username:proxy_password@proxy.com:8080
const portSegment = this.port === undefined ? '' : `:${this.port}`;
@@ -97,6 +200,13 @@ export class ProxyConfig extends Property {
return `${this.protocol}//${this.host}${portSegment}`;
}
/**
* Tests whether a given URL matches the proxy configuration.
*
* @param url - The URL to test. If not provided, the method will return `false`.
* @returns `true` if the URL matches the proxy configuration and is not bypassed;
* otherwise, `false`.
*/
test(url?: string) {
if (!url) {
// TODO: it is confusing in which case url arg is optional
@@ -110,15 +220,21 @@ export class ProxyConfig extends Property {
return urlMatch.test(url);
}
update(options: {
host: string;
match: string;
port?: number;
tunnel: boolean;
authenticate: boolean;
username: string;
password: string;
}) {
/**
* Updates the proxy configuration with the provided options.
*
* @param options - An object containing the new proxy configuration options.
* The `bypass` and `protocol` properties are omitted and cannot be updated.
* The following properties can be updated:
* - `host`: The hostname or IP address of the proxy server.
* - `match`: A pattern to match URLs for which the proxy should be used.
* - `port`: The port number of the proxy server.
* - `tunnel`: A boolean indicating whether to use tunneling.
* - `authenticate`: A boolean indicating whether authentication is required.
* - `username`: The username for proxy authentication.
* - `password`: The password for proxy authentication.
*/
update(options: Omit<ProxyConfigOptions, "bypass" | "protocol">) {
this.host = options.host;
this.match = options.match;
this.port = options.port;
@@ -128,6 +244,12 @@ export class ProxyConfig extends Property {
this.password = options.password;
}
/**
* Updates the list of protocols. Currently this method is not supported in Insomnia
*
* @param _protocols - An array of protocol strings to update.
* @throws {Error} Always throws an error indicating that this method is not supported.
*/
updateProtocols(_protocols: string[]) {
// In Insomnia there is no whitelist while there is a blacklist
throw Error('updateProtocols is not supported in Insomnia');
@@ -140,16 +262,40 @@ export class ProxyConfig extends Property {
// {match: 'http+https://example2.com/*', host: 'proxy2.com'},
// ]);
/**
* A specialized list class for managing `ProxyConfig` objects.
*
* @template T - A type that extends `ProxyConfig`.
*/
export class ProxyConfigList<T extends ProxyConfig> extends PropertyList<T> {
/**
* Constructs a new instance of a list of ProxyConfig.
*
* @param parent - The parent `PropertyList` instance, or `undefined` if there is no parent.
* @param populate - An array of items of type `T` used to populate the list.
*/
constructor(parent: PropertyList<T> | undefined, populate: T[]) {
super(ProxyConfig, undefined, populate);
this.parent = parent;
}
/**
* Determines if the given object is a ProxyConfigList.
*
* @param obj - The object to check.
* @returns `true` if the object is a ProxyConfigList, otherwise `false`.
*/
static isProxyConfigList(obj: any) {
return '_kind' in obj && obj._kind === 'ProxyConfigList';
}
/**
* Resolves the proxy configuration for a given URL.
* It only returns the first one if multiple matches are found.
*
* @param url - The URL to resolve the proxy configuration for. If not provided, `null` is returned.
* @returns The first matching proxy configuration as a JSON object, or `null` if no match is found.
*/
resolve(url?: Url) {
if (!url) {
return null;
@@ -169,6 +315,7 @@ export class ProxyConfigList<T extends ProxyConfig> extends PropertyList<T> {
}
}
/** @ignore */
export function transformToSdkProxyOptions(
httpProxy: string,
httpsProxy: string,