@@ -2233,6 +2233,378 @@ URL {
2233
2233
}
2234
2234
```
2235
2235
2236
+ ## Class: ` http.OutgoingMessage `
2237
+ <!-- YAML
2238
+ added: v0.1.17
2239
+ -->
2240
+
2241
+ * Extends: {Stream}
2242
+
2243
+ This class serves as the parent class of [ ` http.ClientRequest ` ] [ ]
2244
+ and [ ` http.ServerResponse ` ] [ ] . It is an abstract of outgoing message from
2245
+ the perspective of the participants of HTTP transaction.
2246
+
2247
+ ### Event: ` drain `
2248
+ <!-- YAML
2249
+ added: v0.3.6
2250
+ -->
2251
+
2252
+ Emitted when the buffer of the message is free again.
2253
+
2254
+ ### Event: ` finish `
2255
+ <!-- YAML
2256
+ added: v0.1.17
2257
+ -->
2258
+
2259
+ Emitted when transmission is finished successfully.
2260
+
2261
+ ### Event: ` prefinish `
2262
+ <!-- YAML
2263
+ added: v0.11.6
2264
+ -->
2265
+
2266
+ Emitted when ` outgoingMessage.end ` was called.
2267
+ When the event is emitted, all data has been processed but not necessarily
2268
+ completely flushed.
2269
+
2270
+ ### ` outgoingMessage.addTrailers(headers) `
2271
+ <!-- YAML
2272
+ added: v0.3.0
2273
+ -->
2274
+
2275
+ * ` headers ` {Object}
2276
+
2277
+ Adds HTTP trailers (headers but at the end of the message) to the message.
2278
+
2279
+ Trailers are ** only** be emitted if the message is chunked encoded. If not,
2280
+ trailer will be silently discarded.
2281
+
2282
+ HTTP requires the ` Trailer ` header to be sent in order to emit trailers,
2283
+ with a list of header fields in its value, e.g.
2284
+
2285
+ ``` js
2286
+ message .writeHead (200 , { ' Content-Type' : ' text/plain' ,
2287
+ ' Trailer' : ' Content-MD5' });
2288
+ message .write (fileData);
2289
+ message .addTrailers ({ ' Content-MD5' : ' 7895bf4b8828b55ceaf47747b4bca667' });
2290
+ message .end ();
2291
+ ```
2292
+
2293
+ Attempting to set a header field name or value that contains invalid characters
2294
+ will result in a ` TypeError ` being thrown.
2295
+
2296
+ ### ` outgoingMessage.connection `
2297
+ <!-- YAML
2298
+ added: v0.3.0
2299
+ deprecated: REPLACEME
2300
+ -->
2301
+
2302
+ > Stability: 0 - Deprecated: Use [ ` outgoingMessage.socket ` ] [ ] instead.
2303
+
2304
+ Aliases of ` outgoingMessage.socket `
2305
+ ### ` outgoingMessage.cork() `
2306
+ <!-- YAML
2307
+ added: v14.0.0
2308
+ -->
2309
+
2310
+ See [ ` writable.cork() ` ] [ ] .
2311
+
2312
+ ### ` outgoingMessage.destroy([error]) `
2313
+ <!-- YAML
2314
+ added: v0.3.0
2315
+ -->
2316
+
2317
+ * ` error ` {Error} Optional, an error to emit with ` error ` event
2318
+ * Returns: {this}
2319
+
2320
+ Destroys the message. Once a socket is associated with the message
2321
+ and is connected, that socket will be destroyed as well.
2322
+
2323
+ ### ` outgoingMessage.end(chunk[, encoding][, callback]) `
2324
+ <!-- YAML
2325
+ added: v0.1.90
2326
+ changes:
2327
+ - version: v0.11.6
2328
+ description: add `callback` argument.
2329
+ -->
2330
+
2331
+ * ` chunk ` {string | Buffer}
2332
+ * ` encoding ` {string} Optional, ** Default** : ` utf-8 `
2333
+ * ` callback ` {Function} Optional
2334
+ * Returns: {this}
2335
+
2336
+ Finishes the outgoing message. If any parts of the body are unsent, it will
2337
+ flush them to the underlying system. If the message is chunked, it will
2338
+ send the terminating chunk ` 0\r\n\r\n ` , and send the trailer (if any).
2339
+
2340
+ If ` chunk ` is specified, it is equivalent to call
2341
+ ` outgoingMessage.write(chunk, encoding) ` , followed by
2342
+ ` outgoingMessage.end(callback) ` .
2343
+
2344
+ If ` callback ` is provided, it will be called when the message is finished.
2345
+ (equivalent to the callback to event ` finish ` )
2346
+
2347
+ ### ` outgoingMessage.flushHeaders() `
2348
+ <!-- YAML
2349
+ added: v1.6.0
2350
+ -->
2351
+
2352
+ Compulsorily flushes the message headers
2353
+
2354
+ For efficiency reason, Node.js normally buffers the message headers
2355
+ until ` outgoingMessage.end() ` is called or the first chunk of message data
2356
+ is written. It then tries to pack the headers and data into a single TCP
2357
+ packet.
2358
+
2359
+ It is usually desired (it saves a TCP round-trip), but not when the first
2360
+ data is not sent until possibly much later. ` outgoingMessage.flushHeaders() `
2361
+ bypasses the optimization and kickstarts the request.
2362
+
2363
+ ### ` outgoingMessage.getHeader(name) `
2364
+ <!-- YAML
2365
+ added: v0.4.0
2366
+ -->
2367
+
2368
+ * ` name ` {string} Name of header
2369
+ * Returns {string | undefined}
2370
+
2371
+ Gets value of HTTP header with given name. If such name doesn't exist in
2372
+ message, it will be ` undefined ` .
2373
+
2374
+ ### ` outgoingMessage.getHeaderNames() `
2375
+ <!-- YAML
2376
+ added: v8.0.0
2377
+ -->
2378
+
2379
+ * Returns {string[ ] }
2380
+
2381
+ Returns an array of names of headers of the outgoing outgoingMessage. All
2382
+ names are lowercase.
2383
+
2384
+ ### ` outgoingMessage.getHeaders() `
2385
+ <!-- YAML
2386
+ added: v8.0.0
2387
+ -->
2388
+
2389
+ * Returns: {Object}
2390
+
2391
+ Returns a shallow copy of the current outgoing headers. Since a shallow
2392
+ copy is used, array values may be mutated without additional calls to
2393
+ various header-related http module methods. The keys of the returned
2394
+ object are the header names and the values are the respective header
2395
+ values. All header names are lowercase.
2396
+
2397
+ The object returned by the ` outgoingMessage.getHeaders() ` method does
2398
+ not prototypically inherit from the JavaScript Object. This means that
2399
+ typical Object methods such as ` obj.toString() ` , ` obj.hasOwnProperty() ` ,
2400
+ and others are not defined and will not work.
2401
+
2402
+ ``` js
2403
+ outgoingMessage .setHeader (' Foo' , ' bar' );
2404
+ outgoingMessage .setHeader (' Set-Cookie' , [' foo=bar' , ' bar=baz' ]);
2405
+
2406
+ const headers = outgoingMessage .getHeaders ();
2407
+ // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }
2408
+ ```
2409
+
2410
+ ### ` outgoingMessage.hasHeader(name) `
2411
+ <!-- YAML
2412
+ added: v8.0.0
2413
+ -->
2414
+
2415
+ * ` name ` {string}
2416
+ * Returns {boolean}
2417
+
2418
+ Returns ` true ` if the header identified by ` name ` is currently set in the
2419
+ outgoing headers. The header name is case-insensitive.
2420
+
2421
+ ``` js
2422
+ const hasContentType = outgoingMessage .hasHeader (' content-type' );
2423
+ ```
2424
+
2425
+ ### ` outgoingMessage.headersSent `
2426
+ <!-- YAML
2427
+ added: v0.9.3
2428
+ -->
2429
+
2430
+ * {boolean}
2431
+
2432
+ Read-only. ` true ` if the headers were sent, otherwise ` false ` .
2433
+
2434
+ ### ` outgoingMessage.pipe() `
2435
+ <!-- YAML
2436
+ added: v9.0.0
2437
+ -->
2438
+
2439
+ Overrides the pipe method of legacy ` Stream ` which is the parent class of
2440
+ ` http.outgoingMessage ` .
2441
+
2442
+ Since ` OutgoingMessage ` should be a write-only stream,
2443
+ call this function will throw an ` Error ` . Thus, it disabled the pipe method
2444
+ it inherits from ` Stream ` .
2445
+
2446
+ User should not call this function directly.
2447
+
2448
+ ### ` outgoingMessage.removeHeader() `
2449
+ <!-- YAML
2450
+ added: v0.4.0
2451
+ -->
2452
+
2453
+ Removes a header that is queued for implicit sending.
2454
+
2455
+ ``` js
2456
+ outgoingMessage .removeHeader (' Content-Encoding' );
2457
+ ```
2458
+
2459
+ ### ` outgoingMessage.setHeader(name, value) `
2460
+ <!-- YAML
2461
+ added: v0.4.0
2462
+ -->
2463
+
2464
+ * ` name ` {string} Header name
2465
+ * ` value ` {string} Header value
2466
+ * Returns: {this}
2467
+
2468
+ Sets a single header value for header object.
2469
+
2470
+ ### ` outgoingMessage.setTimeout(msesc[, callback]) `
2471
+ <!-- YAML
2472
+ added: v0.9.12
2473
+ -->
2474
+
2475
+ * ` msesc ` {number}
2476
+ * ` callback ` {Function} Optional function to be called when a timeout
2477
+ occurs, Same as binding to the ` timeout ` event.
2478
+ * Returns: {this}
2479
+
2480
+ Once a socket is associated with the message and is connected,
2481
+ [ ` socket.setTimeout() ` ] [ ] will be called with ` msecs ` as the first parameter.
2482
+
2483
+ ### ` outgoingMessage.socket `
2484
+ <!-- YAML
2485
+ added: v0.3.0
2486
+ -->
2487
+
2488
+ * {stream.Duplex}
2489
+
2490
+ Reference to the underlying socket. Usually users will not want to access
2491
+ this property.
2492
+
2493
+ After calling ` outgoingMessage.end() ` , this property will be nulled.
2494
+
2495
+ ### ` outgoingMessage.uncork() `
2496
+ <!-- YAML
2497
+ added: v14.0.0
2498
+ -->
2499
+
2500
+ See [ ` writable.uncork() ` ] [ ]
2501
+
2502
+ ### ` outgoingMessage.writableCorked `
2503
+ <!-- YAML
2504
+ added: v14.0.0
2505
+ -->
2506
+
2507
+ * {number}
2508
+
2509
+ This ` outgoingMessage.writableCorked ` will return the time how many
2510
+ ` outgoingMessage.cork() ` have been called.
2511
+
2512
+ ### ` outgoingMessage.writableEnded `
2513
+ <!-- YAML
2514
+ added: v13.0.0
2515
+ -->
2516
+
2517
+ * {boolean}
2518
+
2519
+ Readonly, ` true ` if ` outgoingMessage.end() ` has been called. Noted that
2520
+ this property does not reflect whether the data has been flush. For that
2521
+ purpose, use ` message.writableFinished ` instead.
2522
+
2523
+ ### ` outgoingMessage.writableFinished `
2524
+ <!-- YAML
2525
+ added: v13.0.0
2526
+ -->
2527
+
2528
+ * {boolean}
2529
+
2530
+ Readonly. ` true ` if all data has been flushed to the underlying system.
2531
+
2532
+ ### ` outgoingMessage.writableHighWaterMark `
2533
+ <!-- YAML
2534
+ added: v13.0.0
2535
+ -->
2536
+
2537
+ * {number}
2538
+
2539
+ This ` outgoingMessage.writableHighWaterMark ` will be the ` highWaterMark ` of
2540
+ underlying socket if socket exists. Else, it would be the default
2541
+ ` highWaterMark ` .
2542
+
2543
+ ` highWaterMark ` is the maximum amount of data which can be potentially
2544
+ buffered by socket.
2545
+
2546
+ ### ` outgoingMessage.writableLength `
2547
+ <!-- YAML
2548
+ added: v13.0.0
2549
+ -->
2550
+
2551
+ * {number}
2552
+
2553
+ Readonly, This ` outgoingMessage.writableLength ` contains the number of
2554
+ bytes (or objects) in the buffer ready to send.
2555
+
2556
+ ### ` outgoingMessage.writableObjectMode `
2557
+ <!-- YAML
2558
+ added: v13.0.0
2559
+ -->
2560
+
2561
+ * {boolean}
2562
+
2563
+ Readonly, always returns ` false ` .
2564
+
2565
+ ### ` outgoingMessage.write(chunk[, encoding][, callback]) `
2566
+ <!-- YAML
2567
+ added: v0.1.29
2568
+ changes:
2569
+ - version: v0.11.6
2570
+ description: add `callback` argument.
2571
+ -->
2572
+
2573
+ * ` chunk ` {string | Buffer}
2574
+ * ` encoding ` {string} ** Default** : ` utf-8 `
2575
+ * ` callback ` {Function}
2576
+ * Returns {boolean}
2577
+
2578
+ If this method is called and header is not sent, it will call
2579
+ ` this._implicitHeader ` to flush implicit header.
2580
+ If the message should not have a body (indicated by ` this._hasBody ` ),
2581
+ the call is ignored and ` chunk ` will not be sent. It could be useful
2582
+ when handling particular message which must not include a body.
2583
+ e.g. response to ` HEAD ` request, ` 204 ` and ` 304 ` response.
2584
+
2585
+ ` chunk ` can be a string or a buffer. When ` chunk ` is a string, the
2586
+ ` encoding ` parameter specifies how to encode ` chunk ` into a byte stream.
2587
+ ` callback ` will be called when the ` chunk ` is flushed.
2588
+
2589
+ If the message is transferred in chucked encoding
2590
+ (indicated by ` this.chunkedEncoding ` ), ` chunk ` will be flushed as
2591
+ one chunk among a stream of chunks. Otherwise, it will be flushed as body
2592
+ of message.
2593
+
2594
+ This method handles the raw body of HTTP message and has nothing to do with
2595
+ higher-level multi-part body encodings that may be used.
2596
+
2597
+ If it is the first call to this method of a message, it will send the
2598
+ buffered header first, then flush the the ` chunk ` as described above.
2599
+
2600
+ The second and successive calls to this method, it will assume the data
2601
+ will streamed and send the new data separately. It means that the response
2602
+ is buffered up to the first chunk of the body.
2603
+
2604
+ Returns ` true ` if the entire data was flushed successfully to the kernel
2605
+ buffer. Returns ` false ` if all or part of the data was queued in user
2606
+ memory. Event ` drain ` will be emitted when the buffer is free again.
2607
+
2236
2608
## ` http.METHODS `
2237
2609
<!-- YAML
2238
2610
added: v0.11.8
@@ -2758,6 +3130,7 @@ try {
2758
3130
[ `http.ClientRequest` ] : #http_class_http_clientrequest
2759
3131
[ `http.IncomingMessage` ] : #http_class_http_incomingmessage
2760
3132
[ `http.Server` ] : #http_class_http_server
3133
+ [ `http.ServerResponse` ] : #http_class_http_serverresponse
2761
3134
[ `http.get()` ] : #http_http_get_options_callback
2762
3135
[ `http.globalAgent` ] : #http_http_globalagent
2763
3136
[ `http.request()` ] : #http_http_request_options_callback
@@ -2768,6 +3141,7 @@ try {
2768
3141
[ `net.createConnection()` ] : net.md#net_net_createconnection_options_connectlistener
2769
3142
[ `new URL()` ] : url.md#url_new_url_input_base
2770
3143
[ `message.socket` ] : #http_message_socket
3144
+ [ `outgoingMessage.socket` ] : #http_outgoingMessage.socket
2771
3145
[ `removeHeader(name)` ] : #http_request_removeheader_name
2772
3146
[ `request.end()` ] : #http_request_end_data_encoding_callback
2773
3147
[ `request.destroy()` ] : #http_request_destroy_error
0 commit comments