Crystal: I don't know how to read the Crystal docs

[ghost]

Crystal Version: 0.24.1

Been stuck on this all day and not sure what to do. Oprypin and I have been back n forth on gitter for hours. I'm pretty sure something internally is going on, or it's a rare OS edge case. If you have time please take a look. And if you need access to my openVZ VPS, I can give you my SSH key. Just PM me through Gitter.

Testing this on Debian 8, 64-bit minimal (openVZ container, stock settings)
server.cr: https://paste.ee/p/C4UV7
socket.cr: https://paste.ee/p/2PzOT

How to Replicate

• run ulimit -n 60000, then crystal server.cr
• in another terminal, run: while sleep 1; do netstat -an | wc -l; done (shows connected amount)
• run socket.cr for 3-5 seconds, then do ctrl+c. do this about 3 times.
• close the socket.cr terminal to close all client-side connections

Then, gather your attention to the echoing netstat terminal, the connections decrement a tiny amount, but they will never get fully released. They'll stay at around 1039, or a weird number. To further illustrate this, run netstat -ntu, and you'll see a ton of established TCP states. Even after crystal used socket.close on them.

Reasons to believe it might be because of Crystal's TCPServer:

• This does not happen with a nodejs tcp server using socket.destroy()
• If you change socket.cr to port 22, to just do tcp connections to sshd. You will see all the connections eventually are free'd. It's not a socket.cr issue
• If you stop the server.cr, then watch your netstat terminal, you'll see your connections slowly go back down and be free'd. It'll look like this

[ghost]

@bararchy Recommended to use read_timeout, on the Socket. Which now correctly updates netstat -ntu with the correct TCP STATE. This closes the lingering rogue connections.

Not a Crystal issue at, and am sorry for this

[vectorselector]

OTOH, someone may have an actual issue reading crystal API docs. The format is not beginner-friendly and most methods are missing examples and one has to interpret what things mean such as:

as_h? : Hash(String, Type)?

which is not exactly the same format as actual usage... there is additional meaning and intention here

Not sure that the name of this issue is very helpful, even if you do feel ashamed for not reading the docs.

[bcardiff]

The API docs (https://crystal-lang.org/api/) are for reference. Sometimes a preface on each module might serve as an introduction. But is not a guide. For guides and more beginner friendly crystal-book (https://crystal-lang.org/docs/) should be used. And of course, all the docs are work in progress.

[asterite]

Just a quick suggestion for Spanish speakers. Remember that English doesn't have an implicit subject like in Spanish. So "But is not a guide" is not valid English because the subject is missing. "But it is not a guide" is a valid sentence.

Just a small thing. It's probably caused by translating from Spanish word by word ("Pero no es una guía" - > "But is not a guide").

This is not intended to offend anyone, just my grammar obsession :-P