0
# Resource Types
1

2
Support for multiple resource types including files, HTTP endpoints, TCP ports, and Unix domain sockets. Each resource type has specific behavior and configuration options.
3

4
## Capabilities
5

6
### File Resources
7

8
Monitor file system resources for existence and stability.
9

10
```javascript { .api }
11
// File resource formats
12
'file:/path/to/file'      // Explicit file prefix
13
'/path/to/file'           // Default type (no prefix)
14
'./relative/path'         // Relative paths supported
15
'file:C:\\path\\file.txt' // Windows paths
16
```
17

18
**Behavior:**
19
- Waits for file to exist and size to stabilize
20
- Uses `window` option for stability checking (default 750ms)
21
- In reverse mode, waits for file to not exist
22
- Monitors file size changes over the stability window
23

24
**Usage Examples:**
25

26
```javascript
27
// Wait for log file to be created and stabilize
28
await waitOn({
29
  resources: ['file:/var/log/app.log'],
30
  window: 2000  // Wait 2 seconds for size stability
31
});
32

33
// Wait for multiple files
34
await waitOn({
35
  resources: [
36
    '/tmp/ready.flag',
37
    'file:/data/output.json',
38
    './build/bundle.js'
39
  ]
40
});
41

42
// Reverse mode - wait for temporary file to be removed
43
await waitOn({
44
  resources: ['file:/tmp/lock.pid'],
45
  reverse: true
46
});
47
```
48

49
### HTTP/HTTPS Resources
50

51
Monitor HTTP endpoints for successful responses.
52

53
```javascript { .api }
54
// HTTP resource formats
55
'http://hostname:port/path'        // HTTP HEAD request (default)
56
'https://hostname:port/path'       // HTTPS HEAD request  
57
'http-get://hostname:port/path'    // HTTP GET request
58
'https-get://hostname:port/path'   // HTTPS GET request
59
```
60

61
**Behavior:**
62
- HEAD requests by default, GET requests with `-get` suffix
63
- Expects 2XX response codes (customizable with `validateStatus`)
64
- Follows redirects by default (controlled by `followRedirect`)
65
- Supports authentication, custom headers, SSL options
66
- Uses `httpTimeout` for individual request timeout
67

68
**Usage Examples:**
69

70
```javascript
71
// Basic HTTP health check
72
await waitOn({
73
  resources: ['http://localhost:3000/health']
74
});
75

76
// HTTPS with custom validation
77
await waitOn({
78
  resources: ['https://api.example.com/status'],
79
  validateStatus: (status) => status === 503 || (status >= 200 && status < 300),
80
  strictSSL: false
81
});
82

83
// HTTP GET request with authentication
84
await waitOn({
85
  resources: ['http-get://api.internal.com/ready'],
86
  auth: {
87
    username: 'monitor',
88
    password: 'secret'
89
  },
90
  headers: {
91
    'User-Agent': 'HealthCheck/1.0'
92
  }
93
});
94

95
// Multiple endpoints with timeout
96
await waitOn({
97
  resources: [
98
    'https://service1.com/health',
99
    'https://service2.com/health',
100
    'http://localhost:8080/ready'
101
  ],
102
  httpTimeout: 5000,
103
  simultaneous: 2
104
});
105
```
106

107
### TCP Port Resources
108

109
Monitor TCP ports for active listeners.
110

111
```javascript { .api }
112
// TCP resource formats
113
'tcp:hostname:port'    // Specific host and port
114
'tcp:port'             // Port on localhost
115
'tcp:localhost:port'   // Explicit localhost
116
'tcp:127.0.0.1:port'   // IP address
117
```
118

119
**Behavior:**
120
- Attempts TCP connection to specified host:port
121
- Uses `tcpTimeout` for connection timeout (default 300ms)
122
- Success when connection established (immediately closed)
123
- Supports both hostnames and IP addresses
124
- Defaults to localhost when host omitted
125

126
**Usage Examples:**
127

128
```javascript
129
// Wait for database
130
await waitOn({
131
  resources: ['tcp:localhost:5432'],
132
  tcpTimeout: 1000
133
});
134

135
// Multiple services with different hosts
136
await waitOn({
137
  resources: [
138
    'tcp:redis:6379',
139
    'tcp:postgres:5432', 
140
    'tcp:elasticsearch:9200'
141
  ]
142
});
143

144
// Local development ports
145
await waitOn({
146
  resources: [
147
    'tcp:3000',  // Web server
148
    'tcp:3001',  // API server
149
    'tcp:9229'   // Debug port
150
  ]
151
});
152

153
// Wait for service to stop listening (reverse mode)
154
await waitOn({
155
  resources: ['tcp:8080'],
156
  reverse: true,
157
  timeout: 10000
158
});
159
```
160

161
### Unix Socket Resources
162

163
Monitor Unix domain socket files for active listeners.
164

165
```javascript { .api }
166
// Socket resource format
167
'socket:/path/to/socket'       // Unix domain socket
168
'socket:/var/run/app.sock'     // Typical socket location
169
'socket:./relative/socket'     // Relative path
170
```
171

172
**Behavior:**
173
- Attempts connection to Unix domain socket
174
- Success when connection established (immediately closed)  
175
- Works only on Unix-like systems (Linux, macOS)
176
- Socket file must exist and be accepting connections
177

178
**Usage Examples:**
179

180
```javascript
181
// Wait for application socket
182
await waitOn({
183
  resources: ['socket:/var/run/myapp.sock']
184
});
185

186
// Multiple socket services
187
await waitOn({
188
  resources: [
189
    'socket:/tmp/redis.sock',
190
    'socket:/var/lib/mysql/mysql.sock'
191
  ]
192
});
193

194
// Development socket
195
await waitOn({
196
  resources: ['socket:./tmp/dev.sock'],
197
  timeout: 15000
198
});
199
```
200

201
### HTTP over Unix Socket
202

203
Special format for HTTP requests over Unix domain sockets.
204

205
```javascript { .api }
206
// HTTP over Unix socket formats
207
'http://unix:/path/to/socket:/url/path'      // HTTP HEAD over socket
208
'http-get://unix:/path/to/socket:/url/path'  // HTTP GET over socket
209
'https://unix:/path/to/socket:/url/path'     // HTTPS over socket (rare)
210
```
211

212
**Behavior:**
213
- Makes HTTP request over Unix domain socket
214
- Socket path and URL path are separated by colons
215
- Supports all HTTP options (headers, auth, etc.)
216
- Useful for containerized applications
217

218
**Usage Examples:**
219

220
```javascript
221
// Docker daemon API
222
await waitOn({
223
  resources: ['http://unix:/var/run/docker.sock:/version']
224
});
225

226
// Application health check over socket
227
await waitOn({
228
  resources: ['http-get://unix:/tmp/app.sock:/health'],
229
  headers: {
230
    'Host': 'localhost'
231
  }
232
});
233

234
// Multiple socket endpoints
235
await waitOn({
236
  resources: [
237
    'http://unix:/var/run/app.sock:/status',
238
    'http://unix:/tmp/worker.sock:/health'
239
  ]
240
});
241
```
242

243
## Resource Prefix Detection
244

245
wait-on automatically detects resource types based on prefixes:
246

247
```javascript { .api }
248
// Prefix detection rules
249
'file:'      → File resource
250
'http:'      → HTTP HEAD resource  
251
'https:'     → HTTPS HEAD resource
252
'http-get:'  → HTTP GET resource
253
'https-get:' → HTTPS GET resource
254
'tcp:'       → TCP port resource
255
'socket:'    → Unix socket resource
256
(no prefix)  → File resource (default)
257
```
258

259
## Cross-Platform Considerations
260

261
```javascript
262
// Platform compatibility
263
'file:'    → All platforms (Windows, macOS, Linux)
264
'http:'    → All platforms
265
'https:'   → All platforms  
266
'tcp:'     → All platforms
267
'socket:'  → Unix-like only (Linux, macOS)
268
```
269

270
**Usage Examples:**
271

272
```javascript
273
// Cross-platform file waiting
274
const isWindows = process.platform === 'win32';
275
const configFile = isWindows 
276
  ? 'C:\\app\\config.json'
277
  : '/etc/app/config.json';
278

279
await waitOn({
280
  resources: [`file:${configFile}`]
281
});
282

283
// Multi-platform service detection
284
await waitOn({
285
  resources: [
286
    'tcp:3306',                    // MySQL (all platforms)
287
    'tcp:5432',                    // PostgreSQL (all platforms)
288
    ...(isWindows ? [] : ['socket:/tmp/redis.sock'])  // Redis socket (Unix only)
289
  ]
290
});
291
```