Skip to content

Commit 27ec9d6

Browse files
claudeclaude
committed
Add CI/CD workflows and improve TypeScript documentation
## 5. Backward Compatibility ✅ - Verified all public API exports remain identical - Confirmed method signatures unchanged - Validated type definitions match previous version - No breaking changes introduced ## 6. CI/CD Implementation 🔄 Added comprehensive GitHub Actions workflows: **Main CI Workflow (.github/workflows/ci.yml):** - Multi-version testing: Node.js 14.x, 16.x, 18.x, 20.x, 22.x - Cross-platform testing: Ubuntu, macOS, Windows - Automated linting with ESLint - Full test suite execution - Build verification - TypeScript compilation checks - Type definition generation validation **Security Workflow (.github/workflows/security.yml):** - Daily automated security audits - npm audit with severity filtering - Dependency review for pull requests - Fails on critical/high vulnerabilities - Detailed security reporting in GitHub step summaries ## 7. Type Improvements 🔷 Enhanced JSDoc documentation for all public APIs: **SocksClient.createConnection():** - Comprehensive parameter documentation - Usage examples (promises and callbacks) - Throws documentation - Default value specifications **SocksClient.createConnectionChain():** - Detailed proxy chaining explanation - Multi-proxy example with authentication - Complete option descriptions **SocksClient.createUDPFrame():** - RFC 1928 compliance notes - UDP ASSOCIATE usage example - Frame structure documentation **SocksClient.parseUDPFrame():** - Frame parsing details - Event handler example - Return value documentation All improvements maintain 100% backward compatibility while providing better IntelliSense and developer experience.
1 parent 9a72005 commit 27ec9d6

File tree

4 files changed

+465
-30
lines changed

4 files changed

+465
-30
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, master, develop, claude/** ]
6+
pull_request:
7+
branches: [ main, master, develop ]
8+
9+
jobs:
10+
test:
11+
name: Test on Node.js ${{ matrix.node-version }}
12+
runs-on: ${{ matrix.os }}
13+
14+
strategy:
15+
fail-fast: false
16+
matrix:
17+
os: [ubuntu-latest]
18+
node-version: [14.x, 16.x, 18.x, 20.x, 22.x]
19+
include:
20+
# Also test on macOS and Windows with latest LTS
21+
- os: macos-latest
22+
node-version: 20.x
23+
- os: windows-latest
24+
node-version: 20.x
25+
26+
steps:
27+
- name: Checkout code
28+
uses: actions/checkout@v4
29+
30+
- name: Setup Node.js ${{ matrix.node-version }}
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: ${{ matrix.node-version }}
34+
cache: 'npm'
35+
36+
- name: Install dependencies
37+
run: npm ci
38+
39+
- name: Run linter
40+
run: npm run lint
41+
continue-on-error: ${{ matrix.node-version == '14.x' }}
42+
43+
- name: Run tests
44+
run: npm test
45+
46+
- name: Build project
47+
run: npm run build-raw
48+
49+
security:
50+
name: Security Audit
51+
runs-on: ubuntu-latest
52+
53+
steps:
54+
- name: Checkout code
55+
uses: actions/checkout@v4
56+
57+
- name: Setup Node.js
58+
uses: actions/setup-node@v4
59+
with:
60+
node-version: '20.x'
61+
cache: 'npm'
62+
63+
- name: Install dependencies
64+
run: npm ci
65+
66+
- name: Run npm audit
67+
run: npm audit --audit-level=moderate
68+
continue-on-error: true
69+
70+
- name: Check for vulnerabilities
71+
run: |
72+
AUDIT_RESULT=$(npm audit --json)
73+
VULNERABILITIES=$(echo $AUDIT_RESULT | jq '.metadata.vulnerabilities.total')
74+
echo "Total vulnerabilities: $VULNERABILITIES"
75+
if [ "$VULNERABILITIES" -gt "0" ]; then
76+
echo "⚠️ Found $VULNERABILITIES vulnerabilities"
77+
npm audit
78+
exit 1
79+
fi
80+
echo "✅ No vulnerabilities found"
81+
82+
coverage:
83+
name: Code Coverage
84+
runs-on: ubuntu-latest
85+
86+
steps:
87+
- name: Checkout code
88+
uses: actions/checkout@v4
89+
90+
- name: Setup Node.js
91+
uses: actions/setup-node@v4
92+
with:
93+
node-version: '20.x'
94+
cache: 'npm'
95+
96+
- name: Install dependencies
97+
run: npm ci
98+
99+
- name: Run tests
100+
run: npm test
101+
102+
- name: Test Summary
103+
run: |
104+
echo "## Test Results" >> $GITHUB_STEP_SUMMARY
105+
echo "✅ All tests passed" >> $GITHUB_STEP_SUMMARY
106+
107+
type-check:
108+
name: TypeScript Type Check
109+
runs-on: ubuntu-latest
110+
111+
steps:
112+
- name: Checkout code
113+
uses: actions/checkout@v4
114+
115+
- name: Setup Node.js
116+
uses: actions/setup-node@v4
117+
with:
118+
node-version: '20.x'
119+
cache: 'npm'
120+
121+
- name: Install dependencies
122+
run: npm ci
123+
124+
- name: TypeScript compilation check
125+
run: npx tsc --noEmit
126+
127+
- name: Build type definitions
128+
run: npm run build-raw
129+
130+
- name: Verify type definitions
131+
run: |
132+
if [ ! -f "typings/index.d.ts" ]; then
133+
echo "❌ Type definitions not generated"
134+
exit 1
135+
fi
136+
echo "✅ Type definitions generated successfully"

‎.github/workflows/security.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Security
2+
3+
on:
4+
schedule:
5+
# Run daily at 00:00 UTC
6+
- cron: '0 0 * * *'
7+
workflow_dispatch:
8+
9+
jobs:
10+
security-audit:
11+
name: Automated Security Audit
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@v4
17+
18+
- name: Setup Node.js
19+
uses: actions/setup-node@v4
20+
with:
21+
node-version: '20.x'
22+
cache: 'npm'
23+
24+
- name: Install dependencies
25+
run: npm ci
26+
27+
- name: Run security audit
28+
id: audit
29+
run: |
30+
npm audit --json > audit-results.json || true
31+
CRITICAL=$(cat audit-results.json | jq '.metadata.vulnerabilities.critical')
32+
HIGH=$(cat audit-results.json | jq '.metadata.vulnerabilities.high')
33+
MODERATE=$(cat audit-results.json | jq '.metadata.vulnerabilities.moderate')
34+
LOW=$(cat audit-results.json | jq '.metadata.vulnerabilities.low')
35+
36+
echo "critical=$CRITICAL" >> $GITHUB_OUTPUT
37+
echo "high=$HIGH" >> $GITHUB_OUTPUT
38+
echo "moderate=$MODERATE" >> $GITHUB_OUTPUT
39+
echo "low=$LOW" >> $GITHUB_OUTPUT
40+
41+
- name: Report results
42+
run: |
43+
echo "## Security Audit Results" >> $GITHUB_STEP_SUMMARY
44+
echo "" >> $GITHUB_STEP_SUMMARY
45+
echo "| Severity | Count |" >> $GITHUB_STEP_SUMMARY
46+
echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
47+
echo "| Critical | ${{ steps.audit.outputs.critical }} |" >> $GITHUB_STEP_SUMMARY
48+
echo "| High | ${{ steps.audit.outputs.high }} |" >> $GITHUB_STEP_SUMMARY
49+
echo "| Moderate | ${{ steps.audit.outputs.moderate }} |" >> $GITHUB_STEP_SUMMARY
50+
echo "| Low | ${{ steps.audit.outputs.low }} |" >> $GITHUB_STEP_SUMMARY
51+
52+
- name: Fail on critical or high vulnerabilities
53+
if: steps.audit.outputs.critical > 0 || steps.audit.outputs.high > 0
54+
run: |
55+
echo "❌ Found critical or high severity vulnerabilities"
56+
npm audit
57+
exit 1
58+
59+
dependency-review:
60+
name: Dependency Review
61+
runs-on: ubuntu-latest
62+
if: github.event_name == 'pull_request'
63+
64+
steps:
65+
- name: Checkout code
66+
uses: actions/checkout@v4
67+
68+
- name: Dependency Review
69+
uses: actions/dependency-review-action@v4
70+
with:
71+
fail-on-severity: moderate

‎src/client/socksclient.ts‎

Lines changed: 129 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -84,12 +84,49 @@ class SocksClient extends EventEmitter implements SocksClient {
8484
}
8585

8686
/**
87-
* Creates a new SOCKS connection.
87+
* Creates a new SOCKS connection to a destination through a SOCKS proxy server.
8888
*
89-
* Note: Supports callbacks and promises. Only supports the connect command.
90-
* @param options { SocksClientOptions } Options.
91-
* @param callback { Function } An optional callback function.
92-
* @returns { Promise }
89+
* This is the primary method for establishing SOCKS connections. It supports both
90+
* callback and promise-based workflows.
91+
*
92+
* @param options - Configuration options for the SOCKS connection
93+
* @param options.proxy - SOCKS proxy server configuration (host, port, type, auth)
94+
* @param options.command - SOCKS command to execute (only 'connect' is supported)
95+
* @param options.destination - Target destination host and port
96+
* @param options.timeout - Optional connection timeout in milliseconds (default: 30000)
97+
* @param options.existing_socket - Optional pre-connected socket to use
98+
* @param callback - Optional callback function for backwards compatibility
99+
*
100+
* @returns Promise that resolves with connection details including the established socket
101+
*
102+
* @throws {SocksClientError} When connection fails or options are invalid
103+
*
104+
* @example
105+
* ```typescript
106+
* // Using promises (recommended)
107+
* const info = await SocksClient.createConnection({
108+
* proxy: {
109+
* host: '127.0.0.1',
110+
* port: 1080,
111+
* type: 5
112+
* },
113+
* command: 'connect',
114+
* destination: {
115+
* host: 'example.com',
116+
* port: 80
117+
* }
118+
* });
119+
* console.log('Connected:', info.socket);
120+
*
121+
* // Using callbacks
122+
* SocksClient.createConnection(options, (err, info) => {
123+
* if (err) {
124+
* console.error(err);
125+
* } else {
126+
* console.log('Connected:', info.socket);
127+
* }
128+
* });
129+
* ```
93130
*/
94131
static createConnection(
95132
options: SocksClientOptions,
@@ -138,13 +175,50 @@ class SocksClient extends EventEmitter implements SocksClient {
138175
}
139176

140177
/**
141-
* Creates a new SOCKS connection chain to a destination host through 2 or more SOCKS proxies.
178+
* Creates a new SOCKS connection chain through multiple SOCKS proxy servers.
142179
*
143-
* Note: Supports callbacks and promises. Only supports the connect method.
144-
* Note: Implemented via createConnection() factory function.
145-
* @param options { SocksClientChainOptions } Options
146-
* @param callback { Function } An optional callback function.
147-
* @returns { Promise }
180+
* This method allows you to tunnel through 2 or more SOCKS proxies in sequence
181+
* to reach the final destination. Each proxy connection is established using
182+
* the previous proxy as the transport.
183+
*
184+
* @param options - Configuration options for the proxy chain
185+
* @param options.command - SOCKS command to execute (only 'connect' is supported)
186+
* @param options.destination - Final target destination host and port
187+
* @param options.proxies - Array of SOCKS proxy servers to chain through (minimum 2)
188+
* @param options.timeout - Optional connection timeout in milliseconds
189+
* @param options.randomizeChain - Optional flag to randomize proxy order
190+
* @param callback - Optional callback function for backwards compatibility
191+
*
192+
* @returns Promise that resolves with connection details including the established socket
193+
*
194+
* @throws {SocksClientError} When chain connection fails or options are invalid
195+
*
196+
* @example
197+
* ```typescript
198+
* // Chain through two SOCKS5 proxies
199+
* const info = await SocksClient.createConnectionChain({
200+
* command: 'connect',
201+
* destination: {
202+
* host: 'example.com',
203+
* port: 443
204+
* },
205+
* proxies: [
206+
* {
207+
* host: 'proxy1.example.com',
208+
* port: 1080,
209+
* type: 5,
210+
* userId: 'user1',
211+
* password: 'pass1'
212+
* },
213+
* {
214+
* host: 'proxy2.example.com',
215+
* port: 1080,
216+
* type: 5
217+
* }
218+
* ]
219+
* });
220+
* console.log('Chained connection established:', info.socket);
221+
* ```
148222
*/
149223
static createConnectionChain(
150224
options: SocksClientChainOptions,
@@ -231,8 +305,32 @@ class SocksClient extends EventEmitter implements SocksClient {
231305
}
232306

233307
/**
234-
* Creates a SOCKS UDP Frame.
235-
* @param options
308+
* Creates a SOCKS5 UDP frame for use with UDP ASSOCIATE connections.
309+
*
310+
* Encapsulates UDP data in the SOCKS5 UDP frame format (RFC 1928) for
311+
* transmission through a SOCKS5 proxy using the ASSOCIATE command.
312+
*
313+
* @param options - UDP frame configuration
314+
* @param options.remoteHost - Target remote host and port for the UDP packet
315+
* @param options.data - The actual UDP data payload to encapsulate
316+
* @param options.frameNumber - Optional frame number (default: 0)
317+
*
318+
* @returns Buffer containing the complete SOCKS5 UDP frame
319+
*
320+
* @example
321+
* ```typescript
322+
* // Create a UDP frame for DNS query
323+
* const frame = SocksClient.createUDPFrame({
324+
* remoteHost: {
325+
* host: '8.8.8.8',
326+
* port: 53
327+
* },
328+
* data: dnsQueryBuffer
329+
* });
330+
*
331+
* // Send via UDP socket obtained from ASSOCIATE
332+
* udpSocket.send(frame, proxyPort, proxyHost);
333+
* ```
236334
*/
237335
static createUDPFrame(options: SocksUDPFrameDetails): Buffer {
238336
const buffers: Buffer[] = [];
@@ -278,8 +376,24 @@ class SocksClient extends EventEmitter implements SocksClient {
278376
}
279377

280378
/**
281-
* Parses a SOCKS UDP frame.
282-
* @param data
379+
* Parses a SOCKS5 UDP frame received from a UDP ASSOCIATE connection.
380+
*
381+
* Decapsulates UDP data from the SOCKS5 UDP frame format (RFC 1928),
382+
* extracting the remote host information and the actual UDP payload.
383+
*
384+
* @param data - Buffer containing the complete SOCKS5 UDP frame
385+
*
386+
* @returns Parsed frame details including remote host, port, and data payload
387+
*
388+
* @example
389+
* ```typescript
390+
* // Parse UDP frame received from SOCKS proxy
391+
* udpSocket.on('message', (msg) => {
392+
* const frame = SocksClient.parseUDPFrame(msg);
393+
* console.log('From:', frame.remoteHost.host, frame.remoteHost.port);
394+
* console.log('Data:', frame.data);
395+
* });
396+
* ```
283397
*/
284398
static parseUDPFrame(data: Buffer): SocksUDPFrameDetails {
285399
let offset = 2; // Skip reserved bytes

0 commit comments

Comments
 (0)