Using Proxies

Graphman Client supports routing all gateway communication through a proxy server. This is useful in environments where direct connectivity to the Layer7 API Gateway is restricted and traffic must flow through a corporate or network proxy.

Proxy support is implemented as a built-in extension (graphman-extension-http-proxy) and is enabled by default.

Supported Proxy Types

agentType	Protocol	npm Package Required
http	HTTP proxy	http-proxy-agent
https	HTTPS proxy	https-proxy-agent
socks4	SOCKS4 proxy	socks-proxy-agent
socks5	SOCKS5 proxy	socks-proxy-agent

Note: The agentType determines which npm package is used to create the agent. For HTTP/HTTPS proxies, the actual agent class chosen at runtime is based on the target gateway's URL protocol (http:// vs https://), not the proxy's own protocol.

Prerequisites

The proxy agent packages are not bundled with graphman. Install the one matching your proxy type before use:

# For HTTP or HTTPS proxies
npm install http-proxy-agent https-proxy-agent --global

# For SOCKS4/5 proxies
npm install socks-proxy-agent --global

Configuration

Proxies are defined in the proxies section of graphman.configuration. Each entry is a named proxy profile.

Basic Structure

{
  "proxies": {
    "my-proxy": {
      "agentType": "http",
      "host": "proxy.example.com",
      "port": 3128,
      "credential": null,
      "options": {
        "timeout": 30000,
        "keepAlive": true,
        "maxSockets": 10,
        "rejectUnauthorized": false
      }
    }
  }
}

Fields

Field	Type	Description
agentType	string	Proxy protocol. One of: http, https, socks4, socks5
host	string	Proxy server hostname or IP address
port	number	Proxy server port
credential	string | null	Name of a credential profile (from credentials) for authenticated proxies. Set null for unauthenticated proxies
options	object	Additional options passed to the proxy agent (see below)

Options

Option	Type	Default	Description
timeout	number	30000	Socket timeout in milliseconds
keepAlive	boolean	true	Keep connections alive between requests
maxSockets	number	10	Maximum number of concurrent sockets
rejectUnauthorized	boolean	false	Whether to reject proxy servers with invalid TLS certificates

Linking a Proxy to a Gateway

Once a proxy profile is defined, assign it to a gateway by setting the proxy field to the proxy profile name:

{
  "gateways": {
    "default": {
      "address": "https://gateway.example.com:8443/graphman",
      "credential": "default",
      "rejectUnauthorized": true,
      "allowMutations": true,
      "proxy": "my-proxy"
    }
  }
}

When proxy is null, the gateway connects directly without a proxy.

Authenticated Proxies

To use a proxy that requires username/password authentication, create a credential profile and reference it from the proxy profile.

Step 1 — Add a credential:

{
  "credentials": {
    "proxy-creds": {
      "username": "proxyuser",
      "password": "proxypassword",
      "keyFilename": null,
      "certFilename": null,
      "keyPassphrase": null
    }
  }
}

Step 2 — Reference it from the proxy profile:

{
  "proxies": {
    "my-auth-proxy": {
      "agentType": "http",
      "host": "proxy.example.com",
      "port": 3128,
      "credential": "proxy-creds",
      "options": {
        "timeout": 30000,
        "keepAlive": true,
        "maxSockets": 10,
        "rejectUnauthorized": false
      }
    }
  }
}

The username and password are embedded in the proxy URL as http://proxyuser:proxypassword@proxy.example.com:3128.

SOCKS Proxy Example

{
  "proxies": {
    "socks-proxy": {
      "agentType": "socks5",
      "host": "socks.example.com",
      "port": 1080,
      "credential": null,
      "options": {
        "timeout": 30000,
        "keepAlive": true,
        "maxSockets": 10,
        "rejectUnauthorized": false
      }
    }
  }
}

Assign it to a gateway the same way as an HTTP proxy:

{
  "gateways": {
    "default": {
      "address": "https://gateway.example.com:8443/graphman",
      "credential": "default",
      "rejectUnauthorized": true,
      "allowMutations": true,
      "proxy": "socks-proxy"
    }
  }
}

Multiple Gateways with Different Proxies

You can define multiple proxy profiles and assign different proxies to different gateways:

{
  "proxies": {
    "corp-proxy": {
      "agentType": "http",
      "host": "proxy.corp.example.com",
      "port": 8080,
      "credential": null,
      "options": { "timeout": 30000, "keepAlive": true, "maxSockets": 10, "rejectUnauthorized": false }
    },
    "dmz-proxy": {
      "agentType": "socks5",
      "host": "socks.dmz.example.com",
      "port": 1080,
      "credential": null,
      "options": { "timeout": 30000, "keepAlive": true, "maxSockets": 10, "rejectUnauthorized": false }
    }
  },
  "gateways": {
    "internal-gw": {
      "address": "https://internal.example.com:8443/graphman",
      "credential": "default",
      "rejectUnauthorized": true,
      "allowMutations": true,
      "proxy": "corp-proxy"
    },
    "dmz-gw": {
      "address": "https://dmz.example.com:8443/graphman",
      "credential": "default",
      "rejectUnauthorized": true,
      "allowMutations": false,
      "proxy": "dmz-proxy"
    }
  }
}

Using a Proxy in CLI Commands

No additional CLI flags are needed. Proxy routing is applied automatically based on which gateway is targeted. Use --gateway to select the gateway profile:

# Export using the gateway that has a proxy configured
graphman export --using all --gateway internal-gw --output ./bundle.json

# Diff two gateways, each potentially behind different proxies
graphman diff --gateway source-gateway --targetGateway target-gateway --output ./diff.json

The default gateway (used when --gateway is omitted) is the profile named "default" in graphman.configuration.

How It Works

When graphman invokes a GraphQL request:

1. The gateway configuration is resolved, including its proxy field.
2. The named proxy profile is loaded and its credential (if any) is resolved.
3. The graphman-extension-http-proxy extension constructs a proxy agent:
   • agentType starting with socks → SocksProxyAgent from socks-proxy-agent
   • Otherwise → HttpsProxyAgent (if gateway address is https://) or HttpProxyAgent (if http://) from the respective package
4. The agent is attached to the outbound HTTP/HTTPS request, which routes all traffic through the proxy.

The extension is listed under options.extensions in graphman.configuration as "http-proxy" and is active for all operations.

Troubleshooting

failed to configure socks proxy agent / failed to configure http proxy agent

The required npm package is not installed. Run npm install socks-proxy-agent or npm install http-proxy-agent https-proxy-agent in your graphman working directory.

Connection timeouts through proxy

Increase the timeout value in the proxy options block. For slow or high-latency proxies, 60000 (60 seconds) is a reasonable starting point.

Proxy TLS certificate errors

Set "rejectUnauthorized": false in the proxy options block if the proxy uses a self-signed or corporate CA certificate that Node.js does not trust. Alternatively, configure the caFilename option in graphman.configuration options to trust a custom CA bundle.

Verifying proxy is in use

Set "log": "debug" in graphman.configuration options to see detailed HTTP request output, including the agent being used.