0
# Validation and Utility Functions
1

2
Utility and validation functions for SOCKS client configuration validation and IP address manipulation. These functions are primarily used internally by the SOCKS client but are exported for advanced use cases.
3

4
## Capabilities
5

6
### Configuration Validation
7

8
Functions that validate SOCKS client configuration objects to ensure they contain valid and complete settings.
9

10
#### SocksClientOptions Validation
11

12
Validates a SocksClientOptions object for use with single proxy connections.
13

14
```typescript { .api }
15
/**
16
 * Validates the provided SocksClientOptions
17
 * @param options - The SocksClientOptions to validate
18
 * @param acceptedCommands - List of accepted SOCKS commands (default: ['connect', 'bind', 'associate'])
19
 * @throws SocksClientError if validation fails
20
 */
21
function validateSocksClientOptions(
22
  options: SocksClientOptions,
23
  acceptedCommands?: string[]
24
): void;
25
```
26

27
**Usage Example:**
28

29
```typescript
30
import { validateSocksClientOptions, SocksClientError } from "socks";
31

32
try {
33
  validateSocksClientOptions({
34
    command: 'connect',
35
    proxy: {
36
      host: '127.0.0.1',
37
      port: 1080,
38
      type: 5
39
    },
40
    destination: {
41
      host: 'example.com',
42
      port: 80
43
    }
44
  });
45
  console.log('Configuration is valid');
46
} catch (error) {
47
  if (error instanceof SocksClientError) {
48
    console.error('Configuration error:', error.message);
49
  }
50
}
51
```
52

53
#### SocksClientChainOptions Validation
54

55
Validates a SocksClientChainOptions object for use with proxy chaining.
56

57
```typescript { .api }
58
/**
59
 * Validates the SocksClientChainOptions
60
 * @param options - The SocksClientChainOptions to validate
61
 * @throws SocksClientError if validation fails
62
 */
63
function validateSocksClientChainOptions(
64
  options: SocksClientChainOptions
65
): void;
66
```
67

68
**Usage Example:**
69

70
```typescript
71
import { validateSocksClientChainOptions, SocksClientError } from "socks";
72

73
try {
74
  validateSocksClientChainOptions({
75
    command: 'connect',
76
    destination: {
77
      host: 'example.com',
78
      port: 80
79
    },
80
    proxies: [
81
      { host: '127.0.0.1', port: 1080, type: 5 },
82
      { host: '127.0.0.1', port: 1081, type: 5 }
83
    ]
84
  });
85
  console.log('Chain configuration is valid');
86
} catch (error) {
87
  if (error instanceof SocksClientError) {
88
    console.error('Chain configuration error:', error.message);
89
  }
90
}
91
```
92

93
### IP Address Utilities
94

95
Low-level utility functions for converting between different IP address representations used by SOCKS protocols.
96

97
#### IPv4 to 32-bit Integer Conversion
98

99
Converts an IPv4 address string to a 32-bit unsigned integer.
100

101
```typescript { .api }
102
/**
103
 * Converts an IPv4 address string to a 32-bit unsigned integer
104
 * @param ip - IPv4 address in dotted decimal notation (e.g., "192.168.1.1")
105
 * @returns 32-bit unsigned integer representation
106
 */
107
function ipv4ToInt32(ip: string): number;
108
```
109

110
**Usage Example:**
111

112
```typescript
113
import { ipv4ToInt32 } from "socks";
114

115
const ipInt = ipv4ToInt32("192.168.1.1");
116
console.log(ipInt); // 3232235777
117
```
118

119
#### 32-bit Integer to IPv4 Conversion
120

121
Converts a 32-bit unsigned integer back to an IPv4 address string.
122

123
```typescript { .api }
124
/**
125
 * Converts a 32-bit unsigned integer to an IPv4 address string
126
 * @param int32 - 32-bit unsigned integer representation
127
 * @returns IPv4 address in dotted decimal notation
128
 */
129
function int32ToIpv4(int32: number): string;
130
```
131

132
**Usage Example:**
133

134
```typescript
135
import { int32ToIpv4 } from "socks";
136

137
const ipString = int32ToIpv4(3232235777);
138
console.log(ipString); // "192.168.1.1"
139
```
140

141
#### IP Address to Buffer Conversion
142

143
Converts an IP address (IPv4 or IPv6) to a Buffer representation for network transmission.
144

145
```typescript { .api }
146
/**
147
 * Converts an IP address to a Buffer for network transmission
148
 * @param ip - IPv4 or IPv6 address string
149
 * @returns Buffer containing the binary representation of the IP address
150
 * @throws Error if the IP address format is invalid
151
 */
152
function ipToBuffer(ip: string): Buffer;
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import { ipToBuffer } from "socks";
159

160
// IPv4 address
161
const ipv4Buffer = ipToBuffer("192.168.1.1");
162
console.log(ipv4Buffer); // <Buffer c0 a8 01 01>
163

164
// IPv6 address
165
const ipv6Buffer = ipToBuffer("2001:db8::1");
166
console.log(ipv6Buffer); // <Buffer 20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01>
167

168
// Invalid address throws error
169
try {
170
  ipToBuffer("invalid-ip");
171
} catch (error) {
172
  console.error('Invalid IP address format');
173
}
174
```
175

176
## Validation Details
177

178
The validation functions check the following:
179

180
### SocksClientOptions Validation
181
- Command is one of: 'connect', 'bind', 'associate'
182
- Destination host is a valid string and port is 0-65535
183
- Proxy configuration is complete and valid
184
- Custom authentication settings are properly configured (if used)
185
- Timeout value is positive (if specified)
186
- Existing socket is a Duplex stream (if provided)
187

188
### SocksClientChainOptions Validation
189
- Command is 'connect' (only supported command for chaining)
190
- Destination host and port are valid
191
- At least 2 proxies are provided in the chain
192
- Each proxy in the chain passes individual proxy validation
193
- Timeout value is positive (if specified)
194

195
### Custom Authentication Validation
196
When custom authentication is configured, the validation ensures:
197
- Authentication method is in the valid range (0x80-0xFE)
198
- Request handler function is provided
199
- Response size is specified
200
- Response handler function is provided
201

202
## Error Handling
203

204
All validation functions throw `SocksClientError` instances with descriptive messages when validation fails. The error object includes the original options that failed validation for debugging purposes.
205

206
```typescript
207
try {
208
  validateSocksClientOptions(invalidOptions);
209
} catch (error) {
210
  if (error instanceof SocksClientError) {
211
    console.error('Error:', error.message);
212
    console.error('Failed options:', error.options);
213
  }
214
}
215
```