fixed TLSSocket documentation error from Issue #3963. #14062

VerteDinde · 2017-07-03T17:04:10Z

#Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

This PR affects the documentation for TLSSocket and new.Socket, and references Issue #3963. See line 879 - 902 in doc/api/tls.md. Let me know if I should make any changes! #3963

…02 in doc/api/tls.md

tniessen · 2017-07-03T17:13:08Z

Thank you for your contribution! To start off, head over to our style guide. For example, you should

Generally avoid personal pronouns in reference documentation ("I", "you", "we").

tniessen

Regardless of the technical contents, here are some basic suggestions for improval 😃

tniessen · 2017-07-03T17:21:40Z

doc/api/tls.md

@@ -876,6 +876,30 @@ socket.on('end', () => {
 });
 ```

+Note: When using an instance of `net.Socket`, you start the `net.Socket`. You can use `net.Socket` to upgrade an existing socket you don't wrap the `net.Socket` in a `TLSSocket`, then the connect works as expected.


Avoid using you (see my comment above).

There is a grammar mistake in the second sentence: "You can use net.Socket to upgrade an existing socket ??? you don't wrap the..."

tniessen · 2017-07-03T17:21:43Z

doc/api/tls.md

+See the example below for usage of upgrading an existing socket with `net.Socket`:
+
+```js
+var Socket = require('net').Socket;


Use const instead of var where applicable.

tniessen · 2017-07-03T17:24:40Z

doc/api/tls.md

+var secureSock = tls.connect({ socket: s }, function() {
+  console.log("The tls socket connected. Yay!");
+});
+sock.connect({port: 6697, host: "irc.freenode.net"});


Style nits: Use 'foo' instead of "foo" and put spaces around the properties like { foo: 'bar' }.

tniessen · 2017-07-03T17:24:42Z

doc/api/tls.md

+sock.connect({port: 6697, host: "irc.freenode.net"});
+```
+
+That's typically how you upgrade an existing socket. However, if you're using TLS from the start, then just use tls.connect() to upgrade a socket:


Avoid using informal omissions: "you're" → "you are".

Put tls.connect() into backticks to mark it as code.

tniessen · 2017-07-03T17:26:45Z

doc/api/tls.md

+var tls = require('tls');
+var secureSock = tls.connect({port: 6697, host: "irc.freenode.net"}, function() {
+  console.log("The tls socket connected. Yay!");
+  secureSock.write(...);


We like to keep our examples as close to runnable code as possible. This will cause a parser error.

I believe this parse error is fixed now, but (I apologize) I am not terribly familiar with tls.connect and was using the recommended fix referenced in the issue. If there is a better example, happy to use it instead.

tniessen · 2017-07-03T17:26:46Z

doc/api/tls.md

+
+```js
+var tls = require('tls');
+var secureSock = tls.connect({port: 6697, host: "irc.freenode.net"}, function() {


Avoid using function() { ... } where arrow functions can be used: () => { ... }

VerteDinde · 2017-07-03T17:58:47Z

Thank you for your time and all of the thoughtful comments, @tniessen! Sorry for all my errors - I'm going through your comments and fixing everything now, will have an updated push shortly. 😄

…e, styling fix

VerteDinde · 2017-07-03T18:12:12Z

PR updated to address all comments. 😃 Will be happy to make any additional changes.

vsemozhetbyt · 2017-07-03T18:56:18Z

doc/api/tls.md

@@ -876,6 +876,27 @@ socket.on('end', () => {
 });
 ```

+When using an instance of `net.Socket`, use `net.Socket` to upgrade an existing socket. Do not wrap the `net.Socket` in a `TLSSocket`. See the example below for usage of upgrading an existing socket:


Thank you!
Our doc style guide recommends to word-wrap lines at 80 characters)

Will do! Making changes now, thank you @vsemozhetbyt

vsemozhetbyt · 2017-07-03T18:59:43Z

doc/api/tls.md

+When using an instance of `net.Socket`, use `net.Socket` to upgrade an existing socket. Do not wrap the `net.Socket` in a `TLSSocket`. See the example below for usage of upgrading an existing socket:
+
+```js
+const Socket = require('net').Socket;


Most of our examples use destructuring, so this can be:

const { Socket } = require('net');

Thanks! Changed to the destructured format.

vsemozhetbyt · 2017-07-03T19:07:04Z

doc/api/tls.md

@@ -876,6 +876,31 @@ socket.on('end', () => {
 });
 ```

+When using an instance of `net.Socket`, use `net.Socket` to upgrade an existing socket. 


Sorry, this is still 88 chars) But it is a small nit and can be fixed later on landing)

Ah dang, I can't count! Sorry, now fixed - cuts off before 80.

vsemozhetbyt · 2017-07-03T19:08:25Z

doc/api/tls.md

+sock.connect({ port: 6697, host: 'irc.freenode.net' });
+```
+
+If using TLS as the initial default rather than net.Socket, 


`net.Socket`)

tniessen · 2017-07-03T18:13:43Z

doc/api/tls.md

+const secureSock = tls.connect({ socket: s }, () => {
+  console.log('The tls socket connected.');
+});
+sock.connect({ port: 6697, host: 'irc.freenode.net' });


I think this works, but our docs say

Usually, a socket is already connected when passed to tls.connect()

It might be a bit counter-intuitive to call tls.connect() before socket.connect(). I don't use the TLS module much, is there any reason for this order?

Good question - I thought that seemed off as well, but worked when I tested it. Let me test it by calling sock.connect first and see; it does seem redundant to call sock.connect after tls.connect.

I replaced { socket: s } with the port and host information, and removed sock.connect entirely. It appears to be passing, and now the sample code is more in line with the docs' recommendations.

tniessen · 2017-07-03T18:17:39Z

doc/api/tls.md

@@ -876,6 +876,27 @@ socket.on('end', () => {
 });
 ```

+When using an instance of `net.Socket`, use `net.Socket` to upgrade an existing socket. Do not wrap the `net.Socket` in a `TLSSocket`. See the example below for usage of upgrading an existing socket:


When using an instance of net.Socket, use net.Socket to upgrade an existing socket.

I think this sentence is misleading. Users still need to use tls.connect(). Perhaps something like

To upgrade an existing instance of net.Socket to a tls.TLSSocket, pass it to tls.connect() as the socket option:

(code here)

What do you think?

I think that's much more clear - the original issue had a user trying to do this:

const tlsSocket = new TlsSocket(new NetSocket());

And I think your wording will keep them from doing that much more clearly. Will update now!

…n of upgrading instance.

vsemozhetbyt · 2017-07-03T20:05:57Z

Linter CI: https://ci.nodejs.org/job/node-test-linter/10249/

vsemozhetbyt

Formal part LGTM

tniessen · 2017-07-03T20:06:59Z

doc/api/tls.md

+const { Socket } = require('net');
+const tls = require('tls');
+const sock = new Socket();
+const secureSock = tls.connect({ port: 6697, host: 'irc.freenode.net' }, () => {


Are we legally allowed and/or encouraged to use a third party domain here? @addaleax

In the documentation? I wouldn’t worry about that, although example.org:443 might be a somewhat more natural choice?

example.org exists for that sole purpose, but users won't be able to connect to it.

https://example.org:443/ seems to work fine for me?

Oh okay, I thought example.com rejects all IP traffic, seems like HTTP and HTTPS work.

Fixed! Added 'https://example.org:443/' instead of the freenode url.

tniessen · 2017-07-03T20:14:03Z

doc/api/tls.md

@@ -876,6 +876,30 @@ socket.on('end', () => {
 });
 ```

+Passing in `net.Socket` will start a new instance.
+To upgrade an existing instance of `net.Socket` to a 


Please try to avoid trailing whitespace characters. Git can help you with that, see this.

(This is not critical, our team will usually fix this while landing the PR, but it is still good practice to take care of that! 😃 )

Ah sorry, and thank you for pointing it out! 😄 Thanks so much for all of your help, this was my first open source PR and you were wonderful to work with.

addaleax · 2017-07-03T20:24:33Z

doc/api/tls.md

+```js
+const { Socket } = require('net');
+const tls = require('tls');
+const sock = new Socket();


Where is this variable used?

Uhm something went wrong here... The original code (see first commit) looked like tls.connect({ socket: sock }). @VerteDinde You probably don't want to use tls.connect({ port: 6697, host: 'irc.freenode.net' }) in both cases, right? This won't upgrade an existing socket, it establishes a new connection.

Yes, you're right! Just updated to reflect that variable and changed the irc.freenode.net to https://example.org:443/.

…le.org:443/

tniessen · 2017-07-03T21:50:19Z

doc/api/tls.md

@@ -895,7 +895,7 @@ use only `tls.connect()` to upgrade the socket:

 ```js
 const tls = require('tls');
-const secureSock = tls.connect({ port: 6697, host: 'irc.freenode.net' }, () => {
+const secureSock = tls.connect({ port: 6697, host: 'https://example.org:443/' }, () => {


I am sorry if we were too vague about this, but this is not how TLS sockets work. You need to specify example.org as the host and 443 as the port instead of 6697. https://example.org:443/ is a URL, @addaleax just used it to point out that browsers can connect to port 443. Sockets are below HTTP level, HTTP(s) is built on top of (TLS) sockets.

Ha, sorry - this is now fixed. Thanks so much for your patience, @tniessen 😝

TimothyGu

Nice work! I'd actually move the bits you added, so that is comes before the "echo server" example. Usually for API documentation we want to first explain what the API does, before providing a full working example like the "echo server".

TimothyGu · 2017-07-04T05:37:16Z

doc/api/tls.md

+const tls = require('tls');
+const sock = new Socket();
+const secureSock = tls.connect({ socket: sock }, () => {
+  console.log('The tls socket connected.');


I'd prefer 'The TLS socket has been connected.'

Sounds good. 😄 Altered!

TimothyGu · 2017-07-04T05:42:50Z

doc/api/tls.md

+```
+
+If using TLS as the initial default rather than `net.Socket`, 
+use only `tls.connect()` to upgrade the socket:


I think "upgrade" is a bit of a misnomer as there is no initial socket to be upgraded. I'd go with just:

If no socket is provided, this function will create a new TLS socket.

as opposed to

If a net.Socket is provided, this function will upgrade that TCP socket to a TLS one.

Ahhhh this is actually really clarifying - I was wondering what the distinction was with net.Socket. Have clarified by removing my old sentence, and adding yours. Thanks!

cjihrig

Left a comment. You can treat it as optional.

cjihrig · 2017-07-04T14:22:47Z

doc/api/tls.md

+const { Socket } = require('net');
+const tls = require('tls');
+const sock = new Socket();
+const secureSock = tls.connect({ socket: sock }, () => {


If you rename sock to socket, you can drop the : sock.

Thanks man! Destructured.

tniessen · 2017-07-04T16:39:30Z

doc/api/tls.md

@@ -876,6 +876,30 @@ socket.on('end', () => {
 });
 ```

+Passing in `net.Socket` will start a new instance.


Is this line necessary? I am not entirely sure I understand what it is supposed to say, apart from the same thing the next sentence says.

Good point. In the original issue, the user was attempting to do this because he didn't understand that if you pass in a net.Socket, you start the net.Socket.:

const tlsSocket = new TlsSocket(new NetSocket());

I just wanted to make sure that that was clearly stated; but if it's clear in the subsequent lines, I'll just take it out 😄

…de language, moved amended docs to above echo server example

tniessen

LGTM, this will land after the usual 48 hours 🕐

sam-github

This PR seems to be based on the #3963, but it was already addressed by documenting the behaviour of the socket option. There are lots of options, will we eventually have an example for every one of the dozen options? If yes, that seems excessive to me. If no, why is this particular option singled out?

sam-github · 2017-07-05T17:13:00Z

doc/api/tls.md

@@ -821,6 +821,28 @@ The `callback` function, if specified, will be added as a listener for the

 `tls.connect()` returns a [`tls.TLSSocket`][] object.

+To upgrade an existing instance of `net.Socket` to a 


this is documented above, does it really need an example? was the existing description of the socket: option somehow deficient?

sam-github · 2017-07-05T17:13:47Z

doc/api/tls.md

+const tls = require('tls');
+const socket = new Socket();
+const secureSock = tls.connect({ socket }, () => {
+  console.log('The TLS socket has been connected.');


at this point, neither the underlying Socket or tls.TLSSocket are connected, so the log message is misleading (see description of the socket option)

This must have slipped through, earlier commits had the actual connect code in them, so the message was justified at that point.

sam-github · 2017-07-05T17:21:54Z

Also, this PR doesn't address #3963, which is that the connect() doesn't actually connect the underlying TCP socket, causing the example code to exit immediately, and the example code here does indeed have the behaviour described in #3963, it exits immediately:

/tmp % node --version
v8.0.0
/tmp % node _.js
/tmp % cat _.js
const { Socket } = require('net');
const tls = require('tls');
const socket = new Socket();
const secureSock = tls.connect({ socket }, () => {
  console.log('The TLS socket has been connected.');
});

VerteDinde · 2017-07-05T17:33:23Z

Hey @sam-github : Just want to make sure I understand your position - are you advocating for:

Closing Issue (new TLSSocket(new net.Socket())).connect() fails silently. #3963 and this PR, because the issue is already adequately explained in the documentation, and getting more specific would require explaining dozens of other cases?
or
Altering this PR so that it more accurately addresses the issue raised in (new TLSSocket(new net.Socket())).connect() fails silently. #3963?

Just want to make sure I'm clear before I start making any changes. Happy to go either way, or take a third option if neither of the two above are adequately stating your thoughts. Thanks for your comments!

sam-github · 2017-07-05T17:36:54Z

@VerteDinde IMO, 1. makes sense, if you arrived at this by looking at old issues for something to help out with. I am sorry that you wasted your time :-(.

If you got here because you found the current doc text unclear, that would be different, then it would be useful to clarify the behaviour that confused you.

VerteDinde · 2017-07-05T17:40:25Z

@sam-github Oh no worries at all! I did arrive here by poking through old issues - I'm just a big fan of Node and wanted to give back and start contributing. 😄

I'm completely fine closing this PR and the issue and finding something else to help with. Learned a lot about TLS and sockets in the process, so it was a good use of time for me (though sorry/thanks to @tniessen for all his time and patience!). If there's something else I can help on, let me know, otherwise I'll poke through and find a simpler doc problem.

sam-github · 2017-07-05T17:52:55Z

#881 (comment) <--- why not a binding for process.getuid()/geteuid()? Or if you aren't comfortable with C++, isTTY documented only in prose, not as a property (see the TTY docs), easy to fix.

sam-github · 2017-07-05T17:56:38Z

random stuff I've seen and not had time to fix. warning some of these may not longer be true.

isTTY documented only in prose, not as a property:
file:///home/sam/w/core/node/out/doc/api/tty.html
https://nodejs.org/api/dgram.html#dgram_socket_send_msg_offset_length_port_address_callback documents that <Array> is supported... but neglects to say anything about wh
IncomingMessage.connection is not documented, .socket is not documented
either as to whether it is a Socket or a TLSSocket
make it clear that ssl servers must have their full cert chain:
- https://www.npmjs.com/package/ssl-root-cas
UV_THREADPOOL_SIZE not documented as a node env var
what APIs use the thread pool not documented
NODE_TLS_REJECT_UNAUTHORIZED not documented
closed PR to doc the process.platform: doc: Update docs for os.platform() #2446
signal docs problems: Shouldn't the default SIGINT handler trigger process.on('exit')? #2853
signal docs, do they make clear that waiting on signals doesn't ref the loop?
fs: positional reads/writes don't document that they don't change fd position
http docs, and additional apis: http.ClientRequest poor documentation #2461 (comment)
fix/doc path.format(): Path should format when 'base' missing and 'name' and 'ext' exist #2305
child.signalCode and exitCode and killed are not documented
return value and exceptions of child.kill() are not documented
https://iojs.org/api/child_process.html#child_process_options_stdio,
'inherit' is now valid in the array, but undocumented
cluster.setupMaster and child_process.fork both support execArgv, but it is not documented for either, is this intentional?
cluster, worker.disconnect(), return value not documented (should be this)
- worker.disconnect().once('disconnect', doThis);
process.on(disconnect or process.on(message causes process to be refed!
udp: Event: 'listening'#
Emitted when a socket starts listening for datagrams. This happens as
soon as UDP sockets are created. before bind()? I think not
_write is linked in stream docs, _read isn't, fix
tls newSession should have backwards compat note about callback
fs.access should have backwards compat note about availability

vsemozhetbyt · 2017-07-05T18:29:23Z

Cross-refs) #14085 (comment) ...

tniessen · 2017-07-09T10:57:06Z

@sam-github Please close this if you feel like it should not be landed for your presented reasons.

Fixing TLS documentation error in Issue nodejs#3963. See line 879 - 9…

55f3170

…02 in doc/api/tls.md

nodejs-github-bot added doc Issues and PRs related to the documentations. tls Issues and PRs related to the tls subsystem. labels Jul 3, 2017

tniessen reviewed Jul 3, 2017

View reviewed changes

VerteDinde added 2 commits July 3, 2017 10:50

Changed documentation to remove pronoun usage

09f8564

Removed pronouns 'you'

cbbe60c

Adjusted 'vars' to 'const', changed parsing error in last code exampl…

7e766ff

…e, styling fix

vsemozhetbyt reviewed Jul 3, 2017

View reviewed changes

VerteDinde added 2 commits July 3, 2017 12:00

Word wrap at ~80 characters

8b945f8

Added destructuring to const Socket

5144cf4

vsemozhetbyt reviewed Jul 3, 2017

View reviewed changes

tniessen reviewed Jul 3, 2017

View reviewed changes

VerteDinde added 2 commits July 3, 2017 13:01

Added codetype to net.Socket, updated word wrap, updated descriptio…

fda1b66

…n of upgrading instance.

Removed sock.connect, appears to be passing

de3d050

vsemozhetbyt approved these changes Jul 3, 2017

View reviewed changes

tniessen reviewed Jul 3, 2017

View reviewed changes

addaleax reviewed Jul 3, 2017

View reviewed changes

Fixed socket update sample code, changed example url to https://examp…

872132e

…le.org:443/

tniessen reviewed Jul 3, 2017

View reviewed changes

VerteDinde added 2 commits July 3, 2017 15:23

Fixed example.org port number

5c41572

Fixed host name

955ad0f

TimothyGu reviewed Jul 4, 2017

View reviewed changes

cjihrig approved these changes Jul 4, 2017

View reviewed changes

tniessen self-assigned this Jul 4, 2017

tniessen reviewed Jul 4, 2017

View reviewed changes

VerteDinde added 2 commits July 4, 2017 22:56

Destructured socket, simplified net.Socket explanation, removed upgra…

9658ac3

…de language, moved amended docs to above echo server example

Fixed variable name

077508d

tniessen approved these changes Jul 5, 2017

View reviewed changes

sam-github reviewed Jul 5, 2017

View reviewed changes

vsemozhetbyt mentioned this pull request Jul 5, 2017

module: addBuiltinLibsToObject refactoring #14085

Closed

2 tasks

sam-github closed this Jul 10, 2017

joyeecheung mentioned this pull request Oct 9, 2017

(new TLSSocket(new net.Socket())).connect() fails silently. #3963

Closed

		@@ -821,6 +821,28 @@ The `callback` function, if specified, will be added as a listener for the

		`tls.connect()` returns a [`tls.TLSSocket`][] object.

		To upgrade an existing instance of `net.Socket` to a

fixed TLSSocket documentation error from Issue #3963. #14062

fixed TLSSocket documentation error from Issue #3963. #14062

Conversation

VerteDinde commented Jul 3, 2017

#Checklist

Affected core subsystem(s)

tniessen commented Jul 3, 2017 • edited Loading

tniessen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VerteDinde commented Jul 3, 2017

VerteDinde commented Jul 3, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VerteDinde Jul 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented Jul 3, 2017

vsemozhetbyt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TimothyGu left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cjihrig left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tniessen left a comment

Choose a reason for hiding this comment

sam-github left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tniessen Jul 5, 2017 • edited Loading

Choose a reason for hiding this comment

sam-github commented Jul 5, 2017 • edited Loading

VerteDinde commented Jul 5, 2017 • edited Loading

sam-github commented Jul 5, 2017

VerteDinde commented Jul 5, 2017

sam-github commented Jul 5, 2017

sam-github commented Jul 5, 2017

vsemozhetbyt commented Jul 5, 2017

tniessen commented Jul 9, 2017

tniessen commented Jul 3, 2017 •

edited

Loading

VerteDinde Jul 3, 2017 •

edited

Loading

TimothyGu left a comment •

edited

Loading

tniessen Jul 5, 2017 •

edited

Loading

sam-github commented Jul 5, 2017 •

edited

Loading

VerteDinde commented Jul 5, 2017 •

edited

Loading