Rockxy NodeJS Sample Guidance

Runnable Node.js examples for sending HTTP and HTTPS traffic through Rockxy with explicit proxy and certificate configuration.

The examples cover:

• axios
• Node core HTTP/HTTPS
• got

Use this project when you want a small, repeatable demo that proves Rockxy can capture Node.js client traffic through explicit proxy and certificate configuration. The sample is intentionally local-first, policy-clean, and safe to publish after review: it uses fake localhost data, no real credentials, and no private account details.

Project Layout

.env.example                 # Environment template for the active Rockxy proxy.
src/config.js                # Shared config parsing, CA loading, and response output.
scripts/demo-server.js       # Local JSON server at 127.0.0.1:8000/demo.
scripts/run-all-examples.js  # Sequential runner for every client example.
examples/axios-example.js    # axios proxy + optional CA-backed HTTPS agent.
examples/node-core-example.js # Node core HTTP absolute-form + HTTPS CONNECT.
examples/got-example.js      # got with explicit HTTP and HTTPS proxy agents.
tests/*.test.js              # Network-free contract tests for config and entrypoints.

Design Principles

• Keep proxy routing explicit. The examples do not depend on hidden HTTP_PROXY or HTTPS_PROXY behavior.
• Keep TLS verification enabled. HTTPS examples use Rockxy's exported CA bundle instead of rejectUnauthorized: false.
• Keep the local demo inspectable. The default target is http://127.0.0.1:8000/demo, so Rockxy should show loopback traffic clearly.
• Keep failures actionable. Invalid URLs, missing proxy ports, and bad timeouts fail early with readable errors.
• Keep examples independent. run-all-examples.js starts a fresh Node process for each client so one library cannot leak state into another.

Requirements

• Node.js 20 or newer
• Rockxy running locally
• Rockxy capture started
• Rockxy root certificate exported when you want to inspect HTTPS traffic
• The package dependencies installed with npm ci

Step 1: Set Up Rockxy

1. Open Rockxy.
2. Start capture from the main toolbar.
3. Confirm Rockxy is listening on the active proxy port shown in the toolbar.
4. Open Developer Setup Hub.
5. Select Node.js.
6. Confirm Node.js is detected.
7. For plain HTTP demos, you can continue without exporting a certificate.
8. For HTTPS demos, generate and trust the Rockxy root certificate if you have not already done so.
9. Export the Rockxy root certificate as a .pem file.
10. Keep the exported certificate path ready for ROCKXY_CA_BUNDLE.

Recommended first check inside Rockxy:

1. In Developer Setup Hub, choose Node.js.
2. Pick the same client you want to demo.
3. Open the Validate tab.
4. Run the local validation probe.
5. Confirm Rockxy captures the probe before moving to this sample project.

If the validation probe does not appear, fix that in Rockxy first. The sample project depends on the same proxy and certificate path.

Step 2: Install This Project

npm ci
npm test

Expected test result:

tests 7
pass 7

Step 3: Configure The Demo

The examples read these environment variables:

export ROCKXY_PROXY_URL="http://127.0.0.1:9090"
export ROCKXY_CA_BUNDLE="/path/to/RockxyRootCA.pem"
export ROCKXY_TARGET_URL="http://127.0.0.1:8000/demo"
export ROCKXY_TIMEOUT_MS="10000"

ROCKXY_CA_BUNDLE is optional for plain HTTP, but it should point at Rockxy's exported root certificate when you inspect HTTPS traffic. The examples default to http://127.0.0.1:9090, but you should replace that value with the active port shown in Rockxy.

Configuration Reference

Variable	Default	Required	Notes
ROCKXY_PROXY_URL	http://127.0.0.1:9090	Yes	Must match Rockxy's active proxy port.
ROCKXY_TARGET_URL	http://127.0.0.1:8000/demo	Yes	Use the local demo first, then switch to HTTPS targets.
ROCKXY_CA_BUNDLE	unset	HTTPS only	Path to Rockxy's exported root CA .pem file.
ROCKXY_TIMEOUT_MS	10000	Yes	Positive number in milliseconds.

You can also start from the template:

cp .env.example .env

Then load it in shells that support source:

set -a
. ./.env
set +a

For a plain HTTP demo:

export ROCKXY_PROXY_URL="http://127.0.0.1:9090"
export ROCKXY_TARGET_URL="http://127.0.0.1:8000/demo"
unset ROCKXY_CA_BUNDLE

For an HTTPS demo:

export ROCKXY_PROXY_URL="http://127.0.0.1:9090"
export ROCKXY_CA_BUNDLE="/path/to/RockxyRootCA.pem"
export ROCKXY_TARGET_URL="https://example.com"

Use the proxy port and certificate path shown by your Rockxy app. Do not copy old values from notes if Rockxy has been restarted or reconfigured.

Step 4: Run The Demo

Start the local demo server in one terminal:

node scripts/demo-server.js

Keep that server running, then open a second terminal for the examples.

Start with one library:

node examples/axios-example.js

Then run all libraries:

node scripts/run-all-examples.js

Watch Rockxy's traffic list while the commands run. You should see requests from each example.

Demo Case Studies

Case 1: Plain HTTP Capture

Use this first when you want a fully local demo where Rockxy shows 127.0.0.1 as the target host.

Terminal 1:

node scripts/demo-server.js

Terminal 2:

export ROCKXY_PROXY_URL="http://127.0.0.1:9090"
export ROCKXY_TARGET_URL="http://127.0.0.1:8000/demo"
unset ROCKXY_CA_BUNDLE
node examples/axios-example.js

Expected result:

• the script prints status=200 and a JSON body;
• Rockxy shows one captured request to 127.0.0.1;
• if nothing appears, the issue is proxy routing, not certificate trust.

Case 2: HTTPS Inspection With The Rockxy Root CA

Use this when you want to show the full HTTPS debugging path.

export ROCKXY_PROXY_URL="http://127.0.0.1:9090"
export ROCKXY_CA_BUNDLE="/path/to/RockxyRootCA.pem"
export ROCKXY_TARGET_URL="https://example.com"
node examples/got-example.js

Expected result:

• the script prints an HTTPS status;
• Rockxy captures the request;
• if SSL proxying is enabled for the host, Rockxy can show decrypted request and response details.

Case 3: Compare Three Node.js HTTP Clients

Use this for a stronger demo because it proves the same Rockxy setup works across common Node.js client paths.

node scripts/run-all-examples.js

Expected result:

• each client prints a status;
• Rockxy shows separate captured requests;
• the examples use explicit proxy and CA options instead of relying on hidden environment behavior.

Run Individual Examples

node examples/axios-example.js
node examples/node-core-example.js
node examples/got-example.js

After each command, check Rockxy's traffic list for the request.

What Each Example Demonstrates

Example	Demonstrates
axios-example.js	explicit proxy, optional CA-backed HTTPS agent, and timeout
node-core-example.js	absolute-form HTTP requests through Rockxy plus CONNECT + TLS for HTTPS
got-example.js	HttpProxyAgent, HttpsProxyAgent, optional CA bundle, and timeout

The examples intentionally avoid certificate bypasses. If HTTPS fails, fix certificate trust or the CA bundle path.

Code Reading Notes

• src/config.js is the shared contract. Start there when changing defaults or environment handling.
• axios-example.js shows the highest-level client configuration.
• node-core-example.js is the most educational file because it spells out the proxy protocol directly.
• got-example.js demonstrates the agent-based pattern used by many Node.js HTTP clients.
• scripts/demo-server.js binds to 127.0.0.1 only and returns harmless JSON for reliable local captures.

Validate The Project

npm test

The tests do not send network traffic. They verify configuration handling and example entrypoints.

Demo Checklist

Before recording a demo or sharing the sample:

• start Rockxy capture;
• confirm the proxy port is correct;
• use fake local demo data only;
• avoid real tokens, cookies, emails, account IDs, production hosts, or private request payloads;
• run the local HTTP demo first;
• add HTTPS only after the root certificate path is correct.

Troubleshooting

Problem	Next action
Node.js is unavailable	Install Node.js 20 or newer, then rerun node --version.
Connection refused for the proxy	Start capture in Rockxy and update ROCKXY_PROXY_URL to the active toolbar port.
Demo server refuses the connection	Start node scripts/demo-server.js and keep that terminal open.
Rockxy captures nothing	Make sure the example is using ROCKXY_PROXY_URL and not reaching the target directly.
HTTPS fails	Set ROCKXY_CA_BUNDLE to the exported Rockxy root CA path.
The wrong host appears in Rockxy	Check ROCKXY_TARGET_URL; use http://127.0.0.1:8000/demo for the local demo.

License

MIT