Skip to content

Commit dd9573e

Browse files
ystreetystreet
committed
update READMEs
1 parent 74379d3 commit dd9573e

File tree

3 files changed

+126
-3
lines changed

3 files changed

+126
-3
lines changed

‎README.md

+40-2
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,59 @@
66

77
# stun-proto
88

9-
Repository containing an implementation of STUN (RFC5389/RFC8489) protocol writing in
10-
the [Rust programming language](https://www.rust-lang.org/).
9+
Repository containing a sans-IO implementation of the STUN (RFC5389/RFC8489) protocol
10+
and STUN parsing and writing in the [Rust programming language](https://www.rust-lang.org/).
11+
12+
## Why sans-io?
13+
14+
A couple of reasons: reusability, and testability.
15+
16+
Without being bogged down in the details of how IO happens, the same sans-IO
17+
implementation can be used without prescribing the IO pattern that an application
18+
must follow. Instead, the application (or parent library) has much more freedom
19+
in how bytes are transferred between peers. It's also possible to us a sans-IO
20+
library in either a synchronous or within an asynchronous runtime.
21+
22+
sans-IO also allows easy testing of any specific state the sans-IO
23+
implementation might find itself in. Combined with a comprehensive test-suite,
24+
this provides assurance that the implementation behaves as expected under all
25+
circumstances.
26+
27+
For other examples of sans-IO implementations, take a look at:
28+
- [librice](https://github.com/ystreet/librice)
29+
- [Quinn](https://github.com/quinn-rs/quinn/)
30+
- https://sans-io.readthedocs.io/
1131

1232
## Relevant standards
1333

34+
- [RFC5245](https://tools.ietf.org/html/rfc5245):
35+
Interactive Connectivity Establishment (ICE): A Protocol for Network Address
36+
Translator (NAT) Traversal for Offer/Answer Protocols
1437
- [RFC5389](https://tools.ietf.org/html/rfc5389):
1538
Session Traversal Utilities for NAT (STUN)
39+
- [RFC5766](https://tools.ietf.org/html/rfc5766):
40+
Traversal Using Relays around NAT (TURN): Relay Extensions to Session
41+
Traversal Utilities for NAT (STUN)
42+
- [RFC5769](https://tools.ietf.org/html/rfc5769):
43+
Test Vectors for Session Traversal Utilities for NAT (STUN)
44+
- [RFC6156](https://tools.ietf.org/html/rfc6156):
45+
Traversal Using Relays around NAT (TURN) Extension for IPv6
46+
- [RFC8445](https://tools.ietf.org/html/rfc8445):
47+
Interactive Connectivity Establishment (ICE): A Protocol for Network Address
48+
Translator (NAT) Traversal
1649
- [RFC8489](https://tools.ietf.org/html/rfc8489):
1750
Session Traversal Utilities for NAT (STUN)
51+
- [RFC8656](https://tools.ietf.org/html/rfc8656):
52+
Traversal Using Relays around NAT (TURN): Relay Extensions to Session
53+
Traversal Utilities for NAT (STUN)
1854

1955
## Structure
2056

2157
### [stun-types](https://github.com/ystreet/stun-proto/tree/main/stun-types)
2258

2359
Contains parsers and writing implementations for STUN messages and attributes.
60+
Message parsing is zero-copy by default and easily supports externally defined
61+
custom attributes.
2462

2563
### [stun-proto](https://github.com/ystreet/stun-proto/tree/main/stun-proto)
2664

‎stun-proto/README.md

+36
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,46 @@
99
Repository containing a sans-IO implementation of the STUN (RFC5389/RFC8489) protocol written in
1010
the [Rust programming language](https://www.rust-lang.org/).
1111

12+
## Why sans-io?
13+
14+
A couple of reasons: reusability, and testability.
15+
16+
Without being bogged down in the details of how IO happens, the same sans-IO
17+
implementation can be used without prescribing the IO pattern that an application
18+
must follow. Instead, the application (or parent library) has much more freedom
19+
in how bytes are transferred between peers. It's also possible to us a sans-IO
20+
library in either a synchronous or within an asynchronous runtime.
21+
22+
sans-IO also allows easy testing of any specific state the sans-IO
23+
implementation might find itself in. Combined with a comprehensive test-suite,
24+
this provides assurance that the implementation behaves as expected under all
25+
circumstances.
26+
27+
For other examples of sans-IO implementations, take a look at:
28+
- [librice](https://github.com/ystreet/librice)
29+
- [Quinn](https://github.com/quinn-rs/quinn/)
30+
- https://sans-io.readthedocs.io/
31+
1232
## Relevant standards
1333

34+
- [RFC5245](https://tools.ietf.org/html/rfc5245):
35+
Interactive Connectivity Establishment (ICE): A Protocol for Network Address
36+
Translator (NAT) Traversal for Offer/Answer Protocols
1437
- [RFC5389](https://tools.ietf.org/html/rfc5389):
1538
Session Traversal Utilities for NAT (STUN)
39+
- [RFC5766](https://tools.ietf.org/html/rfc5766):
40+
Traversal Using Relays around NAT (TURN): Relay Extensions to Session
41+
Traversal Utilities for NAT (STUN)
42+
- [RFC5769](https://tools.ietf.org/html/rfc5769):
43+
Test Vectors for Session Traversal Utilities for NAT (STUN)
44+
- [RFC6156](https://tools.ietf.org/html/rfc6156):
45+
Traversal Using Relays around NAT (TURN) Extension for IPv6
46+
- [RFC8445](https://tools.ietf.org/html/rfc8445):
47+
Interactive Connectivity Establishment (ICE): A Protocol for Network Address
48+
Translator (NAT) Traversal
1649
- [RFC8489](https://tools.ietf.org/html/rfc8489):
1750
Session Traversal Utilities for NAT (STUN)
51+
- [RFC8656](https://tools.ietf.org/html/rfc8656):
52+
Traversal Using Relays around NAT (TURN): Relay Extensions to Session
53+
Traversal Utilities for NAT (STUN)
1854

‎stun-types/README.md

+50-1
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,62 @@
99
Repository containing an implementation of STUN (RFC5389/RFC8489) protocol writing in
1010
the [Rust programming language](https://www.rust-lang.org/).
1111

12+
## Goals
13+
14+
- Efficiency:
15+
- zero-copy parsing
16+
- no copies until the message is written.
17+
- Support externally defined attributes easily. Only 3 traits required for an
18+
implementation, two of which are `From` and `TryFrom`.
19+
1220
## Relevant standards
1321

22+
- [RFC5245](https://tools.ietf.org/html/rfc5245):
23+
Interactive Connectivity Establishment (ICE): A Protocol for Network Address
24+
Translator (NAT) Traversal for Offer/Answer Protocols
1425
- [RFC5389](https://tools.ietf.org/html/rfc5389):
1526
Session Traversal Utilities for NAT (STUN)
27+
- [RFC5766](https://tools.ietf.org/html/rfc5766):
28+
Traversal Using Relays around NAT (TURN): Relay Extensions to Session
29+
Traversal Utilities for NAT (STUN)
30+
- [RFC5769](https://tools.ietf.org/html/rfc5769):
31+
Test Vectors for Session Traversal Utilities for NAT (STUN)
32+
- [RFC6156](https://tools.ietf.org/html/rfc6156):
33+
Traversal Using Relays around NAT (TURN) Extension for IPv6
34+
- [RFC8445](https://tools.ietf.org/html/rfc8445):
35+
Interactive Connectivity Establishment (ICE): A Protocol for Network Address
36+
Translator (NAT) Traversal
1637
- [RFC8489](https://tools.ietf.org/html/rfc8489):
1738
Session Traversal Utilities for NAT (STUN)
39+
- [RFC8656](https://tools.ietf.org/html/rfc8656):
40+
Traversal Using Relays around NAT (TURN): Relay Extensions to Session
41+
Traversal Utilities for NAT (STUN)
1842

19-
# Examples
43+
## Examples
2044

2145
Have a look at the documentation at the crate root for some examples
46+
47+
## Why not use `stun_codec`, `stun-format`, `stun-rs`, or 'insert crate here'?
48+
49+
Existing STUN crates suffer from one of a few of shortcomings.
50+
51+
1. Encoding attributes as enum's rather than as a trait. Using a trait for
52+
attributes allows external code to implement their own attributes and is thus
53+
not limited to what the crate implements. A trait-based approach also allows
54+
us to add attribute implementations without requiring breaking semver.
55+
`rust-stun-coder` and `stun-format` fall into this category. While we do aim
56+
to eventually support all the STUN attributes currently defined by the IANA
57+
and in various RFCs, we are also not going to force a user to use our
58+
implementations (except for integrity and fingerprint attributes).
59+
2. Non-zero copy parsing. i.e. taking some input data and making no copies
60+
unless a specific attribute implement is required. This is not usually a big
61+
deal with most STUN messages but can become an issue with TURN usage and high
62+
bitrates transfers. Our goal is to perform no copies of the data unless
63+
necessary. `stun-format`, `stun_codec`, `stun-rs` fail this design goal. The
64+
only other implementation I could find was `turn-rs` which contains a very
65+
small STUN implementation that is only enough for TURN usage.
66+
3. Overly complicated with macros and additional traits. It shouldn't be
67+
necessary to implement STUN with complicated macros or `decoder`/`encoder`
68+
traits for messages and attributes. STUN is a relatively simple byte codec
69+
and does not require a complicated implementation. `stun-rs`, `stun_codec`,
70+
currently this design goal.

0 commit comments

Comments
 (0)