FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: http2 socket documentation, fix formatting · nodejs/node@9eff92c · GitHub

/ node Public

Commit 9eff92c

Browse files
apapirovski
committed
doc: http2 socket documentation, fix formatting
1 parent 9ac7ac9 commit 9eff92c

2 files changed

Lines changed: 69 additions & 34 deletions

File tree

‎doc/api/errors.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,12 @@ SETTINGS. By default, a maximum number of un-acknowledged `SETTINGS` frame may
796796
be sent at any given time. This error code is used when that limit has been
797797
reached.
798798

799+
<a id="ERR_HTTP2_NO_SOCKET_MANIPULATION"></a>
800+
### ERR_HTTP2_NO_SOCKET_MANIPULATION
801+
802+
Used when attempting to read, write, pause, and/or resume a socket attached to
803+
an `Http2Session`.
804+
799805
<a id="ERR_HTTP2_OUT_OF_STREAMS"></a>
800806
### ERR_HTTP2_OUT_OF_STREAMS
801807

‎doc/api/http2.md‎

Lines changed: 63 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2046,7 +2046,7 @@ console.log(request.headers);
20462046

20472047
See [Headers Object][].
20482048

2049-
### request.httpVersion
2049+
#### request.httpVersion
20502050
<!-- YAML
20512051
added: v8.4.0
20522052
-->
@@ -2117,7 +2117,14 @@ added: v8.4.0
21172117
* `msecs` {number}
21182118
* `callback` {Function}
21192119

2120-
Calls `request.connection.setTimeout(msecs, callback)`.
2120+
Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is
2121+
provided, then it is added as a listener on the `'timeout'` event on
2122+
the response object.
2123+
2124+
If no `'timeout'` listener is added to the request, the response, or
2125+
the server, then [`Http2Stream`]()s are destroyed when they time out. If a
2126+
handler is assigned to the request, the response, or the server's `'timeout'`
2127+
events, timed out sockets must be handled explicitly.
21212128

21222129
Returns `request`.
21232130

@@ -2128,13 +2135,24 @@ added: v8.4.0
21282135

21292136
* {net.Socket}
21302137

2131-
The [`net.Socket`][] object associated with the connection.
2138+
Returns a Proxy object that acts as a `net.Socket` but applies getters,
2139+
setters and methods based on HTTP/2 logic.
2140+
2141+
`destroyed`, `readable`, and `writable` properties will be retrieved from and
2142+
set on `request.stream`.
21322143

2133-
With TLS support, use [`request.socket.getPeerCertificate()`][] to obtain the
2134-
client's authentication details.
2144+
`destroy`, `emit`, `end`, `on` and `once` methods will be called on
2145+
`request.stream`.
21352146

2136-
*Note*: do not use this socket object to send or receive any data. All
2137-
data transfers are managed by HTTP/2 and data might be lost.
2147+
`setTimeout` method will be called on `request.stream.session`.
2148+
2149+
`pause`, `read`, `resume`, and `write` will throw an error with code
2150+
`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [`Http2Session and Sockets`][] for
2151+
more information.
2152+
2153+
All other interactions will be routed directly to the socket. With TLS support,
2154+
use [`request.socket.getPeerCertificate()`][] to obtain the client's
2155+
authentication details.
21382156

21392157
#### request.stream
21402158
<!-- YAML
@@ -2232,15 +2250,15 @@ passed as the second parameter to the [`'request'`][] event.
22322250
The response implements, but does not inherit from, the [Writable Stream][]
22332251
interface. This is an [`EventEmitter`][] with the following events:
22342252

2235-
### Event: 'close'
2253+
#### Event: 'close'
22362254
<!-- YAML
22372255
added: v8.4.0
22382256
-->
22392257

22402258
Indicates that the underlying [`Http2Stream`]() was terminated before
22412259
[`response.end()`][] was called or able to flush.
22422260

2243-
### Event: 'finish'
2261+
#### Event: 'finish'
22442262
<!-- YAML
22452263
added: v8.4.0
22462264
-->
@@ -2252,7 +2270,7 @@ does not imply that the client has received anything yet.
22522270

22532271
After this event, no more events will be emitted on the response object.
22542272

2255-
### response.addTrailers(headers)
2273+
#### response.addTrailers(headers)
22562274
<!-- YAML
22572275
added: v8.4.0
22582276
-->
@@ -2265,7 +2283,7 @@ message) to the response.
22652283
Attempting to set a header field name or value that contains invalid characters
22662284
will result in a [`TypeError`][] being thrown.
22672285

2268-
### response.connection
2286+
#### response.connection
22692287
<!-- YAML
22702288
added: v8.4.0
22712289
-->
@@ -2274,7 +2292,7 @@ added: v8.4.0
22742292

22752293
See [`response.socket`][].
22762294

2277-
### response.end([data][, encoding][, callback])
2295+
#### response.end([data][, encoding][, callback])
22782296
<!-- YAML
22792297
added: v8.4.0
22802298
-->
@@ -2293,7 +2311,7 @@ If `data` is specified, it is equivalent to calling
22932311
If `callback` is specified, it will be called when the response stream
22942312
is finished.
22952313

2296-
### response.finished
2314+
#### response.finished
22972315
<!-- YAML
22982316
added: v8.4.0
22992317
-->
@@ -2303,7 +2321,7 @@ added: v8.4.0
23032321
Boolean value that indicates whether the response has completed. Starts
23042322
as `false`. After [`response.end()`][] executes, the value will be `true`.
23052323

2306-
### response.getHeader(name)
2324+
#### response.getHeader(name)
23072325
<!-- YAML
23082326
added: v8.4.0
23092327
-->
@@ -2320,7 +2338,7 @@ Example:
23202338
const contentType = response.getHeader('content-type');
23212339
```
23222340

2323-
### response.getHeaderNames()
2341+
#### response.getHeaderNames()
23242342
<!-- YAML
23252343
added: v8.4.0
23262344
-->
@@ -2340,7 +2358,7 @@ const headerNames = response.getHeaderNames();
23402358
// headerNames === ['foo', 'set-cookie']
23412359
```
23422360

2343-
### response.getHeaders()
2361+
#### response.getHeaders()
23442362
<!-- YAML
23452363
added: v8.4.0
23462364
-->
@@ -2368,7 +2386,7 @@ const headers = response.getHeaders();
23682386
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }
23692387
```
23702388

2371-
### response.hasHeader(name)
2389+
#### response.hasHeader(name)
23722390
<!-- YAML
23732391
added: v8.4.0
23742392
-->
@@ -2385,7 +2403,7 @@ Example:
23852403
const hasContentType = response.hasHeader('content-type');
23862404
```
23872405

2388-
### response.headersSent
2406+
#### response.headersSent
23892407
<!-- YAML
23902408
added: v8.4.0
23912409
-->
@@ -2394,7 +2412,7 @@ added: v8.4.0
23942412

23952413
Boolean (read-only). True if headers were sent, false otherwise.
23962414

2397-
### response.removeHeader(name)
2415+
#### response.removeHeader(name)
23982416
<!-- YAML
23992417
added: v8.4.0
24002418
-->
@@ -2409,7 +2427,7 @@ Example:
24092427
response.removeHeader('Content-Encoding');
24102428
```
24112429

2412-
### response.sendDate
2430+
#### response.sendDate
24132431
<!-- YAML
24142432
added: v8.4.0
24152433
-->
@@ -2422,7 +2440,7 @@ the response if it is not already present in the headers. Defaults to true.
24222440
This should only be disabled for testing; HTTP requires the Date header
24232441
in responses.
24242442

2425-
### response.setHeader(name, value)
2443+
#### response.setHeader(name, value)
24262444
<!-- YAML
24272445
added: v8.4.0
24282446
-->
@@ -2463,7 +2481,7 @@ const server = http2.createServer((req, res) => {
24632481
});
24642482
```
24652483

2466-
### response.setTimeout(msecs[, callback])
2484+
#### response.setTimeout(msecs[, callback])
24672485
<!-- YAML
24682486
added: v8.4.0
24692487
-->
@@ -2482,18 +2500,29 @@ events, timed out sockets must be handled explicitly.
24822500

24832501
Returns `response`.
24842502

2485-
### response.socket
2503+
#### response.socket
24862504
<!-- YAML
24872505
added: v8.4.0
24882506
-->
24892507

24902508
* {net.Socket}
24912509

2492-
Reference to the underlying socket. Usually users will not want to access
2493-
this property. In particular, the socket will not emit `'readable'` events
2494-
because of how the protocol parser attaches to the socket. After
2495-
`response.end()`, the property is nulled. The `socket` may also be accessed
2496-
via `response.connection`.
2510+
Returns a Proxy object that acts as a `net.Socket` but applies getters,
2511+
setters and methods based on HTTP/2 logic.
2512+
2513+
`destroyed`, `readable`, and `writable` properties will be retrieved from and
2514+
set on `response.stream`.
2515+
2516+
`destroy`, `emit`, `end`, `on` and `once` methods will be called on
2517+
`response.stream`.
2518+
2519+
`setTimeout` method will be called on `response.stream.session`.
2520+
2521+
`pause`, `read`, `resume`, and `write` will throw an error with code
2522+
`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [`Http2Session and Sockets`][] for
2523+
more information.
2524+
2525+
All other interactions will be routed directly to the socket.
24972526

24982527
Example:
24992528

@@ -2506,7 +2535,7 @@ const server = http2.createServer((req, res) => {
25062535
}).listen(3000);
25072536
```
25082537

2509-
### response.statusCode
2538+
#### response.statusCode
25102539
<!-- YAML
25112540
added: v8.4.0
25122541
-->
@@ -2526,7 +2555,7 @@ response.statusCode = 404;
25262555
After response header was sent to the client, this property indicates the
25272556
status code which was sent out.
25282557

2529-
### response.statusMessage
2558+
#### response.statusMessage
25302559
<!-- YAML
25312560
added: v8.4.0
25322561
-->
@@ -2545,7 +2574,7 @@ added: v8.4.0
25452574

25462575
The [`Http2Stream`][] object backing the response.
25472576

2548-
### response.write(chunk[, encoding][, callback])
2577+
#### response.write(chunk[, encoding][, callback])
25492578
<!-- YAML
25502579
added: v8.4.0
25512580
-->
@@ -2583,7 +2612,7 @@ Returns `true` if the entire data was flushed successfully to the kernel
25832612
buffer. Returns `false` if all or part of the data was queued in user memory.
25842613
`'drain'` will be emitted when the buffer is free again.
25852614

2586-
### response.writeContinue()
2615+
#### response.writeContinue()
25872616
<!-- YAML
25882617
added: v8.4.0
25892618
-->
@@ -2592,7 +2621,7 @@ Sends a status `100 Continue` to the client, indicating that the request body
25922621
should be sent. See the [`'checkContinue'`][] event on `Http2Server` and
25932622
`Http2SecureServer`.
25942623

2595-
### response.writeHead(statusCode[, statusMessage][, headers])
2624+
#### response.writeHead(statusCode[, statusMessage][, headers])
25962625
<!-- YAML
25972626
added: v8.4.0
25982627
-->
@@ -2648,7 +2677,7 @@ const server = http2.createServer((req, res) => {
26482677
Attempting to set a header field name or value that contains invalid characters
26492678
will result in a [`TypeError`][] being thrown.
26502679

2651-
### response.createPushResponse(headers, callback)
2680+
#### response.createPushResponse(headers, callback)
26522681
<!-- YAML
26532682
added: v8.4.0
26542683
-->

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL