-
Notifications
You must be signed in to change notification settings - Fork 16
/
got.node.txt
367 lines (288 loc) · 20.8 KB
/
got.node.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
GOT
ALTERNATIVES ==> #See HTTP client summary
VERSION ==> #14.4.1 (supports Node >=20 only)
/=+===============================+=\
/ : : \
)==: MAIN :==(
\ :_______________________________: /
\=+===============================+=/
GOT(['URL'|URL][, OPTS[, OPTSI]]) #HTTP request. Node.js only.
->GPROMISE|STREAM #Add:
# - User-Agent: got (URL) [C]
# - Content-Type [C]
# - Content-Length [C]
GPROMISE #PROMISE that resolves to RES
OPTS.isStream #BOOL (def: false). Return STREAM instead of GPROMISE
#Must write request body and read response body
STREAM.on('error', FUNC) #Emitted, i.e. should use Stream.pipeline()
STREAM.once('retry', FUNC(NUM)) #Called on 'error'.
#NUM is STREAM.retryCount (def: 0) + 1
# - to check to see if stop retrying
#STREAM will be restarted, i.e. can pipe|read it again
GOT[.stream][.METHOD](...) #Same with OPTS.method|stream set
new Options(OPTS)->OPTSI #
OPTSI.PROP #Can be get|set
OPTSI.toJSON()->OPTS #
OPTSI.extend(OPTS|OPTSI2)->OPTSI3 #Add to defaults OPTS
OPTSI.merge(OPTS2)->OPTSI3 #
OPTS.mutableDefaults #BOOL (def: false). Allow mutating OPTS.
/=+===============================+=\
/ : : \
)==: REQUEST :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.* #Same as HTTP.request(), i.e.:
# - protocol STR (def: 'http:')
# - host[name] STR (def: "localhost")
# - prefer hostname
# - will fire exception if non existing
# - family 4|6 (def: both)
# - port PORT_NUM (def: 80)
# - localAddress STR
# - method STR (def: "GET")
# - path STR (def: "/"): including hash and query string
# - headers OBJ
# - auth STR: e.g. "auth:password"
# - https.rejectUnauthorized|checkServerIdentity|certificateAuthority|certificate|key|passphrase|pfx
# - agent.http|https|http2 AGENT (def: globalAgent)
# - keepAlive[Msecs]: see AGENT
# - createConnection(...): see AGENT
#Not:
# - OPTS.socketPath:
# - should use '[PROTO://]unix:/SOCKET_PATH:/URI_PATH' URL instead
OPTS.url #URL|'URL'
OPTS.prefixUrl #URL|'URL': prepended to OPTS.url
#When used, input URL must not start with /
RES.requestUrl #URL before redirects
RES.url #URL after redirects
OPTS.searchParams #OBJ|SEARCHPARAMS|'SEARCH'
#null are converted to ''. undefined are skipped.
OPTS.agent #Can also be { PROTO: AGENT, ... } instead of AGENT
OPTS.body #STR|BUFFER|ISTREAM|FORM-DATA. Request body
#FORMDATA (using FORM-DATA library, see its doc): multipart/form-data request body
OPTS.json #VAL. application/json request body
OPTS.form #OBJ. application/x-www-form-urlencoded request body
OPTS.allowGetBody #BOOL (def: false). Allow request body with GET
OPTS.http2 #BOOL (def: false)
OPTS.enableUnixSockets #BOOL (def: false)
OPTSI.createNativeRequestOptions()
->OPTS #To use with HTTP.request()
OPTSI.getRequestFunction()->FUNC #Returns bound HTTP.request()
/=+===============================+=\
/ : : \
)==: RESPONSE :==(
\ :_______________________________: /
\=+===============================+=/
RES.* #Same as RES.* but with additional members.
OPTS.responseType #'json', 'buffer' or 'text' (def)
#Parse RES.body as VAL|BUFFER|STR
RES.body #VAL|BUFFER|STR
OPTS.resolveBodyOnly #BOOL (def: false)
#Resolve with parsed response instead of RES
GPROMISE.json|buffer|text()
->GPROMISE #Same as setting OPTS.responseType|resolveBodyOnly
OPTS.parseJson(STR)->VAL #On 'json' responseType. Def: JSON.parse
OPTS.stringifyJson(VAL)->STR #On 'json' responseType. Def: JSON.stringify
OPTS.decompress #BOOL (def: true)
#Decompress response (using DECOMPRESS-RESPONSE, see its doc)
#Sets Accept-Encoding: gzip, deflate, br [C]
OPTS.encoding #'ENCODING' (def: 'utf8')
RES.ip #'IP'|undefined
/=+===============================+=\
/ : : \
)==: REDIRECTS :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.followRedirect #BOOL[(RES)] (def: true). Follow Redirect [S] if 3**
RES.redirectUrls #URL_ARR
GPROMISE|STREAM.on
('redirect', FUNC(OPTS, RES)) #On HTTP redirection
OPTS.maxRedirects #NUM (def: 10)
OPTS.methodRewriting #BOOL (def: true). Change method to GET when receiving 302|303 (which is standard RFC behavior)
/=+===============================+=\
/ : : \
)==: ERRORS :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.throwHttpErrors #BOOL (def: true)
#Throw HTTPError if not 2**|3**
ERROR.code #STR
ERROR.options #OPTSI
RequestError #Name 'RequestError'. Network error (REQ.on('error'))
UnsupportedProtocolError #Name 'UnsupportedProtocolError'. When not HTTP[S]
ReadError #Name 'ReadError'. When reading response body fails
ParseError #Name 'ParseError', response RES. When parsing response body fails. Error message shows URL
HTTPError #Name 'HTTPError', response RES. When not 2**|3**. Error message shows status code.
TimeoutError #Name 'TimeoutError', timings RES.timings, event ERROR.event. On OPTS.timeout.
MaxRedirectsError #Name 'MaxRedirectsError', response RES. When redirecting more than OPTS.maxRedirects times
CacheError #Name 'CacheError'. Cache store error
CancelError #Name 'CancelError'. On cancel()
/=+===============================+=\
/ : : \
)==: PAGINATION :==(
\ :_______________________________: /
\=+===============================+=/
GOT.paginate.each #Paginates.
(['URL'|URL][, OPTS]) #Call HTTP request (using GOT(OPTS)) repeatedly
->ASYNC_ITERATOR_VAL #Iterates over each VAL (not each response)
GOT.paginate.all
(['URL'|URL][, OPTS])
->ARR #Paginates until the end
OPTS.pagination #POPTS
POPTS.paginate(OBJ)->false|OPTS #Pagination logic
#OBJ:
# - response RES
# - allItems ARR: all previous VALs
# - currentItems ARR2: current VALs
#Should return false to stop iteration
#Otherwise should return new OPTS for next HTTP request (using GOT(OPTS))
#By def, use Link: <URI>; rel="next" [S]
POPTS.transform(RES)->ARR #Customize how response body is parsed.
#Def: JSON.parse(RES.body)
POPTS.filter(OBJ)->BOOL #Whether to include a specific VAL
#ARR are previous VALs
#Def: none
POPTS.shouldContinue(OBJ)->BOOL #Same but to stop whole iteration
#Def: none
POPTS.countLimit #NUM. Stop whole iteration at NUM items
#Def: Infinity
POPTS.requestLimit #NUM. Max amount of iterations
#Def: 10000
POPTS.stackAllItems #BOOL. If false (def), ARR in POPTS.paginate|filter|shouldContinue() is always empty
#Useful to reduce memory consumption
POPTS.backoff #Wait NUMms (def: 0) between each request
/=+===============================+=\
/ : : \
)==: RETRY :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.retry #OBJ
#Retry-After [S]:
# - used if set
# - if 413, must use it
OPTS.retry.limit #NUM (def: 2)
OPTS.retry.calculateDelay(OBJ) #Extra logic applied to `limit`
->[PROMISE_]NUM #OBJ:
# - computedValue NUM: double each time, starting at 1 second
# - attemptCount NUM2
# - error ERROR
# - retryAfter NUM (in ms): Retry-After [S] if set
# - retryOptions OPTS.retry
#Def: OBJ.computedValue
OPTS.retry.methods #'METHOD'_ARR (def: ['get', 'put', 'head', 'delete', 'options', 'trace'])
OPTS.retry.statusCodes #NUM_ARR (def: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524])
OPTS.retry.errorCodes #STR_ARR (def: 'ETIMEDOUT|ECONNRESET|EADDRINUSE|ECONNREFUSED|EPIPE|ENOTFOUND|ENETUNREACH|EAI_AGAIN')
#For ERROR.code
OPTS.retry.maxRetryAfter #NUM. Max Retry-After [S]
OPTS.retry.backoffLimit #NUM (def: Infinity)
OPTS.retry.noise #NUM (def: 100, which means 0-100). Amount of ms randomly added to backoff
RES.retryCount #NUM
/=+===============================+=\
/ : : \
)==: TIMEOUT :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.timeout #Request timeout (in ms) (def: none)
#OBJ:
# - lookup NUM: DNS lookup
# - connect NUM: TCP handshake
# - secureConnect NUM: TLS setup
# - socket NUM: like HTTP.setTimeout()
# - send NUM: time to send request
# - response NUM: time between request sent and response starting to be received
# - request NUM: time between request started and response ended
# - read NUM: time between response read start and response ended
GPROMISE.cancel() #Abort HTTP request
REQ.isCanceled #BOOL
OPTS.signal #ABORT_SIGNAL
#Destroy request|streams on 'abort' event
/=+===============================+=\
/ : : \
)==: COOKIES :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.cookieJar TOUGHCOOKIE|OBJ #Store and sets Cookie [C]
#Must use tough-cookie library (see its doc) or OBJ:
# - setCookie('COOKIE', 'URL')->PROMISE
# - getCookieString('URL')->PROMISE_'COOKIE'
OPTS.ignoreInvalidCookies #BOOL: if false (def), throw if cookie is invalid
/=+===============================+=\
/ : : \
)==: CACHE :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.cache #'URI'|STORE|BOOL. Cache responses (HTTP caching)
#Passed to cacheable-request (see its doc)
RES|STREAM.isFromCache #BOOL. Whether cache was used.
OPTS.dnsCache #KEYV|BOOL (def: false). Cache DNS responses (see keyv doc)
OPTS.dnsLookupIpVersion #undefined (def, auto), 4 or 6
OPTS.dnsLookup #Customize DNS lookup (def: dns.lookup())
/=+===============================+=\
/ : : \
)==: PROGRESS :==(
\ :_______________________________: /
\=+===============================+=/
GPROMISE|STREAM.on #Request body upload progress event OBJ:
('uploadProgress', FUNC(OBJ)) # - percent 0-1
# - 0 if unknown
# - transferred NUM
# - total NUM
# - use Content-Length [C] or body size (using Buffer.byteLength(), FS.stat(), etc.)
# - 0 if unknown
#Sent every 150ms (unless did not change)
GPROMISE|STREAM.on #Response body download progress event OBJ:
('downloadProgress', FUNC(OBJ)) # - percent 0-1
# - 0 if unknown
# - transferred NUM
# - total NUM
# - use Content-Length [S]
# - 0 if unknown
/=+===============================+=\
/ : : \
)==: RESPONSE TIMES :==(
\ :_______________________________: /
\=+===============================+=/
RES.timings #OBJ of how long request|response took:
# - start NUM: request start
# - socket NUM: TCP socket created
# - lookup NUM: DNS lookup done
# - connect NUM: TCP handshake done
# - upload NUM: request body sent
# - response NUM: response body received
# - end|error NUM: request end|error
# - phases:
# - wait NUM: start to socket
# - dns NUM: socket to lookup
# - tcp NUM: lookup to connect
# - request NUM: connect to upload
# - firstByte NUM: upload to response
# - download NUM: response to end
# - total NUM: start to end|error
#Each NUM is a Unix timestamp (in ms)
/=+===============================+=\
/ : : \
)==: CUSTOM :==(
\ :_______________________________: /
\=+===============================+=/
OPTS.hooks #Events callbacks. OBJ:
# - init ARR of FUNC(OPTS, OPTSI):
# - before each request
# - only fired if OPTS|OPTSI was provided
# - beforeRequest ARR of FUNC(OPTS)[->PROMISE]
# - beforeRedirect ARR of FUNC(OPTS, RES)[->PROMISE]: before HTTP redirection
# - beforeRetry ARR of FUNC(ERROR, NUM)[->PROMISE]
# - beforeError ARR of FUNC(ERROR)->[PROMISE_]ERROR
# - afterResponse ARR of FUNC(RES, FUNC2(OPTS))->GPROMISE
OPTS.context #Stateful OBJ, meant for OPTS.hooks
OPTS.request #FUNC instead of HTTP[S].request()
GPROMISE|STREAM.on('error',
FUNC(ERROR, RES.body, RES)) #
GPROMISE|STREAM.on
('request', FUNC(REQ)) #
GPROMISE|STREAM.on
('upload-complete', FUNC(REQ)) #
GPROMISE|STREAM.on
('response', FUNC(RES)) #
GPROMISE|STREAM.off('EVENT', FUNC)#