• Stars
    star
    625
  • Rank 71,862 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created almost 6 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Go implementation of STUN


Pion STUN

A Go implementation of STUN

Pion stun Slack Widget
GitHub Workflow Status Go Reference Coverage Status Go Report Card License: MIT


Package stun implements Session Traversal Utilities for NAT (STUN) (RFC 5389) protocol and client with no external dependencies and zero allocations in hot paths. Client supports automatic request retransmissions.

Example

You can get your current IP address from any STUN server by sending binding request. See more idiomatic example at cmd/stun-client.

package main

import (
	"fmt"

	"github.com/pion/stun"
)

func main() {
	// Parse a STUN URI
	u, err := stun.ParseURI("stun:stun.l.google.com:19302")
	if err != nil {
		panic(err)
	}

	// Creating a "connection" to STUN server.
	c, err := stun.DialURI(u, &stun.DialConfig{})
	if err != nil {
		panic(err)
	}
	// Building binding request with random transaction id.
	message := stun.MustBuild(stun.TransactionID, stun.BindingRequest)
	// Sending request to STUN server, waiting for response message.
	if err := c.Do(message, func(res stun.Event) {
		if res.Error != nil {
			panic(res.Error)
		}
		// Decoding XOR-MAPPED-ADDRESS attribute from message.
		var xorAddr stun.XORMappedAddress
		if err := xorAddr.GetFrom(res.Message); err != nil {
			panic(err)
		}
		fmt.Println("your IP is", xorAddr.IP)
	}); err != nil {
		panic(err)
	}
}

RFCs

Implemented

Planned

Compatability notes

RFC 5389 obsoletes RFC 3489, so implementation was ignored by purpose, however, RFC 3489 can be easily implemented as separate package.

Stability

Package is currently stable, no backward incompatible changes are expected with exception of critical bugs or security fixes.

Additional attributes are unlikely to be implemented in scope of stun package, the only exception is constants for attribute or message types.

Requirements

Go 1.12 is currently supported and tested in CI.

Testing

Client behavior is tested and verified in many ways:

  • End-To-End with long-term credentials
    • coturn: The coturn server (linux)
  • Bunch of code static checkers (linters)
  • Standard unit-tests with coverage reporting (linux {amd64, arm64}, windows and darwin)
  • Explicit API backward compatibility check, see api directory

See TeamCity project and e2e directory for more information. Also the Wireshark .pcap files are available for e2e test in artifacts for build.

Benchmarks

Intel(R) Core(TM) i7-8700K:

version: 1.22.2
goos: linux
goarch: amd64
pkg: github.com/pion/stun
PASS
benchmark                                         iter       time/iter      throughput   bytes alloc        allocs
---------                                         ----       ---------      ----------   -----------        ------
BenchmarkMappedAddress_AddTo-12               32489450     38.30 ns/op                        0 B/op   0 allocs/op
BenchmarkAlternateServer_AddTo-12             31230991     39.00 ns/op                        0 B/op   0 allocs/op
BenchmarkAgent_GC-12                            431390   2918.00 ns/op                        0 B/op   0 allocs/op
BenchmarkAgent_Process-12                     35901940     36.20 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_GetNotFound-12              242004358      5.19 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_Get-12                      230520343      5.21 ns/op                        0 B/op   0 allocs/op
BenchmarkClient_Do-12                          1282231    943.00 ns/op                        0 B/op   0 allocs/op
BenchmarkErrorCode_AddTo-12                   16318916     75.50 ns/op                        0 B/op   0 allocs/op
BenchmarkErrorCodeAttribute_AddTo-12          21584140     54.80 ns/op                        0 B/op   0 allocs/op
BenchmarkErrorCodeAttribute_GetFrom-12       100000000     11.10 ns/op                        0 B/op   0 allocs/op
BenchmarkFingerprint_AddTo-12                 19368768     64.00 ns/op     687.81 MB/s        0 B/op   0 allocs/op
BenchmarkFingerprint_Check-12                 24167007     49.10 ns/op    1057.99 MB/s        0 B/op   0 allocs/op
BenchmarkBuildOverhead/Build-12                5486252    224.00 ns/op                        0 B/op   0 allocs/op
BenchmarkBuildOverhead/BuildNonPointer-12      2496544    517.00 ns/op                      100 B/op   4 allocs/op
BenchmarkBuildOverhead/Raw-12                  6652118    181.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_ForEach-12                   28254212     35.90 ns/op                        0 B/op   0 allocs/op
BenchmarkMessageIntegrity_AddTo-12             1000000   1179.00 ns/op      16.96 MB/s        0 B/op   0 allocs/op
BenchmarkMessageIntegrity_Check-12              975954   1219.00 ns/op      26.24 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_Write-12                     41040598     30.40 ns/op     922.13 MB/s        0 B/op   0 allocs/op
BenchmarkMessageType_Value-12               1000000000      0.53 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_WriteTo-12                   94942935     11.30 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_ReadFrom-12                  43437718     29.30 ns/op     682.87 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_ReadBytes-12                 74693397     15.90 ns/op    1257.42 MB/s        0 B/op   0 allocs/op
BenchmarkIsMessage-12                       1000000000      1.20 ns/op   16653.64 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_NewTransactionID-12            521121   2450.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessageFull-12                        5389495    221.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessageFullHardcore-12               12715876     94.40 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_WriteHeader-12              100000000     11.60 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_CloneTo-12                   30199020     41.80 ns/op    1626.66 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_AddTo-12                    415257625      2.97 ns/op                        0 B/op   0 allocs/op
BenchmarkDecode-12                            49573747     23.60 ns/op                        0 B/op   0 allocs/op
BenchmarkUsername_AddTo-12                    56282674     22.50 ns/op                        0 B/op   0 allocs/op
BenchmarkUsername_GetFrom-12                 100000000     10.10 ns/op                        0 B/op   0 allocs/op
BenchmarkNonce_AddTo-12                       39419097     35.80 ns/op                        0 B/op   0 allocs/op
BenchmarkNonce_AddTo_BadLength-12            196291666      6.04 ns/op                        0 B/op   0 allocs/op
BenchmarkNonce_GetFrom-12                    120857732      9.93 ns/op                        0 B/op   0 allocs/op
BenchmarkUnknownAttributes/AddTo-12           28881430     37.20 ns/op                        0 B/op   0 allocs/op
BenchmarkUnknownAttributes/GetFrom-12         64907534     19.80 ns/op                        0 B/op   0 allocs/op
BenchmarkXOR-12                               32868506     32.20 ns/op   31836.66 MB/s
BenchmarkXORSafe-12                            5185776    234.00 ns/op    4378.74 MB/s
BenchmarkXORFast-12                           30975679     32.50 ns/op   31525.28 MB/s
BenchmarkXORMappedAddress_AddTo-12            21518028     54.50 ns/op                        0 B/op   0 allocs/op
BenchmarkXORMappedAddress_GetFrom-12          35597667     34.40 ns/op                        0 B/op   0 allocs/op
ok      github.com/pion/stun   60.973s

Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Slack.

Follow the Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at [email protected]

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible: AUTHORS.txt

License

MIT License - see LICENSE for full text

More Repositories

1

webrtc

Pure Go implementation of the WebRTC API
Go
13,425
star
2

turn

Pion TURN, an API for building TURN clients and servers
Go
1,826
star
3

example-webrtc-applications

Examples of WebRTC applications that are large, or use 3rd party libraries
Go
1,031
star
4

awesome-pion

A curated list of awesome things related to Pion
Shell
723
star
5

dtls

DTLS 1.2 Server/Client implementation for Go
Go
584
star
6

mediadevices

Go implementation of the MediaDevices API.
Go
530
star
7

ice

A Go implementation of ICE
Go
430
star
8

opus

Pure Go implementation of Opus
Go
389
star
9

rtp

A Go implementation of RTP
Go
349
star
10

rtwatch

Watch videos with friends using WebRTC, let the server do the pausing and seeking.
Go
301
star
11

sctp

A Go implementation of SCTP
Go
219
star
12

offline-browser-communication

Demonstration of a browser connecting to Pion WebRTC without a signaling server.
Go
195
star
13

mdns

Pure Go implementation of Multicast DNS
Go
190
star
14

quic

A Go implementation of the QUIC API for Peer-to-peer and Client-to-Server Connections
Go
178
star
15

rtsp-bench

RTSP -> WebRTC Server that generates a CPU Usage report
Go
165
star
16

rtcp

A Go implementation of RTCP
Go
151
star
17

sdp

A Go implementation of the SDP
Go
146
star
18

srtp

A Go implementation of SRTP
Go
116
star
19

interceptor

Pluggable RTP/RTCP processors for building real time communication
Go
109
star
20

obs-wormhole

Supercharge OBS with WebRTC. Remote WebRTC Sources and Serverless Broadcasting
Go
95
star
21

datachannel

A Go implementation of WebRTC Data Channels
Go
81
star
22

transport

Transport testing for Pion
Go
78
star
23

explainer

Explainer parses WebRTC Offers/Answers then provides summaries and suggestions
Go
45
star
24

11LiveChat

Another one-one live chatroom using pion webrtc with sfu mode
Go
42
star
25

udp

Please use github.com/pion/transport/v2/udp instead
Go
36
star
26

webrtc-voicemail

Voicemail.... for the web! Create voicemails via WebRTC and Transcribe them.
Go
31
star
27

demo-conference

A simple web conferencing application built using Pion
HTML
29
star
28

webrtc-zero-downtime-restart

A playground to make WebRTC easier to deploy, safer and more robust
Go
21
star
29

webrtc-v3-design

EXPERIMENTAL - new API proposals and discussions
Go
17
star
30

signaler

The Pion Signaler
Go
15
star
31

dcnet

net interfaces over DataChannels
Go
14
star
32

portmap

An implementation of UPnP-IGD, NAT-PMP and PCP for configuring port-forwarding
Go
13
star
33

.goassets

Asset files automatically deployed to Go package repositories
Shell
9
star
34

codec

Go wrappers of multiple codecs to be go gettable
Go
7
star
35

logging

The logging library used by Pion
Go
7
star
36

website

Pion public website
HTML
7
star
37

turnc

RFC 5766 TURN client implementation in go
Go
6
star
38

producer

File to webrtc.Track playback
Go
5
star
39

talks

Content for talks given by Pion WebRTC developers
CSS
5
star
40

pion-browser-client

Browser Client for Pion
JavaScript
5
star
41

msapi

media stream api for webrtc !
Go
4
star
42

randutil

Helper library for cryptographic and mathmatical randoms
Go
4
star
43

zapion

uber-go/zap âš¡ backended pion logger
Go
3
star
44

pkg

Shared Go libraries used by Pion products
Go
3
star
45

ci-sandbox

CI testing sandbox
Go
2
star
46

simulnet

A net implementation that enables simulations
2
star
47

ion-admin

This is ion's manager
1
star
48

.github

Default community health files
1
star
49

rtpio

Go
1
star