What is the Values functionality of whistle and how to use and manage Values?

Answer

Whistle provides powerful Values functionality that can store and manage various configuration data for flexible use in rules.

Values Basics

1. What are Values

Values is a data storage mechanism provided by whistle that can store:

• Configuration data
• Mock data
• Constant values
• Environment variables

2. Values File Formats

Values files support multiple formats:

• JSON format: values.json
• Properties format: values.properties
• INI format: values.ini
• YAML format: values.yaml

Creating and Using Values

1. Create JSON Format Values

Create file: values.json

json
{
  "local-host": "127.0.0.1",
  "local-port": "3000",
  "test-host": "test.example.com",
  "test-port": "8080",
  "api-base": "https://api.example.com",
  "timeout": "5000",
  "retry-count": "3"
}

Use in rules:

shell
www.example.com host {{local-host}}:{{local-port}}
api.example.com forward {{api-base}}

2. Create Properties Format Values

Create file: values.properties

shell
local.host=127.0.0.1
local.port=3000
test.host=test.example.com
test.port=8080
api.base=https://api.example.com
timeout=5000
retry.count=3

Use in rules:

shell
www.example.com host {{local.host}}:{{local.port}}
api.example.com forward {{api.base}}

3. Create INI Format Values

Create file: values.ini

ini
[local]
host=127.0.0.1
port=3000

[test]
host=test.example.com
port=8080

[api]
base=https://api.example.com
timeout=5000
retry=3

Use in rules:

shell
www.example.com host {{local.host}}:{{local.port}}
api.example.com forward {{api.base}}

Advanced Values Usage

1. Nested Objects

Create nested Values:

json
{
  "servers": {
    "local": {
      "host": "127.0.0.1",
      "port": "3000"
    },
    "test": {
      "host": "test.example.com",
      "port": "8080"
    }
  },
  "api": {
    "base": "https://api.example.com",
    "version": "v1"
  }
}

Use in rules:

shell
www.example.com host {{servers.local.host}}:{{servers.local.port}}
api.example.com forward {{api.base}}/{{api.version}}

2. Array Data

Create Values with arrays:

json
{
  "allowed-origins": [
    "https://www.example.com",
    "https://test.example.com",
    "https://localhost:3000"
  ],
  "api-endpoints": [
    "/api/user",
    "/api/list",
    "/api/detail"
  ]
}

Use in rules:

shell
# Use first element of array
www.example.com resHeaders://{cors-{{allowed-origins.0}}.json}

3. Environment Variables

Create environment variable Values:

json
{
  "env": "development",
  "api-url": "https://dev-api.example.com",
  "debug": true
}

Use in rules:

shell
# Configure based on environment variables
www.example.com forward {{api-url}}
www.example.com reqHeaders://{debug-{{debug}}.json}

Using Values in Scripts

1. Use in reqScript

Create script: use-values.js

javascript
const values = require('./values.json');

module.exports = function(req, res) {
  // Use data from Values
  const timeout = values.timeout || 5000;
  const retryCount = values['retry-count'] || 3;
  
  req.headers['X-Timeout'] = timeout;
  req.headers['X-Retry-Count'] = retryCount;
};

Configure rule:

shell
www.example.com reqScript://{use-values.js}

2. Use in resScript

Create script: use-values-res.js

javascript
const values = require('./values.json');

module.exports = function(req, res) {
  const originalEnd = res.end;
  
  res.end = function(chunk, encoding) {
    if (chunk) {
      const body = chunk.toString();
      const jsonData = JSON.parse(body);
      
      // Use data from Values
      jsonData.apiVersion = values.api.version;
      jsonData.environment = values.env;
      
      originalEnd.call(res, JSON.stringify(jsonData), encoding);
    } else {
      originalEnd.call(res, chunk, encoding);
    }
  };
};

Configure rule:

shell
www.example.com resScript://{use-values-res.js}

3. Use in Plugins

Create plugin: values-plugin.js

javascript
const fs = require('fs');
const path = require('path');

module.exports = function(server, options) {
  // Read Values file
  const valuesPath = path.join(__dirname, 'values.json');
  const values = JSON.parse(fs.readFileSync(valuesPath, 'utf8'));
  
  server.on('request', function(req, res) {
    // Use data from Values
    req.values = values;
    
    // Process request based on environment variables
    if (values.env === 'development') {
      req.headers['X-Debug'] = 'true';
    }
  });
};

Values Management Tips

1. Multi-Environment Values

Create Values files for different environments:

values-dev.json:

json
{
  "env": "development",
  "api-url": "https://dev-api.example.com",
  "debug": true
}

values-test.json:

json
{
  "env": "testing",
  "api-url": "https://test-api.example.com",
  "debug": true
}

values-prod.json:

json
{
  "env": "production",
  "api-url": "https://api.example.com",
  "debug": false
}

Switch environments:

bash
# Use development environment
cp values-dev.json values.json

# Use test environment
cp values-test.json values.json

# Use production environment
cp values-prod.json values.json

2. Values File Organization

Organize by functional modules:

api-values.json:

json
{
  "api-base": "https://api.example.com",
  "api-version": "v1",
  "timeout": "5000"
}

cors-values.json:

json
{
  "allowed-origins": [
    "https://www.example.com",
    "https://test.example.com"
  ],
  "allowed-methods": [
    "GET",
    "POST",
    "PUT",
    "DELETE"
  ]
}

Use in rules:

shell
api.example.com forward {{api-values.api-base}}/{{api-values.api-version}}
www.example.com resHeaders://{cors-values.json}

3. Values Version Control

Use Git to manage Values files:

bash
# Initialize Git repository
git init

# Add Values files
git add values.json

# Commit
git commit -m "Add values configuration"

# Push to remote repository
git push origin main

Values Best Practices

1. Naming Conventions

• Use lowercase letters and hyphens: local-host
• Use meaningful names: api-base-url
• Avoid special characters

2. Data Types

• Strings: Wrap in quotes
• Numbers: Use directly
• Booleans: Use true or false
• Arrays: Use square brackets
• Objects: Use curly braces

3. Comment Documentation

Add comments in Values file:

json
{
  "local-host": "127.0.0.1",
  "local-port": "3000",
  "api-base": "https://api.example.com",
  "timeout": "5000"
}

Create accompanying README file:

markdown
# Values Configuration Documentation

## Configuration Items

- `local-host`: Local server address
- `local-port`: Local server port
- `api-base`: API base address
- `timeout`: Request timeout (milliseconds)

## Usage

Use `{{key}}` in whistle rules to reference configuration items.

4. Security Considerations

• Don't store sensitive information in Values
• Use environment variables for sensitive data
• Regularly update Values files

Values Practical Examples

1. Dynamic Proxy Configuration

Create Values:

json
{
  "proxy": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": "8080"
  }
}

Configure rules:

shell
{{#if proxy.enabled}}
www.example.com host {{proxy.host}}:{{proxy.port}}
{{/if}}

2. Multi-Domain Configuration

Create Values:

json
{
  "domains": {
    "www": "www.example.com",
    "api": "api.example.com",
    "static": "static.example.com"
  },
  "servers": {
    "local": "127.0.0.1:3000",
    "test": "test.example.com:8080"
  }
}

Configure rules:

shell
{{domains.www}} host {{servers.local}}
{{domains.api}} forward https://{{servers.test}}
{{domains.static}} host {{servers.local}}

3. Conditional Configuration

Create Values:

json
{
  "features": {
    "new-feature": true,
    "beta-feature": false
  }
}

Configure rules:

shell
{{#if features.new-feature}}
www.example.com/new-feature resBody://{new-feature.json}
{{/if}}

{{#if features.beta-feature}}
www.example.com/beta resBody://{beta-feature.json}
{{/if}}