stun_shsp 0.3.0

Combines STUN (RFC 5389) and SHSP protocols into a unified handler for NAT traversal and peer-to-peer UDP communication. Supports dual IPv4/IPv6 stacks, runtime socket migration, optional compression, [...]

stun_shsp

A Dart package that combines the STUN and SHSP protocols into a single unified handler for NAT traversal and peer-to-peer data communication.

Features

• NAT traversal via STUN (RFC 5389) — discover your public IP and port
• Dual-stack IPv4 + IPv6 support with graceful IPv6 fallback
• SHSP socket for compressed, structured UDP communication
• Socket migration — swap IPv4/IPv6 sockets at runtime without tearing down the handler
• Dependency injection via singleton_manager with a generated DI class
• Singleton pattern — StunShspHandlerSingleton ensures one instance per process
• One-call initialization via initializePointStunShsp()

Installation

Add to your pubspec.yaml:

dependencies:
  stun_shsp: ^0.2.2

Then run:

dart pub get

What's New in 0.2.2

Fix: IShspSocket now registered in DI container

initializePointStunShsp() was not registering the IPv4 IShspSocket as an autonomous DI type. Consumers calling SingletonDIAccess.get<IShspSocket>() would get a StateError. Fixed in 0.2.2.

Also includes consolidated test suites (unit + integration) with identity-verification tests for the full DI object graph.

What's New in 0.2.0

Major Refactor: STUN runs on the SHSP socket

Previously, STUN requests were sent from a separate raw socket, which could result in the discovered public port not matching the port that P2P peers use to reach this node. This is now fixed:

• STUN Binding Requests are now sent from the same SHSP socket used for P2P data communication
• The public port returned by performStunRequest() is guaranteed to match the port peers must connect to
• Added comprehensive test suite (stun_shsp_handler_port_test.dart) to catch port-mismatch regressions
• Updated dependencies: stun: ^1.5.1, shsp: ^1.8.0
• Requires Dart >=3.5.0

See CHANGELOG.md for details.

Usage

Quick start with DI (recommended)

Initialize all dependencies in one call and resolve via SingletonDIAccess:

import 'package:stun_shsp/stun_shsp.dart';

Future<void> main() async {
  // Initialize SHSP sockets, STUN handlers and DI wiring
  await initializePointStunShsp();

  final handler = SingletonDIAccess.get<IStunShspHandler>();

  // Discover public IP / port via STUN
  final stunResponse = await handler.performStunRequest();
  print('Public address: ${stunResponse.publicIp}:${stunResponse.publicPort}');

  // Use the SHSP socket for peer communication
  final socket = handler.dualShspSocket;
  // ...

  handler.close();
}

Manual instantiation

import 'package:stun_shsp/stun_shsp.dart';

final handler = StunShspHandlerSingleton();

await handler.initialize(
  address: '0.0.0.0',
  port: 5000,
  timeout: Duration(seconds: 5),
  compressionCodec: MyCodec(), // optional
);

// NAT detection
final stunResponse = await handler.performStunRequest();
print('Public IP: ${stunResponse.publicIp}');
print('Public port: ${stunResponse.publicPort}');

// Local address info
final localInfo = await handler.performLocalRequest();
print('Local address: ${localInfo.address}:${localInfo.port}');

// IPv4 socket
final ipv4Socket = handler.ipv4ShspSocket;

// IPv6 socket (null when IPv6 is unavailable on the system)
final ipv6Socket = handler.ipv6ShspSocket;

// Dual socket — routes automatically between IPv4/IPv6
final dual = handler.dualShspSocket;

handler.close();

Socket migration

Replace a running socket without recreating the handler:

final newSocket = await ShspSocket.bind(InternetAddress.anyIPv4, 0);
handler.migrateSocketIpv4(newSocket);

final newIpv6Socket = await ShspSocket.bind(InternetAddress.anyIPv6, 0);
handler.migrateSocketIpv6(newIpv6Socket);

Custom STUN server

handler.setStunServer('stun.example.com', 3478);
handler.setStunServer('stun6.example.com', 3478, ipv6: true);

final ok = await handler.pingStunServer();

API

initializePointStunShsp()

Bootstraps the full dependency graph:

1. Initializes dual SHSP sockets (initializePointDualShsp)
2. Initializes STUN handlers bound to those sockets
3. Creates and registers StunShspHandlerDI in the DI container

After this call you can resolve IStunShspHandler, IShspSocket, StunHandlerBase, IDualShspSocketMigratable, IDualStunHandler, IDualCallbackHandler, and more from SingletonDIAccess.

---

IStunShspHandler

Member	Description
initialize({address, port, timeout, compressionCodec})	Bind sockets and prepare handlers
performStunRequest()	Query STUN server, returns StunResponse
performLocalRequest()	Returns LocalInfo (local address/port)
pingStunServer({ipv6})	Checks reachability of configured STUN server
setStunServer(address, port, {ipv6})	Override STUN server address
migrateSocketIpv4(socket)	Swap the active IPv4 IShspSocket
migrateSocketIpv6(socket)	Swap the active IPv6 IShspSocket
dualShspSocket	The IDualShspSocketMigratable unified socket
ipv4ShspSocket	Direct access to the IPv4 IShspSocket
ipv6ShspSocket	Direct access to the IPv6 IShspSocket (nullable)
stunHandler	Underlying StunHandlerBase for advanced use
close({ipv6})	Close sockets and release resources

---

StunShspHandler

Concrete implementation of IStunShspHandler. Annotated with @isSingleton for DI code generation. Accepts injected dependencies via injectDependencies(...).

---

StunShspHandlerSingleton

Extends StunShspHandler with a Dart singleton factory:

final a = StunShspHandlerSingleton();
final b = StunShspHandlerSingleton();
assert(identical(a, b)); // true

---

StunShspHandlerDI (generated)

Auto-generated class in lib/generated/stun_shsp_handler_di.dart. Implements ISingletonStandardDI and resolves dependencies from SingletonDIAccess at construction time. Do not instantiate directly — use initializePointStunShsp() instead.

Dependencies

Package	Role
stun	STUN protocol, NAT detection
shsp	Structured UDP socket with optional compression
singleton_manager	DI container and singleton lifecycle

License

MIT