Hoppscotch

The hoppscotch-js-sandbox package provides a secure environment for executing security-sensitive external JavaScript scripts. It is designed to isolate and run code that would otherwise pose a risk to the main application environment.

It currently powers the following Hoppscotch features:

• Hoppscotch Test Scripts: Scripts used to validate API responses.
• Hoppscotch Pre Request Scripts: Scripts used to modify requests before they are sent.

Environments allow you to store and reuse values across different requests and scripts, making it easier to switch between development, staging, and production settings.

Key Features

• Unlimited environments and variables: Create as many as needed.
• Initialization: Variables can be initialized through Pre-Request Scripts.
• Portability: Export and import environments via GitHub Gists.
• Efficiency: By using variables, you only need to update a value in one place to reflect changes throughout your entire request suite.

The Hoppscotch Kernel is designed as a minimal abstraction layer that mediates between high-level application logic and low-level platform implementations.

It is structured into three primary modules:

1. IO Module: Handles file systems and external resources.
2. Relay Module: Manages optimized network operations.
3. Store Module: Provides persistent storage with encryption support.

Developers should favor composition over modifying the kernel directly, as the codebase is intentionally minimal to provide only the necessary building blocks for features.

Hoppscotch allows you to execute JavaScript code at different stages of the request lifecycle to automate setup and validation.

Pre-Request Scripts

Executed before the request is sent. Use these to:

• Set environment variables.
• Include dynamic timestamps in request headers.
• Inject random alphanumeric strings into URL parameters.
• Run any arbitrary JavaScript function.

Post-Request Tests

Executed after the response is received. Use these to:

• Check the status code as an integer.
• Filter response headers.
• Parse response data.
• Set environment variables based on the response.
• Run custom JavaScript validation logic.

The agent supports per-domain configuration overrides. You can set global defaults using the * domain or define specific settings for individual domains (e.g., api.example.com).

Domain Management

• Global Defaults: Settings applied to all domains (domain: *).
• Domain Overrides: Specific settings for individual domains.
• Domain Addition/Removal: Use the domain management modal to add new domains or remove custom ones (the global default cannot be removed).

SSL/TLS Security Settings

For each domain, you can configure:

• Verify Host: Enable/disable hostname verification.
• Verify Peer: Enable/disable peer certificate verification.
• CA Certificates: Upload custom Certificate Authority certificates for domain validation.
• Client Certificates: Configure certificates for mutual TLS (mTLS).

The server requires a stable signing key to prevent "Invalid signature" errors when users have cached bundles from previous instances.

Key Resolution Order

1. Environment variables: WEBAPP_SERVER_SIGNING_KEY, WEBAPP_SERVER_SIGNING_SEED, or WEBAPP_SERVER_SIGNING_SECRET.
2. Key file on disk at the path specified by WEBAPP_SERVER_SIGNING_KEY_FILE (default: /data/webapp-server/signing.key).
3. Auto-generate and persist to disk.
4. Ephemeral fallback (logs the key for manual configuration).

Deployment Strategies

• Kubernetes/Multi-replica: To ensure all replicas use the same key, either mount a persistent volume at /data/webapp-server or set the WEBAPP_SERVER_SIGNING_SECRET to the same value across all replicas.
• Single Instance: Ensure the server has write permissions to /data/webapp-server so it can persist the auto-generated key.

Environment Files

When using the -e or --env flag, provide a JSON file where keys represent variable names:

{
  "ENV1": "value1",
  "ENV2": "value2"
}

In your Hoppscotch scripts, access these using: pw.env.get("ENV1").

Iteration Data (CSV)

When using --iteration-data <file_path>, provide a CSV file. For each row (iteration), the values are injected into the environment using the header names as keys:

key1,key2,key3
value1,value2,value3
value4,value5,value6

• Iteration 1: key1=value1, key2=value2, key3=value3
• Iteration 2: key1=value4, key2=value5, key3=value6

Hoppscotch provides hierarchical structures to manage large numbers of API requests.

Collections

Keep requests organized using collections and nested folders.

• Supports unlimited collections, folders, and requests.
• Export/Import: Save collections as files or GitHub Gists.
• Sync: Collections are synced with your cloud or local session storage.

Workspaces

Use Workspaces to separate different projects or environments (e.g., Personal vs. Team).

• Create unlimited workspaces.
• Easily switch between workspaces to manage multiple projects without cluttering your view.

The agent supports HTTP/HTTPS proxy routing, including support for proxy authentication (e.g., NTLM).

Configuration Steps

1. Select the target domain in the Agent settings.
2. Toggle the Proxy switch to enable it.
3. Enter the Proxy URL (e.g., http://proxy.example.com:8080).
4. If authentication is required, enter the Username and Password in the provided fields.