From 6c64c8a9e246e940170a80de672d20104c0a1079 Mon Sep 17 00:00:00 2001 From: Timon Post Date: Tue, 17 Nov 2020 21:48:17 +0100 Subject: [PATCH 01/10] Write tuturoial book --- docs/book/src/SUMMARY.md | 5 +- docs/book/src/quinn/set-up-connection.md | 89 ++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 docs/book/src/quinn/set-up-connection.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 596f7ac64..b9b55a8bc 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -1,4 +1,7 @@ # Summary -- [Quinn introduction](quinn.md) +- [QUINN Introduction](quinn.md) + - [Overview](quinn/introduction.md) + - [Certificate Configuration](quinn/certificate.md) + - [Connection Setup](quinn/set-up-connection.md) - [The QUIC protocol](quic.md) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md new file mode 100644 index 000000000..d52ce1c56 --- /dev/null +++ b/docs/book/src/quinn/set-up-connection.md @@ -0,0 +1,89 @@ +# Connection Setup + +In the [previous chapter](certificate.md) we looked at how to configure a certificate. +This aspect is omitted in this chapter to prevent duplication. +But **remember** that is is required to get your [Endpoint][Endpoint] up and running. +This chapter explains how to set up a connection and prepare it for data transfer. + +It all starts with the [Endpoint][Endpoint] struct, this is the entry of the library. + +## Example + +Let's start by defining some constants. + +```rust +static SERVER_NAME: &str = "localhost"; + +fn client_addr() -> SocketAddr { + "127.0.0.1:5000".parse::().unwrap() +} + +fn server_addr() -> SocketAddr { + "127.0.0.1:5001".parse::().unwrap() +} +``` + +For both the server and the client we use the [EndpointBuilder][EndpointBuilder]. +The [EndpointBuilder][EndpointBuilder] has a method [bind(address)][bind] with which you link an address to the endpoint. +This method initializes a UDP-socket that is used by quinn. +If you need more control over the socket creation, it is also possible to initialize a quinn endpoint with an existing UDP socket with [with_socket][with_socket]. + +**Server** + +Just like a TCP Listener, you have to listen to incoming connections. +Before you can listen to connections you need to configure the [EndpointBuilder][EndpointBuilder] as a server. +Note that the configuration itself does not perform any listening logic, instead use the `Incomming` type returned by [bind()][bind]. + +```rust +async fn server() -> anyhow::Result<()> { + let mut endpoint_builder = Endpoint::builder(); + // Configure this endpoint as a server by passing in `ServerConfig`. + endpoint_builder.listen(ServerConfig::default()); + + // Bind this endpoint to a UDP socket on the given server address. + let (endpoint, mut incoming) = endpoint_builder.bind(&server_addr())?; + + // Start iterating over incoming connections. + while let Some(conn) = incoming.next().await { + let mut connection: NewConnection = conn.await?; + + // Save connection somewhere, start transferring, receiving data, see DataTransfer tutorial. + } + + Ok(()) +} +``` + +**Client** + +Just like a TCP client, you need to connect to a listening endpoint (the server). +In quinn you can do this with the method [connect()][connect]. +The [connect()][connect] method has an argument 'server name' which has to be the name that is in the configured certificate. + +```rust +async fn client() -> anyhow::Result<()> { + let mut endpoint_builder = Endpoint::builder(); + + // Bind this endpoint to a UDP socket on the given client address. + let (endpoint, _) = endpoint_builder.bind(&client_addr())?; + + // Connect to the server passing in the server name which is supposed to be in the server certificate. + let connection: NewConnection = endpoint + .connect(&server_addr(), SERVER_NAME)? + .await?; + + // Start transferring, receiving data, see data transfer page. + + Ok(()) +} +``` +
+ +[Nextup](set-up-connection.md), lets have a look at sending data over this connection. + + +[Endpoint]: https://docs.rs/quinn/latest/quinn/generic/struct.Endpoint.html +[EndpointBuilder]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html +[bind]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html#method.bind +[connect]: https://docs.rs/quinn/latest/quinn/generic/struct.Endpoint.html#method.connect +[with_socket]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html#method.with_socket \ No newline at end of file From 8f8ed26e4bdb9c84cf8b7a8fc302e9ac334e9317 Mon Sep 17 00:00:00 2001 From: Timon Post Date: Sat, 21 Nov 2020 09:47:30 +0100 Subject: [PATCH 02/10] Remove introduction --- docs/book/src/SUMMARY.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index b9b55a8bc..f570cb9a5 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -1,7 +1,6 @@ # Summary - [QUINN Introduction](quinn.md) - - [Overview](quinn/introduction.md) - [Certificate Configuration](quinn/certificate.md) - [Connection Setup](quinn/set-up-connection.md) - [The QUIC protocol](quic.md) From 3b9f28b34d4340869a5d5779049b573f36f027fc Mon Sep 17 00:00:00 2001 From: Timon Post Date: Tue, 1 Dec 2020 19:32:12 +0100 Subject: [PATCH 03/10] Review round 1 --- docs/book/src/quinn/set-up-connection.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index d52ce1c56..35c96bb5a 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -2,7 +2,7 @@ In the [previous chapter](certificate.md) we looked at how to configure a certificate. This aspect is omitted in this chapter to prevent duplication. -But **remember** that is is required to get your [Endpoint][Endpoint] up and running. +But **remember** that tis is required to get your [Endpoint][Endpoint] up and running. This chapter explains how to set up a connection and prepare it for data transfer. It all starts with the [Endpoint][Endpoint] struct, this is the entry of the library. @@ -23,16 +23,15 @@ fn server_addr() -> SocketAddr { } ``` -For both the server and the client we use the [EndpointBuilder][EndpointBuilder]. -The [EndpointBuilder][EndpointBuilder] has a method [bind(address)][bind] with which you link an address to the endpoint. -This method initializes a UDP-socket that is used by quinn. -If you need more control over the socket creation, it is also possible to initialize a quinn endpoint with an existing UDP socket with [with_socket][with_socket]. +On both the client and the server, the [EndpointBuilder][EndpointBuilder] should be used to configure an endpoint. +The [bind(address)][bind] method initializes a UDP socket on the specified address. +It is also possible to provide Quinn with an initialized socket via [with_socket()][with_socket]. **Server** -Just like a TCP Listener, you have to listen to incoming connections. -Before you can listen to connections you need to configure the [EndpointBuilder][EndpointBuilder] as a server. -Note that the configuration itself does not perform any listening logic, instead use the `Incomming` type returned by [bind()][bind]. +First, the server endpoint should be bound to a socket. +The [bind()][bind] method, which can be used for this, returns a tuple with the `Endpoint` and `Incomming` types. +The `Endpoint` type can be used to start outgoing connections, and the `Incoming` type can be used to listen for incoming connections. ```rust async fn server() -> anyhow::Result<()> { @@ -56,9 +55,8 @@ async fn server() -> anyhow::Result<()> { **Client** -Just like a TCP client, you need to connect to a listening endpoint (the server). -In quinn you can do this with the method [connect()][connect]. -The [connect()][connect] method has an argument 'server name' which has to be the name that is in the configured certificate. +The client needs to connect to the server using the [connect(server_name)][connect] method. +The argument 'server name' is the DNS name (matching the certificate configured in the server). ```rust async fn client() -> anyhow::Result<()> { From 985926a9741d3b0d87ef7243268368cca38b6310 Mon Sep 17 00:00:00 2001 From: Timon Post Date: Tue, 1 Dec 2020 19:38:17 +0100 Subject: [PATCH 04/10] Fix grammer error --- docs/book/src/quinn/set-up-connection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index 35c96bb5a..bb58b9d6c 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -2,7 +2,7 @@ In the [previous chapter](certificate.md) we looked at how to configure a certificate. This aspect is omitted in this chapter to prevent duplication. -But **remember** that tis is required to get your [Endpoint][Endpoint] up and running. +But **remember** that this is required to get your [Endpoint][Endpoint] up and running. This chapter explains how to set up a connection and prepare it for data transfer. It all starts with the [Endpoint][Endpoint] struct, this is the entry of the library. From 631dcb97cae1147fb25ceb8ea931d5f9acb42a37 Mon Sep 17 00:00:00 2001 From: Timon Post Date: Sat, 19 Dec 2020 12:09:36 +0100 Subject: [PATCH 05/10] round 2 --- docs/book/src/quinn/set-up-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index bb58b9d6c..986d31d8c 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -5,7 +5,7 @@ This aspect is omitted in this chapter to prevent duplication. But **remember** that this is required to get your [Endpoint][Endpoint] up and running. This chapter explains how to set up a connection and prepare it for data transfer. -It all starts with the [Endpoint][Endpoint] struct, this is the entry of the library. +It all starts with the [Endpoint][Endpoint] struct, this is the entry point of the library. ## Example @@ -30,7 +30,7 @@ It is also possible to provide Quinn with an initialized socket via [with_socket **Server** First, the server endpoint should be bound to a socket. -The [bind()][bind] method, which can be used for this, returns a tuple with the `Endpoint` and `Incomming` types. +The [bind()][bind] method, which can be used for this, returns a tuple containing the `Endpoint` and `Incoming` types. The `Endpoint` type can be used to start outgoing connections, and the `Incoming` type can be used to listen for incoming connections. ```rust From 556d0ee5d9a25269433ae6822afa71327219c216 Mon Sep 17 00:00:00 2001 From: Timon Date: Sat, 16 Jan 2021 14:39:17 +0100 Subject: [PATCH 06/10] Update docs/book/src/quinn/set-up-connection.md Co-authored-by: Dirkjan Ochtman --- docs/book/src/quinn/set-up-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index 986d31d8c..1ef41560e 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -77,11 +77,11 @@ async fn client() -> anyhow::Result<()> { ```
-[Nextup](set-up-connection.md), lets have a look at sending data over this connection. +[Next up](set-up-connection.md), let's have a look at sending data over this connection. [Endpoint]: https://docs.rs/quinn/latest/quinn/generic/struct.Endpoint.html [EndpointBuilder]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html [bind]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html#method.bind [connect]: https://docs.rs/quinn/latest/quinn/generic/struct.Endpoint.html#method.connect -[with_socket]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html#method.with_socket \ No newline at end of file +[with_socket]: https://docs.rs/quinn/latest/quinn/generic/struct.EndpointBuilder.html#method.with_socket From 5e0e35acf2f554df93e1c6d14bb8b03c9ff2b6b8 Mon Sep 17 00:00:00 2001 From: Timon Date: Sat, 16 Jan 2021 14:39:47 +0100 Subject: [PATCH 07/10] Update docs/book/src/quinn/set-up-connection.md Co-authored-by: Dirkjan Ochtman --- docs/book/src/quinn/set-up-connection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index 1ef41560e..a183974a4 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -56,7 +56,7 @@ async fn server() -> anyhow::Result<()> { **Client** The client needs to connect to the server using the [connect(server_name)][connect] method. -The argument 'server name' is the DNS name (matching the certificate configured in the server). +The `SERVER_NAME` argument is the DNS name, matching the certificate configured in the server. ```rust async fn client() -> anyhow::Result<()> { From 63c448f090f3548097c539d52a472a74c0d005cf Mon Sep 17 00:00:00 2001 From: Timon Date: Sat, 16 Jan 2021 14:40:00 +0100 Subject: [PATCH 08/10] Update docs/book/src/quinn/set-up-connection.md Co-authored-by: Dirkjan Ochtman --- docs/book/src/quinn/set-up-connection.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index a183974a4..e09608843 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -66,9 +66,7 @@ async fn client() -> anyhow::Result<()> { let (endpoint, _) = endpoint_builder.bind(&client_addr())?; // Connect to the server passing in the server name which is supposed to be in the server certificate. - let connection: NewConnection = endpoint - .connect(&server_addr(), SERVER_NAME)? - .await?; + let connection = endpoint.connect(&server_addr(), SERVER_NAME)?.await?; // Start transferring, receiving data, see data transfer page. From 3e42b03e785248faa4d4ed712e31f580513eb551 Mon Sep 17 00:00:00 2001 From: Timon Date: Sat, 16 Jan 2021 14:40:24 +0100 Subject: [PATCH 09/10] Update docs/book/src/quinn/set-up-connection.md Co-authored-by: Dirkjan Ochtman --- docs/book/src/quinn/set-up-connection.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index e09608843..0552a098f 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -24,7 +24,6 @@ fn server_addr() -> SocketAddr { ``` On both the client and the server, the [EndpointBuilder][EndpointBuilder] should be used to configure an endpoint. -The [bind(address)][bind] method initializes a UDP socket on the specified address. It is also possible to provide Quinn with an initialized socket via [with_socket()][with_socket]. **Server** From af88ab8fe1ab256e8764cacf7d4997cd6402ed88 Mon Sep 17 00:00:00 2001 From: Timon Post Date: Sat, 16 Jan 2021 14:55:26 +0100 Subject: [PATCH 10/10] round 32 --- docs/book/src/quinn/set-up-connection.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/book/src/quinn/set-up-connection.md b/docs/book/src/quinn/set-up-connection.md index 0552a098f..2e10e28e1 100644 --- a/docs/book/src/quinn/set-up-connection.md +++ b/docs/book/src/quinn/set-up-connection.md @@ -23,8 +23,7 @@ fn server_addr() -> SocketAddr { } ``` -On both the client and the server, the [EndpointBuilder][EndpointBuilder] should be used to configure an endpoint. -It is also possible to provide Quinn with an initialized socket via [with_socket()][with_socket]. +The [EndpointBuilder][EndpointBuilder] should be used to configure an endpoint. It is also possible to provide Quinn with an initialized socket via [with_socket()][with_socket]. **Server**