bahman/ws
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[doc] Add punctuation for readability (#2213)

Browse Source
This commit is contained in:
Jana R
2024-03-29 17:23:43 +05:30
committed by GitHub
parent 8be840e0a9
commit 2405c17775
3 changed files with 38 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@@ -11,8 +11,8 @@ Passes the quite extensive Autobahn test suite: [server][server-report],
[client][client-report].
**Note**: This module does not work in the browser. The client in the docs is a
reference to a back end with the role of a client in the WebSocket
communication. Browser clients must use the native
reference to a backend with the role of a client in the WebSocket communication.
Browser clients must use the native
[`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
object. To make the same code work seamlessly on Node.js and the browser, you
can use one of the many wrappers available on npm, like
@@ -87,7 +87,7 @@ npm install --save-optional utf-8-validate
This contains a binary polyfill for [`buffer.isUtf8()`][].
To force ws to not use utf-8-validate, use the
To force ws not to use utf-8-validate, use the
[`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment variable.
## API docs
@@ -146,7 +146,7 @@ const wss = new WebSocketServer({
```
The client will only use the extension if it is supported and enabled on the
server. To always disable the extension on the client set the
server. To always disable the extension on the client, set the
`perMessageDeflate` option to `false`.
```js
@@ -451,11 +451,11 @@ wss.on('connection', function connection(ws, req) {
### How to detect and close broken connections?
Sometimes the link between the server and the client can be interrupted in a way
that keeps both the server and the client unaware of the broken state of the
Sometimes, the link between the server and the client can be interrupted in a
way that keeps both the server and the client unaware of the broken state of the
connection (e.g. when pulling the cord).
In these cases ping messages can be used as a means to verify that the remote
In these cases, ping messages can be used as a means to verify that the remote
endpoint is still responsive.
```js
@@ -490,7 +490,7 @@ wss.on('close', function close() {
Pong messages are automatically sent in response to ping messages as required by
the spec.
Just like the server example above your clients might as well lose connection
Just like the server example above, your clients might as well lose connection
without knowing it. You might want to add a ping listener on your clients to
prevent that. A simple implementation would be:

14
SECURITY.md
View File

@@ -12,21 +12,21 @@ blocked instantly.
## Exceptions
If you do not receive an acknowledgement within the said time frame please give
If you do not receive an acknowledgement within the said time frame, please give
us the benefit of the doubt as it's possible that we haven't seen it yet. In
this case please send us a message **without details** using one of the
this case, please send us a message **without details** using one of the
following methods:
- Contact the lead developers of this project on their personal e-mails. You can
find the e-mails in the git logs, for example using the following command:
find the e-mails in the git logs, for example, using the following command:
`git --no-pager show -s --format='%an <%ae>' <gitsha>` where `<gitsha>` is the
SHA1 of their latest commit in the project.
- Create a GitHub issue stating contact details and the severity of the issue.
Once we have acknowledged receipt of your report and confirmed the bug ourselves
we will work with you to fix the vulnerability and publicly acknowledge your
responsible disclosure, if you wish. In addition to that we will create and
publish a security advisory to
Once we have acknowledged receipt of your report and confirmed the bug
ourselves, we will work with you to fix the vulnerability and publicly
acknowledge your responsible disclosure, if you wish. In addition to that, we
will create and publish a security advisory to
[GitHub Security Advisories](https://github.com/websockets/ws/security/advisories?state=published).
## History

46
doc/ws.md
View File

@@ -103,7 +103,7 @@ This class represents a WebSocket server. It extends the `EventEmitter`.
Create a new server instance. One and only one of `port`, `server` or `noServer`
must be provided or an error is thrown. An HTTP server is automatically created,
started, and used if `port` is set. To use an external HTTP/S server instead,
specify only `server` or `noServer`. In this case the HTTP/S server must be
specify only `server` or `noServer`. In this case, the HTTP/S server must be
started manually. The "noServer" mode allows the WebSocket server to be
completely detached from the HTTP/S server. This makes it possible, for example,
to share a single HTTP/S server between multiple WebSocket servers.
@@ -112,8 +112,8 @@ to share a single HTTP/S server between multiple WebSocket servers.
> authentication in the `'upgrade'` event of the HTTP server. See examples for
> more details.
If `verifyClient` is not set then the handshake is automatically accepted. If it
has a single parameter then `ws` will invoke it with the following argument:
If `verifyClient` is not set, then the handshake is automatically accepted. If
it has a single parameter, then `ws` will invoke it with the following argument:
- `info` {Object}
- `origin` {String} The value in the Origin header indicated by the client.
@@ -124,19 +124,19 @@ has a single parameter then `ws` will invoke it with the following argument:
The return value (`Boolean`) of the function determines whether or not to accept
the handshake.
If `verifyClient` has two parameters then `ws` will invoke it with the following
arguments:
If `verifyClient` has two parameters, then `ws` will invoke it with the
following arguments:
- `info` {Object} Same as above.
- `cb` {Function} A callback that must be called by the user upon inspection of
the `info` fields. Arguments in this callback are:
- `result` {Boolean} Whether or not to accept the handshake.
- `code` {Number} When `result` is `false` this field determines the HTTP
- `code` {Number} When `result` is `false`, this field determines the HTTP
error status code to be sent to the client.
- `name` {String} When `result` is `false` this field determines the HTTP
- `name` {String} When `result` is `false`, this field determines the HTTP
reason phrase.
- `headers` {Object} When `result` is `false` this field determines additional
HTTP headers to be sent to the client. For example,
- `headers` {Object} When `result` is `false`, this field determines
additional HTTP headers to be sent to the client. For example,
`{ 'Retry-After': 120 }`.
`handleProtocols` takes two arguments:
@@ -146,15 +146,15 @@ arguments:
- `request` {http.IncomingMessage} The client HTTP GET request.
The returned value sets the value of the `Sec-WebSocket-Protocol` header in the
HTTP 101 response. If returned value is `false` the header is not added in the
HTTP 101 response. If returned value is `false`, the header is not added in the
response.
If `handleProtocols` is not set then the first of the client's requested
If `handleProtocols` is not set, then the first of the client's requested
subprotocols is used.
`perMessageDeflate` can be used to control the behavior of [permessage-deflate
extension][permessage-deflate]. The extension is disabled when `false` (default
value). If an object is provided then that is extension parameters:
value). If an object is provided, then that is extension parameters:
- `serverNoContextTakeover` {Boolean} Whether to use context takeover or not.
- `clientNoContextTakeover` {Boolean} Acknowledge disabling of client context
@@ -171,8 +171,8 @@ value). If an object is provided then that is extension parameters:
above this limit will be queued. Default 10. You usually won't need to touch
this option. See [this issue][concurrency-limit] for more details.
If a property is empty then either an offered configuration or a default value
is used. When sending a fragmented message the length of the first fragment is
If a property is empty, then either an offered configuration or a default value
is used. When sending a fragmented message, the length of the first fragment is
compared to the threshold. This determines if compression is used for the entire
message.
@@ -248,7 +248,7 @@ created internally. If an external HTTP server is used via the `server` or
`noServer` constructor options, it must be closed manually. Existing connections
are not closed automatically. The server emits a `'close'` event when all
connections are closed unless an external HTTP server is used and client
tracking is disabled. In this case the `'close'` event is emitted in the next
tracking is disabled. In this case, the `'close'` event is emitted in the next
tick. The optional callback is called when the `'close'` event occurs and
receives an `Error` if the server is already closed.
@@ -273,7 +273,7 @@ If the upgrade is successful, the `callback` is called with two arguments:
- `request` {http.IncomingMessage} The client HTTP GET request.
See if a given request should be handled by this server. By default this method
See if a given request should be handled by this server. By default, this method
validates the pathname of the request, matching it against the `path` option if
provided. The return value, `true` or `false`, determines whether or not to
accept the handshake.
@@ -305,12 +305,12 @@ This class represents a WebSocket. It extends the `EventEmitter`.
tick. To improve compatibility with the WHATWG standard, the default value
is `false`. Setting it to `true` improves performance slightly.
- `finishRequest` {Function} A function which can be used to customize the
headers of each http request before it is sent. See description below.
headers of each HTTP request before it is sent. See description below.
- `followRedirects` {Boolean} Whether or not to follow redirects. Defaults to
`false`.
- `generateMask` {Function} The function used to generate the masking key. It
takes a `Buffer` that must be filled synchronously and is called before a
message is sent, for each message. By default the buffer is filled with
message is sent, for each message. By default, the buffer is filled with
cryptographically strong random bytes.
- `handshakeTimeout` {Number} Timeout in milliseconds for the handshake
request. This is reset after every redirection.
@@ -343,7 +343,7 @@ context takeover.
for each HTTP GET request (the initial one and any caused by redirects) when it
is ready to be sent, to allow for last minute customization of the headers. If
`finishRequest` is set then it has the responsibility to call `request.end()`
`finishRequest` is set, then it has the responsibility to call `request.end()`
once it is done setting request headers. This is intended for niche use-cases
where some headers can't be provided in advance e.g. because they depend on the
underlying socket.
@@ -479,7 +479,7 @@ The number of bytes of data that have been queued using calls to `send()` but
not yet transmitted to the network. This deviates from the HTML standard in the
following ways:
1. If the data is immediately sent the value is `0`.
1. If the data is immediately sent, the value is `0`.
1. All framing bytes are included.
### websocket.close([code[, reason]])
@@ -610,7 +610,7 @@ state is `CONNECTING`.
### websocket.terminate()
Forcibly close the connection. Internally this calls [`socket.destroy()`][].
Forcibly close the connection. Internally, this calls [`socket.destroy()`][].
### websocket.url
@@ -631,12 +631,12 @@ given `WebSocket`.
### WS_NO_BUFFER_UTIL
When set to a non empty value, prevents the optional `bufferutil` dependency
When set to a non-empty value, prevents the optional `bufferutil` dependency
from being required.
### WS_NO_UTF_8_VALIDATE
When set to a non empty value, prevents the optional `utf-8-validate` dependency
When set to a non-empty value, prevents the optional `utf-8-validate` dependency
from being required.
## Error codes