1 | # wait-on - wait for files, ports, sockets, http(s) resources
|
2 |
|
3 | wait-on is a cross-platform command line utility which will wait for files, ports, sockets, and http(s) resources to become available (or not available using reverse mode). Functionality is also available via a Node.js API. Cross-platform - runs everywhere Node.js runs (linux, unix, mac OS X, windows)
|
4 |
|
5 | wait-on will wait for period of time for a file to stop growing before triggering availability which is good for monitoring files that are being built. Likewise wait-on will wait for period of time for other resources to remain available before triggering success.
|
6 |
|
7 | For http(s) resources wait-on will check that the requests are returning 2XX (success) to HEAD or GET requests (after following any redirects).
|
8 |
|
9 | wait-on can also be used in reverse mode which waits for resources to NOT be available. This is useful in waiting for services to shutdown before continuing. (Thanks @skarbovskiy for adding this feature)
|
10 |
|
11 | [![Build Status](https://secure.travis-ci.org/jeffbski/wait-on.png?branch=master)](http://travis-ci.org/jeffbski/wait-on)
|
12 |
|
13 | ## Installation
|
14 |
|
15 | Latest version 3 requires Node.js v8.9+
|
16 |
|
17 | (Node.js v4 users can still use wait-on@2.1.2, and older Node.js
|
18 | engines, use wait-on@1.5.4)
|
19 |
|
20 |
|
21 | ```bash
|
22 | npm install wait-on # local version
|
23 | OR
|
24 | npm install -g wait-on # global version
|
25 | ```
|
26 |
|
27 | ## Usage
|
28 |
|
29 | Use from command line or using Node.js programmatic API.
|
30 |
|
31 | ### CLI Usage
|
32 |
|
33 | Assuming NEXT_CMD is the command to run when resources are available, then wait-on will wait and then exit with successfull exit code (0) once all resrouces are available causing NEXT_CMD to be run.
|
34 |
|
35 | wait-on can also be used in reverse mode which waits for resources to NOT be available. This is useful in waiting for services to shutdown before continuing. (Thanks @skarbovskiy for adding)
|
36 |
|
37 | If wait-on is interrupted before all resources are available, it will exit with non-zero exit code and thus NEXT_CMD will not be run.
|
38 |
|
39 | ```bash
|
40 | wait-on file1 && NEXT_CMD # wait for file1, then exec NEXT_CMD
|
41 | wait-on f1 f2 && NEXT_CMD # wait for both f1 and f2, the exec NEXT_CMD
|
42 | wait-on http://localhost:8000/foo && NEXT_CMD # wait for http 2XX HEAD
|
43 | wait-on https://myserver/foo && NEXT_CMD # wait for https 2XX HEAD
|
44 | wait-on http-get://localhost:8000/foo && NEXT_CMD # wait for http 2XX GET
|
45 | wait-on https-get://myserver/foo && NEXT_CMD # wait for https 2XX GET
|
46 | wait-on tcp:4000 && NEXT_CMD # wait for service to listen on a TCP port
|
47 | wait-on socket:/path/mysock # wait for service to listen on domain socket
|
48 | wait-on http://unix:/var/SOCKPATH:/a/foo # wait for http HEAD on domain socket
|
49 | wait-on http-get://unix:/var/SOCKPATH:/a/foo # wait for http GET on domain socket
|
50 | ```
|
51 |
|
52 | ```
|
53 | Usage: wait-on {OPTIONS} resource [...resource]
|
54 |
|
55 | Description:
|
56 |
|
57 | wait-on is a command line utility which will wait for files, ports,
|
58 | sockets, and http(s) resources to become available (or not available
|
59 | using reverse flag). Exits with success code (0) when all resources
|
60 | are ready. Non-zero exit code if interrupted or timed out.
|
61 |
|
62 | Options may also be specified in a config file (js or json). For
|
63 | example --config configFile.js would result in configFile.js being
|
64 | required and the resulting object will be merged with any
|
65 | command line options before wait-on is called. See exampleConfig.js
|
66 |
|
67 | In shell combine with && to conditionally run another command
|
68 | once resources are available. ex: wait-on f1 && NEXT_CMD
|
69 |
|
70 | resources types are defined by their prefix, if no prefix is
|
71 | present, the resource is assumed to be of type 'file'
|
72 |
|
73 | resource prefixes are:
|
74 |
|
75 | file: - regular file (also default type). ex: file:/path/to/file
|
76 | http: - HTTP HEAD returns 2XX response. ex: http://m.com:90/foo
|
77 | https: - HTTPS HEAD returns 2XX response. ex: https://my/bar
|
78 | http-get: - HTTP GET returns 2XX response. ex: http://m.com:90/foo
|
79 | https-get: - HTTPS GET returns 2XX response. ex: https://my/bar
|
80 | tcp: - TCP port is listening. ex: 1.2.3.4:9000 or foo.com:700
|
81 | socket: - Domain Socket is listening. ex: socket:/path/to/sock
|
82 | For http over socket, use http://unix:SOCK_PATH:URL_PATH
|
83 | like http://unix:/path/to/sock:/foo/bar or
|
84 | http-get://unix:/path/to/sock:/foo/bar
|
85 |
|
86 | Standard Options:
|
87 |
|
88 | -c, --config
|
89 |
|
90 | js or json config file, useful for http(s) options
|
91 |
|
92 | -d, --delay
|
93 |
|
94 | Initial delay before checking for resources in ms, default 0
|
95 |
|
96 | --httpTimeout
|
97 |
|
98 | Maximum time in ms to wait for an HTTP HEAD/GET request, default 0
|
99 | which results in using the OS default
|
100 |
|
101 | -i, --interval
|
102 |
|
103 | Interval to poll resources in ms, default 250ms
|
104 |
|
105 | -l, --log
|
106 |
|
107 | Log resources begin waited on and when complete or errored
|
108 |
|
109 | -r, --reverse
|
110 |
|
111 | Reverse operation, wait for resources to NOT be available
|
112 |
|
113 | -t, --timeout
|
114 |
|
115 | Maximum time in ms to wait before exiting with failure (1) code,
|
116 | default Infinity
|
117 |
|
118 | --tcpTimeout
|
119 |
|
120 | Maximum time in ms for tcp connect, default 300ms
|
121 |
|
122 | -v, --verbose
|
123 |
|
124 | Enable debug output to stdout
|
125 |
|
126 | -w, --window
|
127 |
|
128 | Stability window, the time in ms defining the window of time that
|
129 | resource needs to have not changed (file size or availability) before
|
130 | signalling success, default 750ms. If less than interval, it will be
|
131 | reset to the value of interval.
|
132 |
|
133 | -h, --help
|
134 |
|
135 | Show this message
|
136 | ```
|
137 |
|
138 | ### Node.js API usage
|
139 |
|
140 | ```javascript
|
141 | var waitOn = require('wait-on');
|
142 | var opts = {
|
143 | resources: [
|
144 | 'file1',
|
145 | 'http://foo.com:8000/bar',
|
146 | 'https://my.com/cat',
|
147 | 'http-get://foo.com:8000/bar',
|
148 | 'https-get://my.com/cat',
|
149 | 'tcp:foo.com:8000',
|
150 | 'socket:/my/sock',
|
151 | 'http://unix:/my/sock:/my/url',
|
152 | 'http-get://unix:/my/sock:/my/url'
|
153 | ],
|
154 | delay: 1000, // initial delay in ms, default 0
|
155 | interval: 100, // poll interval in ms, default 250ms
|
156 | timeout: 30000, // timeout in ms, default Infinity
|
157 | tcpTimeout: 1000, // tcp timeout in ms, default 300ms
|
158 | window: 1000, // stabilization time in ms, default 750ms
|
159 |
|
160 | // http options
|
161 | ca: [ /* strings or binaries */ ],
|
162 | cert: [ /* strings or binaries */ ],
|
163 | key: [ /* strings or binaries */ ],
|
164 | passphrase: 'yourpassphrase',
|
165 | auth: {
|
166 | user: 'theuser', // or username
|
167 | pass: 'thepassword' // or password
|
168 | },
|
169 | httpSignature: {
|
170 | keyId: 'yourKeyId',
|
171 | key: 'yourKey'
|
172 | },
|
173 | strictSSL: false,
|
174 | followAllRedirects: true,
|
175 | followRedirect: true,
|
176 | headers: {
|
177 | 'x-custom': 'headers'
|
178 | }
|
179 | };
|
180 |
|
181 | // Usage with callback function
|
182 | waitOn(opts, function (err) {
|
183 | if (err) { return handleError(err); }
|
184 | // once here, all resources are available
|
185 | });
|
186 |
|
187 | // Usage with promises
|
188 | waitOn(opts)
|
189 | .then(function () {
|
190 | // once here, all resources are available
|
191 | })
|
192 | .catch(function (err) {
|
193 | handleError(err);
|
194 | });
|
195 |
|
196 | // Usage with async await
|
197 | try {
|
198 | await waitOn(opts);
|
199 | // once here, all resources are available
|
200 | } catch (err) {
|
201 | handleError(err);
|
202 | }
|
203 | ```
|
204 |
|
205 | waitOn(opts, [cb]) - function which triggers resource checks
|
206 |
|
207 | - opts.resources - array of string resources to wait for. prefix determines the type of resource with the default type of `file:`
|
208 | - opts.delay - optional initial delay in ms, default 0
|
209 | - opts.interval - optional poll resource interval in ms, default 250ms
|
210 | - opts.log - optional flag which outputs to stdout, remaining resources waited on and when complete or errored
|
211 | - opts.reverse - optional flag to reverse operation so checks are for resources being NOT available, default false
|
212 | - opts.timeout - optional timeout in ms, default Infinity. Aborts with error.
|
213 | - opts.tcpTimeout - optional tcp timeout in ms, default 300ms
|
214 | - opts.verbose - optional flag which outputs debug output, default false
|
215 | - opts.window - optional stabilization time in ms, default 750ms. Waits this amount of time for file sizes to stabilize or other resource availability to remain unchanged.
|
216 | - http(s) specific options, see https://github.com/request/request#readme for specific details
|
217 | - opts.ca: [ /* strings or binaries */ ],
|
218 | - opts.cert: [ /* strings or binaries */ ],
|
219 | - opts.key: [ /* strings or binaries */ ],
|
220 | - opts.passphrase: 'yourpassphrase',
|
221 | - opts.auth: { user, pass }
|
222 | - opts.httpSignature: { keyId, key }
|
223 | - opts.strictSSL: false,
|
224 | - opts.followAllRedirects: true,
|
225 | - opts.followRedirect: true,
|
226 | - opts.headers: { 'x-custom': 'headers' },
|
227 |
|
228 | - cb(err) - if err is provided then, resource checks did not succeed
|
229 |
|
230 |
|
231 | ## Goals
|
232 |
|
233 | - simple command line utility and Node.js API for waiting for resources
|
234 | - wait for files to stabilize
|
235 | - wait for http(s) resources to return 2XX in response to HEAD request
|
236 | - wait for http(s) resources to return 2XX in response to GET request
|
237 | - wait for services to be listening on tcp ports
|
238 | - wait for services to be listening on unix domain sockets
|
239 | - configurable initial delay, poll interval, stabilization window, timeout
|
240 | - command line utility returns success code (0) when resources are availble
|
241 | - command line utility that can also wait for resources to not be available using reverse flag. This is useful for waiting for services to shutdown before continuing.
|
242 | - cross platform - runs anywhere Node.js runs (linux, unix, mac OS X, windows)
|
243 |
|
244 | ## Why
|
245 |
|
246 | I frequently need to wait on build tasks to complete or services to be available before starting next command, so this project makes that easier and is portable to everywhere Node.js runs.
|
247 |
|
248 | ## Get involved
|
249 |
|
250 | If you have input or ideas or would like to get involved, you may:
|
251 |
|
252 | - contact me via twitter @jeffbski - <http://twitter.com/jeffbski>
|
253 | - open an issue on github to begin a discussion - <https://github.com/jeffbski/wait-on/issues>
|
254 | - fork the repo and send a pull request (ideally with tests) - <https://github.com/jeffbski/wait-on>
|
255 |
|
256 | ## License
|
257 |
|
258 | - [MIT license](http://github.com/jeffbski/wait-on/raw/master/LICENSE)
|