1 | /*
|
2 | * Copyright 2020 Adobe. All rights reserved.
|
3 | * This file is licensed to you under the Apache License, Version 2.0 (the "License");
|
4 | * you may not use this file except in compliance with the License. You may obtain a copy
|
5 | * of the License at http://www.apache.org/licenses/LICENSE-2.0
|
6 | *
|
7 | * Unless required by applicable law or agreed to in writing, software distributed under
|
8 | * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
|
9 | * OF ANY KIND, either express or implied. See the License for the specific language
|
10 | * governing permissions and limitations under the License.
|
11 | */
|
12 |
|
13 | export const enum ALPNProtocol {
|
14 | ALPN_HTTP2 = 'h2',
|
15 | ALPN_HTTP2C = 'h2c',
|
16 | ALPN_HTTP1_1 = 'http/1.1',
|
17 | ALPN_HTTP1_0 = 'http/1.0',
|
18 | }
|
19 |
|
20 | export interface Http1Options {
|
21 | /**
|
22 | * Keep sockets around in a pool to be used by other requests in the future.
|
23 | * @default false
|
24 | */
|
25 | keepAlive?: boolean;
|
26 | /**
|
27 | * When using HTTP KeepAlive, how often to send TCP KeepAlive packets over sockets being kept alive.
|
28 | * Only relevant if keepAlive is set to true.
|
29 | * @default 1000
|
30 | */
|
31 | keepAliveMsecs?: number;
|
32 | /**
|
33 | * Maximum number of sockets to allow per host.
|
34 | * @default Infinity
|
35 | */
|
36 | maxSockets?: number;
|
37 | /**
|
38 | * Maximum number of sockets allowed for all hosts in total. Each request will use a new socket until the maximum is reached.
|
39 | * @default Infinity
|
40 | */
|
41 | maxTotalSockets?: number;
|
42 | /**
|
43 | * Maximum number of sockets to leave open in a free state. Only relevant if keepAlive is set to true.
|
44 | * @default 256
|
45 | */
|
46 | maxFreeSockets?: number;
|
47 | /**
|
48 | * Socket timeout in milliseconds. This will set the timeout when the socket is connected.
|
49 | */
|
50 | timeout?: number;
|
51 | /**
|
52 | * Scheduling strategy to apply when picking the next free socket to use.
|
53 | * @default 'fifo'
|
54 | */
|
55 | scheduling?: 'fifo' | 'lifo';
|
56 | /**
|
57 | * (HTTPS only)
|
58 | * If not false, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails; err.code contains the OpenSSL error code.
|
59 | * @default true
|
60 | */
|
61 | rejectUnauthorized?: boolean;
|
62 | /**
|
63 | * (HTTPS only)
|
64 | * Maximum number of TLS cached sessions. Use 0 to disable TLS session caching.
|
65 | * @default 100
|
66 | */
|
67 | maxCachedSessions?: number;
|
68 | }
|
69 |
|
70 | type HeadersInit = Headers | Object | Iterable<readonly [string, string]> | Iterable<Iterable<string>>;
|
71 |
|
72 | export interface RequestInit {
|
73 | /**
|
74 | * A BodyInit object or null to set request's body.
|
75 | */
|
76 | body?: BodyInit | Object |null;
|
77 | /**
|
78 | * A Headers object, an object literal, or an array of two-item arrays to set request's headers.
|
79 | */
|
80 | headers?: HeadersInit;
|
81 | /**
|
82 | * A string to set request's method.
|
83 | */
|
84 | method?: string;
|
85 | }
|
86 |
|
87 | export interface ResponseInit {
|
88 | headers?: HeadersInit;
|
89 | status?: number;
|
90 | statusText?: string;
|
91 | }
|
92 |
|
93 | type BodyInit =
|
94 | | Buffer
|
95 | | URLSearchParams
|
96 | | NodeJS.ReadableStream
|
97 | | string;
|
98 |
|
99 | export class Headers implements Iterable<[string, string]> {
|
100 | constructor(init?: HeadersInit);
|
101 |
|
102 | append(name: string, value: string): void;
|
103 | delete(name: string): void;
|
104 | get(name: string): string | null;
|
105 | has(name: string): boolean;
|
106 | set(name: string, value: string): void;
|
107 |
|
108 | raw(): Record<string, string | string[]>;
|
109 |
|
110 | entries(): Iterator<[string, string]>;
|
111 | keys(): Iterator<string>;
|
112 | values(): Iterator<string>;
|
113 | [Symbol.iterator](): Iterator<[string, string]>;
|
114 | }
|
115 |
|
116 | export class Body {
|
117 | constructor(body?: BodyInit);
|
118 |
|
119 | readonly body: NodeJS.ReadableStream | null;
|
120 | readonly bodyUsed: boolean;
|
121 |
|
122 | buffer(): Promise<Buffer>;
|
123 | arrayBuffer(): Promise<ArrayBuffer>;
|
124 | json(): Promise<unknown>;
|
125 | text(): Promise<string>;
|
126 | }
|
127 |
|
128 | type RequestInfo = string | Body;
|
129 |
|
130 | export class Request extends Body {
|
131 | constructor(input: RequestInfo, init?: RequestInit);
|
132 | readonly headers: Headers;
|
133 | readonly method: string;
|
134 | readonly url: string;
|
135 | }
|
136 |
|
137 | export class Response extends Body {
|
138 | constructor(body?: BodyInit | Object | null, init?: ResponseInit);
|
139 |
|
140 | readonly url: string;
|
141 | readonly status: number;
|
142 | readonly statusText: string;
|
143 | readonly ok: boolean;
|
144 | readonly redirected: boolean;
|
145 | readonly httpVersion: string;
|
146 | readonly decoded: boolean;
|
147 | headers: Headers;
|
148 |
|
149 | // non-spec extensions
|
150 | /**
|
151 | * A boolean specifying whether the response was retrieved from the cache.
|
152 | */
|
153 | readonly fromCache?: boolean;
|
154 | }
|
155 |
|
156 | export interface Http2Options {
|
157 | /**
|
158 | * Max idle time in milliseconds after which a session will be automatically closed.
|
159 | * @default 5 * 60 * 1000
|
160 | */
|
161 | idleSessionTimeout?: number;
|
162 | /**
|
163 | * Enable HTTP/2 Server Push?
|
164 | * @default true
|
165 | */
|
166 | enablePush?: boolean;
|
167 | /**
|
168 | * Max idle time in milliseconds after which a pushed stream will be automatically closed.
|
169 | * @default 5000
|
170 | */
|
171 | pushedStreamIdleTimeout?: number;
|
172 | /**
|
173 | * (HTTPS only)
|
174 | * If not false, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails; err.code contains the OpenSSL error code.
|
175 | * @default true
|
176 | */
|
177 | rejectUnauthorized?: boolean;
|
178 | }
|
179 |
|
180 | export interface ContextOptions {
|
181 | /**
|
182 | * Value of `user-agent` request header
|
183 | * @default 'adobe-fetch/<version>'
|
184 | */
|
185 | userAgent?: string;
|
186 | /**
|
187 | * The maximum total size of the cached entries (in bytes). 0 disables caching.
|
188 | * @default 100 * 1024 * 1024
|
189 | */
|
190 | maxCacheSize?: number;
|
191 | /**
|
192 | * The protocols to be negotiated, in order of preference
|
193 | * @default [ALPN_HTTP2, ALPN_HTTP1_1, ALPN_HTTP1_0]
|
194 | */
|
195 | alpnProtocols?: ReadonlyArray< ALPNProtocol >;
|
196 | /**
|
197 | * How long (in milliseconds) should ALPN information be cached for a given host?
|
198 | * @default 60 * 60 * 1000
|
199 | */
|
200 | alpnCacheTTL?: number;
|
201 | /**
|
202 | * Maximum number of ALPN cache entries
|
203 | * @default 100
|
204 | */
|
205 | alpnCacheSize?: number;
|
206 | /**
|
207 | * (HTTPS only, applies to HTTP/1.x and HTTP/2)
|
208 | * If not false, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails; err.code contains the OpenSSL error code.
|
209 | * @default true
|
210 | */
|
211 | rejectUnauthorized?: boolean;
|
212 |
|
213 | h1?: Http1Options;
|
214 | h2?: Http2Options;
|
215 | }
|
216 |
|
217 | export class AbortSignal {
|
218 | readonly aborted: boolean;
|
219 |
|
220 | addEventListener(type: 'abort', listener: (this: AbortSignal) => void): void;
|
221 | removeEventListener(type: 'abort', listener: (this: AbortSignal) => void): void;
|
222 | }
|
223 |
|
224 | export class TimeoutSignal extends AbortSignal {
|
225 | constructor(timeout: number);
|
226 |
|
227 | clear(): void;
|
228 | }
|
229 |
|
230 | export class AbortController {
|
231 | readonly signal: AbortSignal;
|
232 | abort(): void;
|
233 | }
|
234 |
|
235 | export interface RequestOptions {
|
236 | /**
|
237 | * A string specifying the HTTP request method.
|
238 | * @default 'GET'
|
239 | */
|
240 | method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'PATCH';
|
241 | /**
|
242 | * A Headers object, an object literal, or an array of two-item arrays to set request's headers.
|
243 | * @default {}
|
244 | */
|
245 | headers?: Headers | Object | Iterable<readonly [string, string]> | Iterable<Iterable<string>>;
|
246 | /**
|
247 | * The request's body.
|
248 | * @default null
|
249 | */
|
250 | body?: BodyInit | Object | FormData;
|
251 | /**
|
252 | * A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect.
|
253 | * @default 'follow'
|
254 | */
|
255 | redirect?: 'follow' | 'manual' | 'error';
|
256 | /**
|
257 | * A string indicating how the request will interact with the browser's cache to set request's cache.
|
258 | * @default 'default'
|
259 | */
|
260 | cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached';
|
261 | /**
|
262 | * An AbortSignal to set request's signal.
|
263 | * @default null
|
264 | */
|
265 | signal?: AbortSignal;
|
266 |
|
267 | // non-spec extensions
|
268 | /**
|
269 | * A boolean specifying support of gzip/deflate/brotli content encoding.
|
270 | * @default true
|
271 | */
|
272 | compress?: boolean;
|
273 | /**
|
274 | * A boolean specifying whether gzip/deflate/brotli-endoced content should be decoded.
|
275 | * @default true
|
276 | */
|
277 | decode?: boolean;
|
278 | /**
|
279 | * Maximum number of redirects to follow, 0 to not follow redirect.
|
280 | * @default 20
|
281 | */
|
282 | follow?: number;
|
283 | }
|
284 |
|
285 | // Errors
|
286 | export class FetchBaseError extends Error {
|
287 | type?: string;
|
288 | }
|
289 |
|
290 | export type SystemError = {
|
291 | address?: string;
|
292 | code: string;
|
293 | dest?: string;
|
294 | errno: number;
|
295 | info?: object;
|
296 | message: string;
|
297 | path?: string;
|
298 | port?: number;
|
299 | syscall: string;
|
300 | };
|
301 |
|
302 | export class FetchError extends FetchBaseError {
|
303 | code: string;
|
304 | errno?: number;
|
305 | erroredSysCall?: string;
|
306 | }
|
307 |
|
308 | export class AbortError extends FetchBaseError {
|
309 | type: 'aborted'
|
310 | }
|
311 |
|
312 | interface CacheStats {
|
313 | size: number;
|
314 | count: number;
|
315 | }
|
316 |
|
317 | export type PushHandler = (
|
318 | url: string,
|
319 | response: Response
|
320 | ) => void;
|
321 |
|
322 | /**
|
323 | * Fetches a resource from the network. Returns a Promise which resolves once
|
324 | * the response is available.
|
325 | *
|
326 | * @param {string|Request} url
|
327 | * @param {RequestOptions} [options]
|
328 | * @returns {Promise<Response>}
|
329 | * @throws {FetchError}
|
330 | * @throws {AbortError}
|
331 | * @throws {TypeError}
|
332 | */
|
333 | export function fetch(url: string|Request, options?: RequestOptions): Promise<Response>;
|
334 |
|
335 | /**
|
336 | * Resets the current context, i.e. disconnects all open/pending sessions, clears caches etc..
|
337 | */
|
338 | export function reset(): Promise<[void, void]>;
|
339 |
|
340 | /**
|
341 | * Register a callback which gets called once a server Push has been received.
|
342 | *
|
343 | * @param {PushHandler} fn callback function invoked with the url and the pushed Response
|
344 | */
|
345 | export function onPush(fn: PushHandler): void;
|
346 |
|
347 | /**
|
348 | * Deregister a callback previously registered with {#onPush}.
|
349 | *
|
350 | * @param {PushHandler} fn callback function registered with {#onPush}
|
351 | */
|
352 | export function offPush(fn: PushHandler): void;
|
353 |
|
354 | /**
|
355 | * Create a URL with query parameters
|
356 | *
|
357 | * @param {string} url request url
|
358 | * @param {object} [qs={}] request query parameters
|
359 | */
|
360 | export function createUrl(url: string, qs?: Record<string, unknown>): string;
|
361 |
|
362 | /**
|
363 | * Creates a timeout signal which allows to specify
|
364 | * a timeout for a `fetch` operation via the `signal` option.
|
365 | *
|
366 | * @param {number} ms timeout in milliseconds
|
367 | */
|
368 | export function timeoutSignal(ms: number): TimeoutSignal;
|
369 |
|
370 | /**
|
371 | * Clear the cache entirely, throwing away all values.
|
372 | */
|
373 | export function clearCache(): void;
|
374 |
|
375 | /**
|
376 | * Cache stats for diagnostic purposes
|
377 | */
|
378 | export function cacheStats(): CacheStats;
|