Skip to content

Added networking example to listen on random socket using tcp/ip #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 19, 2017
Merged

Added networking example to listen on random socket using tcp/ip #137

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
18e35d0
Added networking example to listen on random socket using tcp/ip
AndyGauge May 19, 2017
0436206
Merge branch 'master' of https://github.com/brson/rust-cookbook into …
AndyGauge May 19, 2017
e5c7db1
fixed spaces, added telnet example, and properly returned errors
AndyGauge May 19, 2017
25b53f7
Reword description and comments, variable names to match tense.
AndyGauge May 19, 2017
eaf2abc
Make language more concise / readable
AndyGauge May 19, 2017
10a14ea
Removed unused reference
AndyGauge May 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ community. It needs and welcomes help. For details see
| [Query the GitHub API][ex-rest-get] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] |
| [Check if an API Resource Exists][ex-rest-head] | [![reqwest-badge]][reqwest] | [![cat-net-badge]][cat-net] |
| [Create and delete Gist with GitHub API][ex-rest-post] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] |
| [Listen on Unused port TCP/IP][ex-random-port-tcp] | [![std-badge]][std] | [![cat-net-badge]][cat-net] |

## [Application development](app.html)

Expand Down Expand Up @@ -174,6 +175,7 @@ Keep lines sorted.
[ex-rand-custom]: basics.html#ex-rand-custom
[ex-rand-dist]: basics.html#ex-rand-dist
[ex-rand-float]: basics.html#ex-rand-float
[ex-random-port-tcp]: net.html#ex-random-port-tcp
[ex-rand-range]: basics.html#ex-rand-range
[ex-rayon-iter-mut]: concurrency.html#ex-rayon-iter-mut
[ex-rest-head]: net.html#ex-rest-head
Expand Down
79 changes: 79 additions & 0 deletions src/net.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
| [Query the GitHub API][ex-rest-get] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] |
| [Check if an API Resource Exists][ex-rest-head] | [![reqwest-badge]][reqwest] | [![cat-net-badge]][cat-net] |
| [Create and delete Gist with GitHub API][ex-rest-post] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] |
| [Listen on Unused port TCP/IP][ex-random-port-tcp] | [![std-badge]][std] | [![cat-net-badge]][cat-net] |

[ex-url-parse]: #ex-url-parse
<a name="ex-url-parse"/>
Expand Down Expand Up @@ -537,6 +538,75 @@ fn run() -> Result<()> {
quick_main!(run);
```

[ex-random-port-tcp]: #ex-random-port-tcp
<a name="ex-random-port-tcp"></a>
## Listen on Unused port TCP/IP

[![std-badge]][std] [![cat-net-badge]][cat-net]

Give the OS the responsibility to pick an unused [registered port]. These ports
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that you have put a lot of effort into this section but I would rather not educate readers on CS/Networking basics. We can safely assume that reader understands these concepts and came here only for the rust snippet and its very brief textual description (that would ideally be 2-4 sentences). I would suggest dropping this paragraph completely.

generally do not require sudo permission to bind to, and can be helpful when
establishing connections with clients in a disposable communication chain.
These ports begin with 1024 and have around 48,000 available. Typically, a
known port is used to initiate the communication and subsequent communication
occurs on the registered port after a handshake process.

In this example, the port is displayed on the console, and will listen until a
request is made. If you use your browser to test this program, simply enter
the address:port into your location bar and make the request. Because the
program returns nothing, the browser's stop feature can be used to speed things
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph is overly word and redundant with later telnet testing one.
I would remove all of it except the first sentence.

up.

```rust, no_run
#[macro_use]
extern crate error_chain;

use std::net::{SocketAddrV4, Ipv4Addr, TcpListener};
use std::io::Read;

error_chain! {
foreign_links {
Io(::std::io::Error);
}
}

fn run() -> Result<()> {
let loopback = Ipv4Addr::new(127, 0, 0, 1);
// Assigning port 0 requests the OS to assign a free port
let socket = SocketAddrV4::new(loopback, 0);
let listener = TcpListener::bind(socket)?;
let port = listener.local_addr()?;
println!("Listening on {}, access this port to end the program", port);
let (mut tcp_stream, addr) = listener.accept()?; //block until requested
println!("Connection received! {:?} is sending data.", addr);
let mut input = String::new();
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the connection is already accepted here. I would suggest printing
println!("Connection received on {:?}? says {}", addr);
here as it shows exactly where synchronous waiting occurs.

// read from the socket until connection closed by client, discard byte count.
let _ = tcp_stream.read_to_string(&mut input)?;
println!("{:?} says {}", addr, input);
Ok(())
}

quick_main!(run);
```

The `std` library is leveraged to make a well formed IP/port with the
[`SocketAddrV4`] and [`Ipv4Addr`] structs. The loopback address is a special
address that runs only on the local machine, and is available on all machines.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rather not try to educate the readers on what the loopback interface is. I would just stick to stating that code is listening on the loopback interface (possibly with hyperlink to some authoritative resource)


By passing 0 to the [`TcpListener::bind`], the OS will assign an unused random
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest rewording it in a more concise manner e.g:

An unused random port is requested by passing 0 to the [TcpListener::bind]. The assigned address is available via [TcpListener::local_addr].

port. The address and port that the OS assigns is available using
Copy link
Collaborator

@budziq budziq May 19, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit. Please do not mix tenses. Use present/past/future throughout the whole text.

[`TcpListener::local_addr`].

The rest of the recipe prints out the request made on the socket.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove this sentence and modify the following ones to reflect what is going one step by step.

[`TcpListener::accept`] returns a `(`[`TcpStream`], [`SocketAddrV4`]`)`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key fact about accept is that it synchronously waits for an incoming connection and returns the pair

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'an incoming connection is waited synchronously by TcpListener::accept` <- another case where passive isn't the best.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep

representing the data from the client, its IP address and port. Reading on the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

data from the client, its IP address and port.
Could be misunderstood. I would suggest something like:
"representing client connection IP address and port."

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so I'm going to take out the details about what the tuple is and call it the request. I think the links do a good job of explaining the details.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work:

[TcpListener::accept] synchronously waits for an incoming connection and
returns a ([TcpStream], [SocketAddrV4]) representing the request.
[read_to_string] will wait until the connection is closed, flushing the socket,
which can be tested with telnet ip port. For example, if the program
shows Listening on 127.0.0.1:11500, run

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks excellent 👍

socket with [`read_to_string`] will wait until the connection is closed which
can be tested with `telnet ip port`. For example, if the program shows
Listening on 127.0.0.1:11500, run

`telnet 127.0.0.1 11500`

After sending data in telnet press `ctrl-]` and type `quit`.
<!-- Categories -->

[cat-encoding-badge]: https://img.shields.io/badge/-encoding-red.svg
Expand All @@ -552,6 +622,8 @@ quick_main!(run);
[reqwest]: https://docs.rs/reqwest/
[serde-badge]: https://img.shields.io/crates/v/serde.svg?label=serde
[serde]: https://docs.rs/serde/
[std]: https://doc.rust-lang.org/std
[std-badge]: https://img.shields.io/badge/std-1.17.0-blue.svg
[tempdir-badge]: https://img.shields.io/crates/v/tempdir.svg?label=tempdir
[tempdir]: https://docs.rs/tempdir/
[url-badge]: https://img.shields.io/crates/v/url.svg?label=url
Expand All @@ -577,8 +649,15 @@ quick_main!(run);
[`RequestBuilder::json`]: https://docs.rs/reqwest/*/reqwest/struct.RequestBuilder.html#method.json
[`RequestBuilder::send`]: https://docs.rs/reqwest/*/reqwest/struct.RequestBuilder.html#method.send
[`read_to_string`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_to_string
[registered port]: https://en.wikipedia.org/wiki/Registered_port
[`String`]: https://doc.rust-lang.org/std/string/struct.String.html
[`serde::Deserialize`]: https://docs.rs/serde/*/serde/trait.Deserialize.html
[`serde_json::json!`]: https://docs.rs/serde_json/*/serde_json/macro.json.html
[`TempDir::new`]: https://docs.rs/tempdir/*/tempdir/struct.TempDir.html#method.new
[`TempDir::path`]: https://docs.rs/tempdir/*/tempdir/struct.TempDir.html#method.path
[`Ipv4Addr`]: https://doc.rust-lang.org/std/net/struct.Ipv4Addr.html
[`SocketAddrV4`]: https://doc.rust-lang.org/std/net/struct.SocketAddrV4.html
[`TcpListener::accept`]: https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.accept
[`TcpListener::bind`]: https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.bind
[`TcpListener::local_addr`]: https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.local_addr
[`TcpStream`]: https://doc.rust-lang.org/std/net/struct.TcpStream.html