shsp 1.11.1

Single HandShake Protocol (SHSP) - a custom networking protocol for peer-to-peer communication. Unified package containing types, interfaces, and implementations.

example/README.md

SHSP Examples

This directory contains practical examples of using the Single HandShake Protocol (SHSP) package.

Examples

0. Initialize Point (initialize_point.dart) - v1.2.1+

The recommended starting point for most applications. Sets up the global socket singleton with IPv4/IPv6 support in one call. As of v1.9.0, IPv4 is now optional — the singleton works with any available address family.

Demonstrates:

• Using initializePointDualShsp() for easy setup
• Accessing the global dual socket singleton via IDualShspSocketMigratable
• Setting up socket lifecycle callbacks
• Extracting socket profiles
• Proper resource cleanup with DualShspSocketSingleton

Run:

dart example/initialize_point.dart

0b. Initialize Point - Registry Access (initialize_point_registry_access.dart) - v1.7.0+

Key-based alternative to initializePointDualShsp(). Stores socket instances under explicit string keys in the global registry, enabling multiple independent dual-socket instances.

Demonstrates:

• initializePointRegistryAccess() for key-based singleton registration
• Accessing sockets via RegistryAccess.getInstance<IDualShspSocketMigratable>(key)
• Running multiple named socket instances side by side
• Proper registry cleanup with RegistryAccess.unregister()

Run:

dart example/initialize_point_registry_access.dart

1. Basic Peer (basic_peer.dart)

The simplest example - create a peer, send data, and receive messages.

Demonstrates:

• Creating a peer connection
• Registering message callbacks
• Sending data
• Proper cleanup

Run:

dart example/basic_peer.dart

2. Instance with Keep-Alive (instance_with_keepalive.dart)

Create a long-lived connection with automatic keep-alive support and lifecycle callbacks.

Demonstrates:

• Creating an instance with keep-alive
• Lifecycle callbacks (handshake, opening, data, closing, close)
• Long-lived connection management
• Proper cleanup with state notifications

Run:

dart example/instance_with_keepalive.dart

3. Socket Singleton with Compression (singleton_with_compression.dart)

Advanced example using global socket management and data compression.

Demonstrates:

• Using ShspSocketSingleton for global socket management
• Multiple peers sharing the same socket
• Data compression (GZip, Zstd)
• Socket switching and automatic peer reconnection

Run:

dart example/singleton_with_compression.dart

4. Using Interfaces (using_interfaces.dart)

Demonstrates dependency injection and interface-based design for better testability.

Demonstrates:

• Type-safe programming with interfaces
• Dependency injection patterns
• Factory interfaces for custom creation logic
• Benefits for unit testing and mocking

Run:

dart example/using_interfaces.dart

5. Registry Management (registry_management.dart) - v1.2.0+

Advanced example showcasing the new registry system for managing multiple instances.

Demonstrates:

• Socket registry for managing multiple sockets (IPv4/IPv6)
• Peer manager using the Registry mixin pattern
• Instance manager with lifecycle support
• Broadcast patterns for multiple destinations
• Proper resource cleanup and lifecycle management

Run:

dart example/registry_management.dart

6. Socket Migration (socket_migration.dart) - v1.4.0+

Demonstrates live socket migration using ShspSocketMigratable and DualShspSocketMigratable. As of v1.9.0, constructor uses the Sockets value object and IPv4 is optional.

Demonstrates:

• Single-socket migration with ShspSocketMigratable
• Dual-socket migration with DualShspSocketMigratable.fromSockets(...)
• The DI-shaped DualShspSocketMigratable(ipv4Migratable: ..., ipv6Migratable: ...) constructor for pre-configured socket injection
• Callback preservation across socket migrations

Run:

dart example/socket_migration.dart

7. Using Mixins (using_mixins.dart) - v1.10.1+

Build custom components from the public SHSP mixins exported by the shsp.dart barrel.

Demonstrates:

• IdempotentCloseMixin for safe, idempotent close()/destroy() with a single closeImpl() hook
• MessageSizeValidationMixin for standard outgoing-message validation (closed state, empty payload, max UDP size)
• Standard SHSP exceptions (ShspValidationException, ShspNetworkException) thrown by the validation helpers

Run:

dart example/using_mixins.dart

Common Patterns

Creating a Peer

final peer = await AutoShspPeer.create(
  remoteInfo: RemoteInfo.fromString('192.168.1.100:8080')!,
);

Creating an Instance (with keep-alive)

final instance = await AutoShspInstance.create(
  remoteInfo: RemoteInfo.fromString('192.168.1.100:8080')!,
  keepAliveSeconds: 30,
);

Using Custom Socket

final socket = await ShspSocket.bind(InternetAddress.anyIPv4, 9000);
final peer = await AutoShspPeer.create(
  remoteInfo: RemoteInfo.fromString('192.168.1.100:8080')!,
  socket: socket,
);

With Compression

final peer = await AutoShspPeer.create(
  remoteInfo: RemoteInfo.fromString('192.168.1.100:8080')!,
  compressionCodec: ZstdCodec(), // or GZipCodec(), LZ4Codec()
);

Receiving Messages

peer.onMessage((message) {
  print('From: ${message.remotePeer.address}:${message.remotePeer.port}');
  print('Payload: ${message.payload}');
});

Testing

All examples can be tested by running:

dart pub get

# Start with the initialization point (recommended first)
dart example/initialize_point.dart

# Then try other examples
dart example/basic_peer.dart
dart example/instance_with_keepalive.dart
dart example/singleton_with_compression.dart
dart example/using_interfaces.dart
dart example/registry_management.dart
dart example/socket_migration.dart
dart example/using_mixins.dart
dart example/initialize_point_registry_access.dart

Note: Some examples require a remote SHSP server running on the specified address/port to fully demonstrate functionality. For isolated testing, see the test suite in packages/tests/.

Troubleshooting

• "Connection refused": Ensure there's a remote SHSP server listening on the specified address/port
• "Port already in use": Another process is using the port; use a different port number
• "Permission denied": Ports below 1024 require elevated privileges; use ports >= 1024

License

These examples are part of the SHSP package and are licensed under LGPL-3.0.