Mocker

Overview

The Mocker plugin returns simulated provider responses instead of calling a real AI provider. Use it to test and develop against DeepIntShield without spending tokens, to simulate errors and latency, or to generate realistic fake data. It works for both chat completion and responses requests, and you control exactly which requests are mocked with rules and conditions.

Quick Start

The Mocker is a gateway plugin. Enable it in your configuration. With no rules, it creates a default catch-all rule that returns a mock response for every chat and responses request.

{
  "plugins": {
    "mocker": {
      "enabled": true
    }
  }
}

All chat and responses requests then return: This is a mock response from the Mocker plugin.

Custom Response

Add rules to control what gets mocked and what is returned. For example, return a custom message only for OpenAI requests:

{
  "plugins": {
    "mocker": {
      "enabled": true,
      "rules": [
        {
          "name": "openai-mock",
          "enabled": true,
          "probability": 1.0,
          "conditions": {
            "providers": ["openai"]
          },
          "responses": [
            {
              "type": "success",
              "content": {
                "message": "Hello! This is a custom mock response for OpenAI.",
                "usage": {
                  "prompt_tokens": 15,
                  "completion_tokens": 25,
                  "total_tokens": 40
                }
              }
            }
          ]
        }
      ]
    }
  }
}

The same rule applies to both chat completion and responses requests.

Supported Request Types

The Mocker plugin supports:

• Chat completions - standard chat-based interactions
• Responses API - OpenAI-compatible responses format

Skip Mocker for Specific Requests

To bypass mocking for a specific request and route it to the real provider, send the x-bf-skip-mocker: true header on that request.

Key Features

Template Variables

Create dynamic responses using a message template:

{
  "type": "success",
  "content": {
    "message_template": "Hello from {{provider}} using model {{model}}!"
  }
}

Available Variables:

• {{provider}} - Provider name (e.g., “openai”, “anthropic”)
• {{model}} - Model name (e.g., “gpt-4”, “claude-3”)
• {{faker.*}} - Fake data generation (see Configuration Reference)

Weighted Response Selection

Configure multiple responses with different weights so the plugin picks one at random:

"responses": [
  {
    "type": "success",
    "weight": 0.8,
    "content": { "message": "Success response" }
  },
  {
    "type": "error",
    "weight": 0.2,
    "error": {
      "message": "Rate limit exceeded",
      "type": "rate_limit",
      "code": "429"
    }
  }
]

Latency Simulation

Add realistic delays to responses (values in milliseconds):

// Fixed latency
"latency": { "type": "fixed", "min_ms": 250 }

// Variable latency
"latency": { "type": "uniform", "min_ms": 100, "max_ms": 500 }

Advanced Matching

Regex message matching:

"conditions": {
  "message_regex": "(?i).*support.*|.*help.*"
}

Request size filtering (in bytes):

"conditions": {
  "request_size": { "min": 100, "max": 1000 }
}

Faker Data Generation

Create realistic test data using faker variables in a message_template:

{
  "name": "user-profile-example",
  "responses": [
    {
      "type": "success",
      "content": {
        "message_template": "User Profile:\n- Name: {{faker.name}}\n- Email: {{faker.email}}\n- Company: {{faker.company}}\n- Address: {{faker.address}}, {{faker.city}}\n- Phone: {{faker.phone}}\n- User ID: {{faker.uuid}}\n- Join Date: {{faker.date}}\n- Premium Account: {{faker.boolean}}"
      }
    }
  ]
}

Configuration Reference

Mocker config

Field	Type	Default	Description
enabled	bool	false	Enable/disable the entire plugin
default_behavior	string	"passthrough"	Action when no rules match: "passthrough", "success", "error"
global_latency	object	null	Global latency applied to all rules
rules	array	[]	List of mock rules evaluated in priority order

Rule

Field	Type	Default	Description
name	string	-	Unique rule name for identification
enabled	bool	true	Enable/disable this specific rule
priority	int	0	Higher numbers = higher priority
probability	float	1.0	Activation probability (0.0=never, 1.0=always)
conditions	object	{}	Matching conditions (empty = match all)
responses	array	-	Possible responses (weighted random selection)
latency	object	null	Rule-specific latency override

Conditions

Field	Type	Description
providers	array	Match specific providers: ["openai", "anthropic"]
models	array	Match specific models: ["gpt-4", "claude-3"]
message_regex	string	Regex pattern to match message content
request_size	object	Request size constraints in bytes

Response

Field	Type	Description
type	string	Response type: "success" or "error"
weight	float	Weight for random selection (default: 1.0)
content	object	Required if type="success"
error	object	Required if type="error"
allow_fallbacks	bool	Control fallback behavior (omit=allow, false=block)

Success response content

Field	Type	Description
message	string	Static response message
message_template	string	Template with variables: {{provider}}, {{model}}, {{faker.*}}
model	string	Override model name in response
usage	object	Token usage information
finish_reason	string	Completion reason (default: "stop")
custom_fields	object	Additional metadata fields

Error response

Field	Type	Description
message	string	Error message to return
type	string	Error type (e.g., "rate_limit", "auth_error")
code	string	Error code (e.g., "429", "401")
status_code	int	HTTP status code

Latency

Field	Type	Description
type	string	Latency type: "fixed" or "uniform"
min_ms	int	Minimum/exact latency in milliseconds
max_ms	int	Maximum latency in milliseconds (required for "uniform")

Faker Variables

Personal Information

• {{faker.name}} - Full name
• {{faker.first_name}} - First name only
• {{faker.last_name}} - Last name only
• {{faker.email}} - Email address
• {{faker.phone}} - Phone number

Location

• {{faker.address}} - Street address
• {{faker.city}} - City name
• {{faker.state}} - State/province
• {{faker.zip_code}} - Postal code

Business

• {{faker.company}} - Company name
• {{faker.job_title}} - Job title

Text and Data

• {{faker.lorem_ipsum}} - Lorem ipsum text
• {{faker.lorem_ipsum:10}} - Lorem ipsum with 10 words
• {{faker.uuid}} - UUID v4
• {{faker.hex_color}} - Hex color code

Numbers and Dates

• {{faker.integer}} - Random integer (1-100)
• {{faker.integer:10,50}} - Random integer between 10-50
• {{faker.float}} - Random float (0-100, 2 decimals)
• {{faker.float:1,10}} - Random float between 1-10
• {{faker.boolean}} - Random boolean
• {{faker.date}} - Date (YYYY-MM-DD format)
• {{faker.datetime}} - Datetime (YYYY-MM-DD HH:MM:SS format)

Best Practices

• Use priority to control rule evaluation order - place specific rules above general catch-all rules.
• Place specific conditions before general ones, and prefer simple string matching over complex regex when possible.
• In development, set probability: 1.0 to always mock. In production, use a low probability (e.g. 0.1) to mock only a fraction of traffic.

Common Issues

Plugin Not Triggering

1. Check that the plugin is enabled: "enabled": true
2. Verify the rule is enabled: "enabled": true on the rule
3. Check the probability: set "probability": 1.0 for testing
4. Verify the conditions match your request

Latency Not Working

Latency values are in milliseconds - set min_ms / max_ms, not raw nanosecond values.

Regex Not Matching

Test your regex pattern and ensure proper escaping:

// Case-insensitive matching
"message_regex": "(?i).*help.*"

// Escape special characters to match $12.34
"message_regex": "\\$\\d+\\.\\d+"

Controlling Fallbacks

Set allow_fallbacks to false on an error response to prevent failover to another provider:

{
  "type": "error",
  "allow_fallbacks": false,
  "error": { "message": "Authentication failed" }
}