shsp 1.11.1

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

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.11.0 - 2026-08-09

Added

• src/config/shsp_config.dart: config_manager-backed configuration surface — initShspConfig(), shspConfigSector, defaultShspConfig and ShspConfigExtension (defaultKeepAliveSeconds, defaultHandshakeTimeoutMs, defaultHandshakeIntervalMs, defaultRetryMaxAttempts, defaultRetryInitialDelayMs, defaultRetryBackoffMultiplier), replacing hardcoded defaults with overridable, deep-mergeable settings
• main_injection.dart (moved to src/): generated MainInjectionShspMixin/MainInjectionShsp with registerAllSingletonsShsp() / registerAllSingletonsShspAsync() and before/after hooks, wiring every @dependencyInjectable SHSP class into RegistryManager
• src/impl/registry/dual_shsp_registry_wiring.dart: connectDualShspSockets() (binds IPv4/IPv6 RawDatagramSockets best-effort, registering whichever succeeded under the 'ipv4'/'ipv6' subkeys, and throwing SocketException only if neither could be bound), connectShspSocketMigratableSubkeys(), connectAutoShspPeerSubkeys(), connectAutoShspInstanceSubkeys(), and DualShspInjector wiring all of the above into the DI before-register hooks
• src/impl/migration/shsp_socket_migration.dart / dual_shsp_socket_migration.dart: migrateShspSocket(), migrateShspSocketIpv4(), migrateShspSocketIpv6() and migrateDualShspSockets(), swapping the registered RawDatagramSocket/IShspSocket for a subkey/family while carrying the previous socket's profile over to the new one, without replacing the live IShspSocketMigratable/IDualShspSocketMigratable router
• IDualShspSocket.getSocket([InternetAddressType]) / DualShspSocket.getSocket(): unified accessor for the IPv4/IPv6 socket, replacing direct ipv4Socket/ipv6Socket field access in handshake and registry code
• RegistryShspSocket, DualShspSocketAuto, DualShspSocketMigratable and related classes are now @dependencyInjectable, with generated dependencyInjectionFactory() constructors resolving optional dependencies via RegistryManager.tryGetInstance()
• DualShspSocketAuto is now @dependencyInjectable directly: its unnamed constructor takes ipv4Migratable/ipv6Migratable (resolved via @Subkey('ipv4')/@Subkey('ipv6')), and the previous Sockets-based unnamed constructor is now DualShspSocketAuto.fromSockets(...)
• DualShspSocketMigratable is now @dependencyInjectable directly, mirroring DualShspSocketAuto: its unnamed constructor takes ipv4Migratable/ipv6Migratable, and the previous .fromMigratables(...) named constructor is merged into it; the old Sockets-based unnamed constructor is now DualShspSocketMigratable.fromSockets(...)

Changed

• RegistryManager (generic keyed registry, registry_utility.dart) renamed to KeyedRegistry/KeyedRegistryManager/KeyedRegistrySingleton, dropped its IValueForRegistry type bound, and now supports arbitrary Value types
• RegistryShspSocket switched from Registry to KeyedRegistry, gained an optional-socket constructor and a destroy() that iterates registered sockets directly instead of delegating to the removed Registry.destroyAll()
• Renamed ShspSocketWrapper → ShspSocketMigratable and IShspSocketWrapper → IShspSocketMigratable (with ShspSocketWrapperDelegationMixin → ShspSocketMigratableDelegationMixin) so the single-socket and dual-socket migration types share the same naming (ShspSocketMigratable / DualShspSocketMigratable)
• Renamed the associated members for the same reason: getSocketWrapper() → getSocketMigratable(), ipv4SocketWrapper/ipv6SocketWrapper → ipv4SocketMigratable/ipv6SocketMigratable, and the ipv4Wrapper/ipv6Wrapper parameters → ipv4Migratable/ipv6Migratable
• i_shsp_socket_wrapper.dart moved from src/interfaces/wrapper/ to src/interfaces/socket/i_shsp_socket_migratable.dart, alongside i_shsp_socket.dart/i_shsp_socket_base.dart
• main_injection.dart now registers IDualShspSocketAuto → DualShspSocketAuto and IDualShspSocketMigratable → DualShspSocketMigratable instead of IDualShspSocketWrapper → DualShspSocketWrapper, completing the DI tree: RawDatagramSocket → IShspSocket → IShspSocketMigratable → both IDualShspSocketAuto and IDualShspSocketMigratable resolve independently from the same ipv4/ipv6 instances
• RegistryShspSocket.initialize() / bind() updated to use getSocket() and ShspSocketMigratable/DualShspSocketMigratable instead of the removed wrapper types; initializeDI() removed
• Generated DI factories (AutoShspInstance, AutoShspPeer, RegistryShspSocket, ShspSocket, DualShspSocketAuto, DualShspSocketMigratable) resolve optional dependencies via RegistryManager.tryGetInstance() instead of the removed getInstanceNullable(), following the singleton_manager/singleton_manager_generator bump to ^2.2.2/^2.3.2

Removed

• handshake_ip.dart, IHandshakeIP and the stun package dependency — STUN-based public/local IP discovery dropped entirely, including its tests
• initialize_point.dart and its examples/tests (initializePointDualShsp, initializePointRegistryAccess) — superseded by main_injection.dart + dual_shsp_registry_wiring.dart
• DualShspSocketWrapper, IDualShspSocketWrapper, DualShspSocketWrapperDelegationMixin — merged into DualShspSocketAuto, which now owns its own DI resolution instead of being wrapped by a delegating facade
• RegistrySingletonShspSocket.initializeDI()

1.10.1 - 2026-07-15

Fixed

• AutoShspPeer.close() never unregistered its socket-changed listener from ShspSocketSingleton, leaking the callback registration after the peer was closed

Added

• New public mixins, exported from the package:shsp/shsp.dart barrel:
  • IdempotentCloseMixin: idempotent close() / destroy() with an isClosed flag and a closeImpl() hook
  • MessageSizeValidationMixin: shared outgoing-message validation (closed state, empty payload, max UDP size)
  • SocketChangeListenerMixin: registration/deregistration of a singleton socket-changed listener that re-registers the message callback on the new socket
  • SocketProfileTransferMixin: profile extract/close/rebuild/apply/notify sequence for socket replacement (transferProfileAsync / transferProfileSync)
  • ShspSocketWrapperDelegationMixin / DualShspSocketWrapperDelegationMixin: member-by-member delegation to the wrapped socket

Changed

• ShspPeer, ShspSocket, ShspSocketWrapper, DualShspSocketWrapper, BaseShspSocketSingleton, AutoShspPeer and AutoShspInstance refactored to use the new mixins instead of duplicated inline logic (no behavioral change besides the fix above)

1.10.0 - 2026-07-13

Added

• DualShspSocketAuto.fromMigratable() constructor to build an auto-refreshing dual socket from an existing DualShspSocketMigratable
• IDualShspSocketMigratable.ipv4SocketWrapper / ipv6SocketWrapper getters, throwing StateError when the underlying socket isn't wrapped

Changed

• ShspSocket.bindDefault() now defaults ipv6 to true (previously false)
• buildDualSocket() (used by initializePointDualShsp() and initializePointRegistryAccess()) now returns IDualShspSocketAuto, built via DualShspSocketAuto.create(), instead of manually wiring DualShspSocketMigratable
• initializePointDualShsp() and initializePointRegistryAccess() now also register the socket under IDualShspSocketAuto, in addition to the existing IDualShspSocketMigratable registration
• DualShspSocketWrapperDI now resolves IDualShspSocketAuto from DI instead of IDualShspSocketMigratable
• IDualShspSocketWrapper.internalSocket now typed as IDualShspSocketAuto (previously IDualShspSocketMigratable)
• Socket wrapper files reorganized: src/impl/socket/wrappers/ merged into src/impl/socket/core/shsp_socket_wrapper.dart and src/impl/socket/dual/dual_shsp_socket_wrapper.dart

Fixed

• Copy-paste bug in DualShspSocketAuto.fromMigratable() that assigned the IPv4 wrapper to both the IPv4 and IPv6 slots
• DualShspSocketWrapper and Sockets were missing from the package:shsp/shsp.dart barrel export after the wrappers/ → core/+dual/ file move; regenerated via index_generator
• AddressUtility.parseAddress() test expectation and getLocalIp() / canCreateIPv6Socket() call sites updated to match their Future-returning signatures

Test Coverage

• Added fromMigratable test group (dual_shsp_socket_auto_test.dart) asserting IPv4/IPv6 wrappers are distinct instances, covering the previously-untested constructor where the copy-paste bug above was hiding
• Added dual_shsp_socket_wrapper_test.dart: full coverage for DualShspSocketWrapper's three constructors (default, emptyForDI, createFromSocket) and every delegated member, with IPv4/IPv6 pairs asserted as distinct instances to catch swap-style bugs

1.9.0 - 2026-07-12

Added

DualShspSocket as IShspSocket

• IDualShspSocket no longer extends IShspSocket — it is now a pure router interface extending IShspSocketBase
• IShspSocketBase extracted from IShspSocket providing core members (onClose, onError, onListening, setMessageCallback, sendTo, isClosed, destroy) without the RawDatagramSocket contract
• IDualShspSocketAuto interface for auto-detecting and refreshing dual-stack socket instances

Optional IPv4/IPv6

• IPv4 socket is now optional in DualShspSocket — the framework works with IPv6-only or IPv4-only setups
• DualShspSocket.create() attempts IPv6 first, then IPv4, and works if at least one succeeds
• socket getter returns IPv6 socket with IPv4 fallback
• localAddress, localPort, compressionCodec all prefer IPv6 with IPv4 fallback

Auto-Detection via DualShspSocketAuto

• DualShspSocketAuto automatically refreshes underlying sockets to handle network changes
• refreshSocketIpv4(), refreshSocketIpv6(), refreshSockets() methods for on-demand socket refresh
• Implements IDualShspSocketMigratable for seamless socket migration

New Types

• Sockets value object holding optional IPv4 and IPv6 IShspSocket references
• Centralized in src/types/sockets.dart
• Used throughout DualShspSocket, DualShspSocketMigratable, and DualShspSocketWrapper constructors

Enhanced Callback Types

• CallbackOnWithSocket and CallbackOnErrorWithSocket — callbacks now carry the source socket reference in DualShspSocket events
• Event handlers can identify which socket (IPv4 vs IPv6) triggered the event

Changed

Interface Reorganization

• IShspSocket moved to src/interfaces/socket/i_shsp_socket.dart
• IDualShspSocket moved to src/interfaces/dual/i_dual_shsp_socket.dart
• IDualShspSocketMigratable moved to src/interfaces/dual/i_dual_shsp_socket_migratable.dart
• IDualShspSocketAuto added to src/interfaces/dual/i_dual_shsp_socket_auto.dart
• IShspSocketBase added to src/interfaces/socket/i_shsp_socket_base.dart

DualShspSocket Constructor Change (Breaking)

• Constructor now accepts Sockets sockets instead of (IShspSocket ipv4Socket, IShspSocket? ipv6Socket)
• fromSockets factory now takes Sockets instead of two parameters

IPv4/IPv6 Preference Changes

• localAddress returns IPv6 address first (previously IPv4 first)
• localPort returns IPv6 port first (previously IPv4 first)
• compressionCodec prefers IPv6 codec (previously IPv4 first)
• isClosed uses AND logic (both must be closed) instead of OR

ISendTo Validation

• sendTo() validates address family matches available socket type
• Throws StateError when sending IPv6 address with only IPv4 socket (and vice versa)

Fixed

Bug Fixes

• Handshake IP mapping race condition resolved
• Socket callback forwarding in dual socket properly identifies source socket
• Message callback map IPv4/IPv6 key parity fixed
• Various constructor consistency improvements across factories

Test Coverage

• 1,589+ comprehensive test lines added for dual socket scenarios:
  • dual_shsp_socket_comprehensive_test.dart: 1,286 lines covering IPv4-only, IPv6-only, dual-stack, and migration scenarios
  • dual_shsp_socket_auto_test.dart: 303 lines testing auto-detection and socket refresh

1.8.0 - 2026-04-20

Added

Test Coverage

• 10 comprehensive test files with 227+ test cases covering all SHSP components:
  • shsp_exceptions_test.dart: All 6 exception types (ShspProtocolException, ShspNetworkException, ShspValidationException, ShspHandshakeException, ShspInstanceException, ShspConfigurationException)
  • peer_types_test.dart: PeerInfo/RemoteInfo with JSON round-trips, equality, and hashCode
  • address_utility_test.dart: AddressUtility static methods (format, parse, fromString, getLocalIp, canCreateIPv6Socket)
  • callback_map_test.dart: Generic CallbackMap
  • compression_codecs_test.dart: All 3 compression codecs (GZipCodec, ZstdCodec, LZ4Codec)
  • keep_alive_timer_test.dart: KeepAliveTimer lifecycle (periodic, from, cancel, resetTick)
  • shsp_socket_test.dart: ShspSocket operations (bind, fromRaw, close, sendTo, profile round-trips)
  • dual_shsp_socket_test.dart: DualShspSocket and SimpleDualSocketSingleton
  • shsp_peer_test.dart: ShspPeer construction, validation, delivery, and lifecycle
  • shsp_instance_test.dart: ShspInstance message routing (0x00-0x04 prefixes) and state machine
  • shsp_handlers_and_factories_test.dart: ShspHandshakeHandler, ShspInstanceHandler, and all Factory classes

Coverage includes: exceptions, types, utilities, callbacks, sockets (single/dual), peers, instances, handlers, factories, and compression.

Test patterns: Manual mocks (no mockito), Future.microtask() for callbacks, Future.delayed() for timers, real UDP sockets on loopback, full internal src/ imports enabled.

Changed

• Documentation now aligns with comprehensive test coverage
• Quality baseline established with 227 test cases passing

Result: ✅ Comprehensive test suite - All major components verified

1.7.1 - 2026-04-11

Fixed

Code Quality

• Removed unused import dart:typed_data from peer_communicator.dart
• Removed unused variable startTime from test file
• Added const keyword to all constructors for performance optimization
• Fixed double literal 2.0 to 2 where appropriate
• Optimized const declarations in test code

Result: ✅ Zero dart analyze issues - Ready for pub.dev maximum score

1.7.0 - 2026-03-30

Added

• IDualShspSocketWrapper interface for DualShspSocketWrapper/DualShspSocketWrapperDI proxy
• IRegistryShspSocket interface for RegistryShspSocket

Changed

• buildDualSocket() now returns IDualShspSocketMigratable instead of DualShspSocketMigratable
• initializePointDualShsp() registers registry under IRegistryShspSocket interface
• initializePointRegistryAccess() uses IDualShspSocketWrapper and IRegistryShspSocket as registration keys
• DualShspSocketWrapper now explicitly implements IDualShspSocketWrapper
• RegistryShspSocket now explicitly implements IRegistryShspSocket
• ShspHandshakeHandler.handshakeInstance rewritten as event-driven (Completer + Timer.periodic) instead of polling; eliminates a race condition where the onOpen callback was never invoked when the socket read event and the delay timer fired in the same event-loop tick

1.6.1 - 2026-03-30

Changed

• Updated singleton_manager dependency from ^0.5.0 to ^0.6.1

1.6.0 - 2026-03-26

Changed

• Updated singleton_manager dependency from ^0.4.0 to ^0.5.0
• Updated singleton_manager_generator dev dependency from ^1.0.4 to ^1.2.0
• Renamed isClosing() to isClosingMessage() in ShspInstanceHandshakeMixin
• Renamed isClosed() to isClosedMessage() in ShspInstanceHandshakeMixin

Removed

• Removed archive dependency

1.5.0 - 2026-03-20

Changed

• IDualShspSocketMigratable is now the primary DI type replacing IDualShspSocket throughout the framework
  • initializePointDualShsp() now creates a DualShspSocketMigratable (instead of DualShspSocket) and registers it under IDualShspSocketMigratable
  • DualShspSocketWrapper.dualSocket and internalSocket setter are now typed IDualShspSocketMigratable
  • ISimpleDualSocketSingleton.getInstance() / setInstance() now use IDualShspSocketMigratable
  • RegistryShspSocket.initialize() now accepts IDualShspSocketMigratable; bind() creates DualShspSocketMigratable internally
  • RegistryShspSocket.initializeDI() resolves IDualShspSocketMigratable from DI

Breaking Changes

• SingletonDIAccess.get<IDualShspSocket>() is no longer registered by initializePointDualShsp() — use get<IDualShspSocketMigratable>() instead
• ISimpleDualSocketSingleton.setInstance() now requires an IDualShspSocketMigratable; plain IDualShspSocket instances are no longer accepted

1.4.0 - 2026-03-20

Added

• IShspSocketWrapper interface: New contract for socket proxy/wrapper classes
  • migrateSocket(IShspSocket newSocket) — swaps the underlying socket and re-applies stored callbacks
• IDualShspSocketMigratable interface: Contract for dual-socket migration
  • migrateSocketIpv4(IShspSocket socket) — replaces the IPv4 underlying socket
  • migrateSocketIpv6(IShspSocket socket) — replaces or adds the IPv6 underlying socket
• DualShspSocketMigratable: New class extending DualShspSocket that implements IDualShspSocketMigratable
  • Wraps raw sockets in ShspSocketWrapper automatically via its default constructor
  • fromWrappers named constructor for pre-wrapped socket injection
  • Enables live socket migration without losing peer callbacks or references

Changed

• ShspSocketWrapper now implements IShspSocketWrapper instead of bare IShspSocket
  • Added anti-nesting guard: wrapping another ShspSocketWrapper throws ArgumentError
  • Stores listening, close, and error callbacks internally so they are re-applied on every migrateSocket() call

1.3.0 - 2026-03-19

Added

• IShspSocket implements RawDatagramSocket: The socket interface now extends RawDatagramSocket directly, making IShspSocket a full drop-in replacement for RawDatagramSocket in any Dart API
  • ShspSocketWrapper provides complete delegation of all RawDatagramSocket members (address, port, send, receive, broadcastEnabled, multicastLoopback, multicastHops, multicastInterface, readEventsEnabled, writeEventsEnabled, joinMulticast, leaveMulticast, etc.)
  • Added _raw computed getter in ShspSocketWrapper — automatically reflects the current underlying socket after any swap

Changed

• IShspSocket: Added explicit destroy() method to the interface contract
• IDualShspSocket: Removed redundant socket getter — RawDatagramSocket access is now inherited through IShspSocket
• DualShspSocketWrapper: Removed socket override for the same reason
• Removed redundant imports in dual_shsp_socket.dart and initialize_point.dart

Breaking Changes

• Any class implementing IShspSocket must now also implement all RawDatagramSocket members

1.2.4 - 2026-03-19

Fixed

• Incomplete shsp.dart barrel: Regenerated root library with all missing exports
  • Added factory interfaces: i_shsp_instance_factory, i_shsp_peer_factory, i_shsp_socket_factory
  • Added utility interfaces: i_address_utility, i_callback_map, i_keep_alive_timer, i_message_callback_map, i_message_callback_map_singleton, i_raw_shsp_socket, i_shsp_socket_info_singleton
  • Added socket features: shsp_socket_callbacks, shsp_socket_compression, shsp_socket_profile
  • Added dual socket: dual_shsp_socket_message, dual_shsp_socket_profile
  • Reorganized exports in alphabetical/logical order

1.2.3 - 2026-03-19

Fixed

• Missing Index Export: Added i_shsp_socket_base.dart to src/interfaces/index.dart
  • The interface was accessible via the root shsp.dart but missing from the sub-index barrel

1.2.2 - 2026-03-19

Fixed

• Analyzer Issues: Resolved all Dart analyzer warnings and errors
  • Removed unused local variables
  • Added missing test dependencies (singleton_manager)
  • Updated deprecated callback setters to use new CallbackHandler.register() pattern
    • setListeningCallback() → onListening.register((_) {})
    • setCloseCallback() → onClose.register((_) {})
    • setErrorCallback() → onError.register((_) {})

1.2.1 - 2026-03-14

Added

• Initialize Point Function: New initializePointDualShsp() function for convenient singleton setup
  • Automatically initializes IPv4 and IPv6 sockets
  • Handles IPv6 availability detection
  • Sets up dual socket and registry singleton
• Socket Wrapper: New ShspSocketWrapper class for transparent socket replacement
  • Implements proxy pattern to allow underlying socket swapping
  • Maintains stable references while supporting socket migration
  • Enables graceful socket reconnection and state transfer

Changed

• Improved singleton initialization pattern with dedicated entry point
• Registry initialization now integrated into centralized initialization flow

1.2.0 - 2026-03-11

Added

• Registry System: New generic registry pattern with mixin-based API for managing multiple instances:
  • Registry<Key, Value> mixin for key-value based instance management
  • Singleton class for type-based instance management
  • IValueForRegistry interface for registry-managed objects
  • RegistryMixin trait for registering and managing sockets/peers
• Extended Interface Support: Socket and peer interfaces now support registry integration:
  • IShspSocket implements IValueForRegistry with destroy() method
  • IShspPeer implements IValueForRegistry with proper cleanup
• Socket Type Enumeration: New SocketType enum for IPv4/IPv6 socket management
• Registry Utilities: Helper functions for socket registry initialization and management

Changed

• Registry Version Preservation: Registry now preserves element version during updates instead of incrementing
  • register() maintains the existing version when updating an element
  • New elements are initialized with version 0
  • This enables stable version tracking across updates

Fixed

• Improved resource cleanup with destroy() methods throughout the API
• Better type safety with registry-based instance management

1.0.0 - 2026-03-10

Added

• Initial release of the unified SHSP (Single HandShake Protocol) package
• Core networking protocol implementation for peer-to-peer communication over UDP
• ShspSocket: Main UDP socket implementation with callback management
• ShspPeer: High-level peer abstraction for bidirectional communication
• ShspInstance: Protocol instance with automatic keep-alive support
• ShspSocketSingleton: Global socket management with state transfer and reconnection support
• AutoShspPeer: Auto-wiring peer that binds to ShspSocketSingleton with automatic reconnection
• AutoShspInstance: Auto-wiring instance with automatic socket management
• Compression support with three pluggable codecs:
  • GZipCodec: Best compression ratio
  • LZ4Codec: Fast compression with reasonable ratios
  • ZstdCodec: Balanced compression and speed
• Comprehensive type definitions:
  • RemoteInfo: Address and port information
  • SocketProfile: Socket configuration and state tracking
  • InstanceProfile: Instance configuration and state tracking
  • Callback type definitions for various protocol events
• IPv4 and IPv6 support with automatic address formatting
• Dual-stack socket support for seamless IPv4/IPv6 interoperability
• CallbackMap and MessageCallbackMap utilities for managing callbacks
• AddressUtility for address formatting
• Complete interface contracts for extensibility
• 399+ comprehensive tests ensuring reliability
• Multi-platform support (Dart CLI, Flutter mobile, web)
• Comprehensive documentation and examples
• GitHub Actions CI/CD pipeline
• LGPL-3.0 license

Features

• Automatic handshake with configurable timeouts and retry intervals
• Configurable keep-alive heartbeat (default: 30 seconds)
• Non-blocking async/await API throughout
• Singleton pattern for global socket management
• Callback-based message/data reception
• Automatic socket state management and reconnection
• Extensible compression codec interface
• Full type safety with Dart type system