com.netsync.core 2.0.0-rc.4 → 2.0.0-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
@@ -310,13 +310,14 @@
310
310
  </member>
311
311
  <member name="F:NetSync.KeyExchangeMode.PresharedKey">
312
312
  <summary>
313
- Both sides share a secret key out-of-band; per-connection keys are derived
314
- from it and the session token. Simple and works everywhere.
313
+ Both sides share a secret key out-of-band. Every connection still runs an ephemeral
314
+ key exchange, so session keys are fresh each time and past sessions stay private
315
+ even if the shared key leaks later; the shared key is what authenticates the peers.
315
316
  </summary>
316
317
  </member>
317
318
  <member name="F:NetSync.KeyExchangeMode.Ecdh">
318
319
  <summary>
319
- Ephemeral ECDH (P-256) during the handshake: no pre-shared secret needed.
320
+ Ephemeral key exchange (X25519) during the handshake: no pre-shared secret needed.
320
321
  Give the server a <see cref="P:NetSync.EncryptionConfig.ServerIdentity"/> and pin its key on
321
322
  clients (<see cref="P:NetSync.EncryptionConfig.TrustedServerKeys"/>) to stop an active
322
323
  man-in-the-middle; without pinning it only defeats passive eavesdropping.
@@ -379,6 +380,9 @@
379
380
  policy: client and server may choose differently, it is not part of the handshake.
380
381
  </summary>
381
382
  </member>
383
+ <member name="P:NetSync.ChannelConfig.IsReliable">
384
+ <summary>The channel promises delivery: a stream slot, or a reliable mode on the datagram slot.</summary>
385
+ </member>
382
386
  <member name="T:NetSync.NetConfig">
383
387
  <summary>
384
388
  Shared configuration for <see cref="T:NetSync.Peers.NetClient"/> and <see cref="T:NetSync.Peers.NetServer"/>.
@@ -387,6 +391,22 @@
387
391
  channel 0 = TCP, channel 1 = UDP.
388
392
  </summary>
389
393
  </member>
394
+ <member name="P:NetSync.NetConfig.AppId">
395
+ <summary>
396
+ Names the application. A server refuses clients whose AppId differs, so two
397
+ different applications that happen to reach each other (same port, same relay)
398
+ never connect. Empty = not checked beyond both sides leaving it empty.
399
+ </summary>
400
+ </member>
401
+ <member name="P:NetSync.NetConfig.AppProtocolVersion">
402
+ <summary>
403
+ The application's own protocol version. A server refuses clients with another
404
+ value: raise it when a release can't talk to the previous one.
405
+ </summary>
406
+ </member>
407
+ <member name="P:NetSync.NetConfig.AppIdHash">
408
+ <summary>What travels in the handshake for <see cref="P:NetSync.NetConfig.AppId"/>: the first 8 bytes of its SHA-256 (0 when empty).</summary>
409
+ </member>
390
410
  <member name="P:NetSync.NetConfig.PingIntervalMs">
391
411
  <summary>Keepalive ping period per transport link.</summary>
392
412
  </member>
@@ -409,11 +429,20 @@
409
429
  the connection is closed with Timeout instead of hanging. 0 disables.
410
430
  </summary>
411
431
  </member>
432
+ <member name="P:NetSync.NetConfig.CloseFlushTimeoutMs">
433
+ <summary>
434
+ Server only: how long a kick or a shutdown waits for what is already queued for the
435
+ client (the notice itself included) to be written before the links close. A client
436
+ that has stopped reading can hold a kick up for this long, and no longer.
437
+ </summary>
438
+ </member>
412
439
  <member name="P:NetSync.NetConfig.MaxPendingEvents">
413
440
  <summary>
414
- Polled mode only: cap on undelivered events. When PollEvents() isn't called
415
- for a while, data events beyond the cap are dropped (with a warning) instead
416
- of growing memory without bound. Connect/disconnect events are never dropped.
441
+ Polled mode only: cap on undelivered events, so memory can't grow without bound when
442
+ PollEvents() isn't called for a while. Beyond the cap, messages of unreliable channels
443
+ are dropped (with a warning); a message of a reliable channel closes its connection
444
+ with <see cref="F:NetSync.Transports.DisconnectReason.Overloaded"/> instead of being lost
445
+ silently. Connect/disconnect events are never dropped.
417
446
  </summary>
418
447
  </member>
419
448
  <member name="P:NetSync.NetConfig.MaxConnections">
@@ -594,6 +623,9 @@
594
623
  <member name="F:NetSync.Peers.ConnectionRejection.Application">
595
624
  <summary>The server application refused (ConnectionApprover, or server full).</summary>
596
625
  </member>
626
+ <member name="F:NetSync.Peers.ConnectionRejection.ApplicationMismatch">
627
+ <summary>The server runs another application or application protocol version (NetConfig.AppId / AppProtocolVersion).</summary>
628
+ </member>
597
629
  <member name="T:NetSync.Peers.ConnectionRejectedException">
598
630
  <summary>The server refused the connection, or the client refused the server.</summary>
599
631
  </member>
@@ -620,8 +652,10 @@
620
652
  which are rare, keep their closures).
621
653
 
622
654
  The Polled queue is bounded: if the application stops polling (paused game,
623
- forgotten call) data events beyond the cap are dropped with a warning instead of
624
- growing memory forever. Lifecycle events (connect/disconnect) are never dropped.
655
+ forgotten call) memory must not grow forever. Beyond the cap, events of unreliable
656
+ channels are dropped with a warning; for a reliable channel the caller is told and
657
+ closes the connection — a reliable message is never lost silently. Lifecycle
658
+ events (connect/disconnect) are never dropped.
625
659
  </summary>
626
660
  </member>
627
661
  <member name="P:NetSync.Peers.EventDispatcher.IsImmediate">
@@ -639,7 +673,8 @@
639
673
  <member name="M:NetSync.Peers.EventDispatcher.QueueData(System.Object,System.Byte,System.Byte[],System.Int32,System.Int32)">
640
674
  <summary>
641
675
  Polled mode: queues a data event, copying the payload into a pooled buffer
642
- (the caller's buffer is only valid during this call). May drop when full.
676
+ (the caller's buffer is only valid during this call). False = the queue is full
677
+ and the event was not queued.
643
678
  </summary>
644
679
  </member>
645
680
  <member name="M:NetSync.Peers.EventDispatcher.Poll(System.Int32)">
@@ -668,10 +703,17 @@
668
703
  <summary>The configuration lets UDP channels ride TCP when UDP fails.</summary>
669
704
  </member>
670
705
  <member name="M:NetSync.Peers.NetClient.EstablishKeys(NetSync.Peers.NetClient.Session,NetSync.Peers.PeerProtocol.Welcome)">
671
- <summary>
672
- First Welcome: check the server's choice of suite, verify its identity, derive the
673
- session keys. Returns the reason to refuse the server, or null. Caller holds CryptoLock.
674
- </summary>
706
+ <summary>
707
+ First Welcome: check what the server chose, complete the key exchange, derive the
708
+ session keys. Returns the reason to refuse the server, or null. Caller holds CryptoLock.
709
+
710
+ A server identity is not proven here: it is mixed into the keys, so a server without
711
+ the private key ends up with different ones and the connection never opens
712
+ (see <see cref="M:NetSync.Peers.NetClient.KeysDifferRejection(NetSync.Peers.NetClient.Session)"/>).
713
+ </summary>
714
+ </member>
715
+ <member name="M:NetSync.Peers.NetClient.KeysDifferRejection(NetSync.Peers.NetClient.Session)">
716
+ <summary>Client and server derived different session keys: which secret was wrong depends on the mode.</summary>
675
717
  </member>
676
718
  <member name="M:NetSync.Peers.NetClient.FailConnect(NetSync.Peers.NetClient.Session,System.Exception)">
677
719
  <summary>The connect attempt fails with <paramref name="error"/> (every pending wait observes it).</summary>
@@ -966,8 +1008,8 @@
966
1008
  </member>
967
1009
  <member name="M:NetSync.Peers.NetServer.CreateConnection(NetSync.Peers.PeerProtocol.Hello,NetSync.CipherSuite,System.Byte[])">
968
1010
  <summary>
969
- Builds a pending connection from its first Hello: keys (PSK or ECDH), the chosen
970
- suite, and the Welcome every link will get — signed when the server has an identity.
1011
+ Builds a pending connection from its first Hello: the server's half of the key
1012
+ exchange, the session keys, the chosen suite, and the Welcome every link will get.
971
1013
  Returns null when the client's key material is unusable.
972
1014
  </summary>
973
1015
  </member>
@@ -988,13 +1030,19 @@
988
1030
  Peer-level messages, carried inside transport Data payloads.
989
1031
 
990
1032
  Handshake (plaintext):
991
- Hello [0x01][ver=3][token:8][configHash:4][keyExchange:1][suites:1][pubLen:1][pub…][cookieLen:1][cookie…]
1033
+ Hello [0x01][ver=4][token:8][configHash:4][keyExchange:1][suites:1][appId:8][appVersion:2][features:4]
1034
+ [pubLen:1][pub…][cookieLen:1][cookie…][extLen:2][extensions…]
992
1035
  — client introduces itself on every link; the token groups the links into one
993
1036
  connection, configHash covers the channel table and MaxMessageSize, suites
994
- is the bitmask of cipher suites the client can run.
995
- Welcome [0x02][connectionId:8][suite:1][pubLen:1][pub…][idLen:1][identityKey…][sigLen:1][signature…]
996
- — server bound the link; ECDH public key, and when the server has an identity
997
- its public key plus a signature over the handshake transcript.
1037
+ is the bitmask of cipher suites the client can run, pub its ephemeral
1038
+ X25519 key (keyed modes).
1039
+ Welcome [0x02][connectionId:8][suite:1][features:4][pubLen:1][pub…][idLen:1][identityKey…][extLen:2][extensions…]
1040
+ — server bound the link; its ephemeral X25519 key, the features both sides
1041
+ support, and its long-term public key when it has an identity.
1042
+
1043
+ Growing without a new version: features is a bitmask (the server answers with the
1044
+ bits both sides know), extensions a block of [type:1][length:2][value] entries.
1045
+ A receiver ignores feature bits and extension types it does not know.
998
1046
  Reject [0x03][reason:1] — handshake refused (version/encryption/config/auth).
999
1047
  Retry [0x06][cookie:16] — UDP-only servers: prove your address, resend Hello with this cookie.
1000
1048
 
@@ -1024,13 +1072,20 @@
1024
1072
  <member name="F:NetSync.Peers.PeerProtocol.RejectAuthenticationFailed">
1025
1073
  <summary>The server can't verify the client's envelopes: the keys differ (wrong PSK).</summary>
1026
1074
  </member>
1075
+ <member name="F:NetSync.Peers.PeerProtocol.RejectApplicationMismatch">
1076
+ <summary>The client belongs to another application or application protocol version.</summary>
1077
+ </member>
1078
+ <member name="F:NetSync.Peers.PeerProtocol.LocalFeatures">
1079
+ <summary>Feature bits this build understands (none are defined yet).</summary>
1080
+ </member>
1027
1081
  <member name="M:NetSync.Peers.PeerProtocol.TryReadHelloVersion(System.ReadOnlySpan{System.Byte},System.Byte@)">
1028
1082
  <summary>Reads just the version (to reject old peers clearly before parsing the rest).</summary>
1029
1083
  </member>
1030
- <member name="M:NetSync.Peers.PeerProtocol.IdentityTranscript(System.Int64,System.UInt32,System.Byte,System.Byte,NetSync.CipherSuite,System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte})">
1084
+ <member name="M:NetSync.Peers.PeerProtocol.ExtensionsWellFormed(System.ReadOnlySpan{System.Byte},System.Int32)">
1031
1085
  <summary>
1032
- What the server's identity signs: everything that shapes the session keys, so a
1033
- man-in-the-middle can neither swap the ECDH keys nor downgrade the cipher suite.
1086
+ The extension block [length:2][entries…] must fit the message; its entries
1087
+ ([type:1][length:2][value]) are skipped — none are defined yet, and unknown ones
1088
+ are ignored by design.
1034
1089
  </summary>
1035
1090
  </member>
1036
1091
  <member name="T:NetSync.Pipeline.Compression.Compressor">
@@ -1140,6 +1195,23 @@
1140
1195
  Not thread-safe; owned by the endpoint under its RTT lock.
1141
1196
  </summary>
1142
1197
  </member>
1198
+ <member name="F:NetSync.Pipeline.Reliability.RttEstimator.MaxBackoff">
1199
+ <summary>Largest factor a run of timeouts multiplies the retransmission timeout by.</summary>
1200
+ </member>
1201
+ <member name="M:NetSync.Pipeline.Reliability.RttEstimator.OnTimeout(System.Int64,System.Int32)">
1202
+ <summary>
1203
+ A retransmission timer fired (RFC 6298, 5.5): the timeout stays doubled for every
1204
+ packet — not just the one that timed out — until an acknowledgement brings a new
1205
+ valid sample. Without this, a link whose acknowledgements are merely slow (a busy
1206
+ receiver, a congested queue) keeps timing out at the old short timeout, and every
1207
+ spurious retransmission adds to the load that delays the acknowledgements: a storm.
1208
+ Retransmitted packets give no samples (Karn), so only this backoff lets the timeout grow.
1209
+ Doubles at most once per timeout period, like TCP's single timer: packets sent a little
1210
+ apart expire on consecutive scans, and that is one timeout, not several.
1211
+ </summary>
1212
+ <param name="nowMs">Current time.</param>
1213
+ <param name="timeoutMs">The (backed-off) retransmission timeout that just expired.</param>
1214
+ </member>
1143
1215
  <member name="P:NetSync.Pipeline.Reliability.RttEstimator.BaseRtt">
1144
1216
  <summary>Minimum RTT over the last 30–60 s (route changes age out).</summary>
1145
1217
  </member>
@@ -1235,7 +1307,7 @@
1235
1307
  WindowSize ahead of this, otherwise the receiver's dedup ring (also
1236
1308
  WindowSize) could not distinguish new packets from ancient ones.</summary>
1237
1309
  </member>
1238
- <member name="M:NetSync.Pipeline.Reliability.ReliableEndpoint.#ctor(System.Collections.Generic.Dictionary{System.Byte,NetSync.ChannelConfig},System.Func{System.ReadOnlyMemory{System.Byte},System.Threading.Tasks.ValueTask},System.Action{System.Byte,System.Byte[]},System.Func{System.Int32},System.Action{NetSync.Transports.DisconnectReason},NetSync.Diagnostics.INetLogger,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Boolean)">
1310
+ <member name="M:NetSync.Pipeline.Reliability.ReliableEndpoint.#ctor(System.Collections.Generic.Dictionary{System.Byte,NetSync.ChannelConfig},System.Func{System.ReadOnlyMemory{System.Byte},System.Threading.Tasks.ValueTask},System.Action{System.Byte,System.Byte[]},System.Func{System.Int32},System.Action{NetSync.Transports.DisconnectReason},NetSync.Diagnostics.INetLogger,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Boolean,System.Int32)">
1239
1311
  <summary>Convenience overload: each delivered payload is copied into its own array.</summary>
1240
1312
  </member>
1241
1313
  <member name="P:NetSync.Pipeline.Reliability.ReliableEndpoint.DeferAcks">
@@ -1353,13 +1425,7 @@
1353
1425
  <summary>Largest number of bytes <see cref="M:NetSync.Pipeline.Security.ConnectionCrypto.Encrypt(System.ReadOnlySpan{System.Byte},System.Span{System.Byte})"/> adds to a plaintext.</summary>
1354
1426
  </member>
1355
1427
  <member name="M:NetSync.Pipeline.Security.ConnectionCrypto.FromSecret(System.Byte[],NetSync.CipherSuite,System.Boolean)">
1356
- <summary>Derives every per-direction key from a session secret.</summary>
1357
- </member>
1358
- <member name="M:NetSync.Pipeline.Security.ConnectionCrypto.FromPresharedKey(System.Byte[],System.Int64,NetSync.CipherSuite,System.Boolean)">
1359
- <summary>
1360
- PSK mode: session secret = HMAC(psk, label ‖ sessionToken). The token is
1361
- public, the PSK is not — an eavesdropper cannot derive the session keys.
1362
- </summary>
1428
+ <summary>Derives every per-direction key from a session secret (see <see cref="T:NetSync.Pipeline.Security.HandshakeKeys"/>).</summary>
1363
1429
  </member>
1364
1430
  <member name="M:NetSync.Pipeline.Security.ConnectionCrypto.CreateLinkSecurity(NetSync.TransportType)">
1365
1431
  <summary>Packet authenticator for one link of this connection.</summary>
@@ -1377,22 +1443,41 @@
1377
1443
  its tag.
1378
1444
  </summary>
1379
1445
  </member>
1380
- <member name="T:NetSync.Pipeline.Security.EcdhKeyExchange">
1446
+ <member name="T:NetSync.Pipeline.Security.HandshakeKeys">
1447
+ <summary>
1448
+ Session keys of protocol v4. Every keyed connection runs an ephemeral X25519 exchange,
1449
+ so both sides contribute fresh randomness to every session; what authenticates it is
1450
+ mixed into the same derivation:
1451
+ - PresharedKey: the shared key — only holders of it arrive at the same session keys;
1452
+ - a server identity: a second exchange between the client's ephemeral key and the
1453
+ server's long-term key — only the holder of that private key arrives at them.
1454
+
1455
+ secret = HKDF-SHA256(salt = SHA-256(transcript), ikm = ee ‖ [es] ‖ [psk], info = "NetSync/4 session")
1456
+
1457
+ The transcript covers every negotiated value, so none of them can be altered in
1458
+ transit without the two sides ending up with different keys.
1459
+ </summary>
1460
+ </member>
1461
+ <member name="M:NetSync.Pipeline.Security.HandshakeKeys.Transcript(System.Int64,System.UInt32,System.Byte,System.Byte,System.UInt64,System.UInt16,System.UInt32,System.ReadOnlySpan{System.Byte},NetSync.CipherSuite,System.UInt32,System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte})">
1462
+ <summary>Everything both sides agreed on, in one canonical byte string.</summary>
1463
+ </member>
1464
+ <member name="M:NetSync.Pipeline.Security.HandshakeKeys.SessionSecret(System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte})">
1381
1465
  <summary>
1382
- Ephemeral ECDH (NIST P-256) helpers. Public keys travel as raw 64-byte X‖Y
1383
- points — no ASN.1, works on both target frameworks.
1384
- The exchange is unauthenticated: it defeats passive eavesdropping, not an
1385
- active MITM (documented in <see cref="F:NetSync.KeyExchangeMode.Ecdh"/>).
1466
+ The session secret. <paramref name="identityShared"/> and <paramref name="presharedKey"/>
1467
+ are empty when the connection doesn't use them.
1386
1468
  </summary>
1387
1469
  </member>
1388
- <member name="P:NetSync.Pipeline.Security.EcdhKeyExchange.IsSupported">
1470
+ <member name="T:NetSync.Pipeline.Security.Hkdf">
1389
1471
  <summary>
1390
- Whether this runtime can actually do P-256 ECDH. Some Mono/IL2CPP builds ship
1391
- the type but throw at use; probe a full key agreement once.
1472
+ HKDF with HMAC-SHA256 (RFC 5869). The class library has one only on newer targets;
1473
+ this is the same function everywhere.
1392
1474
  </summary>
1393
1475
  </member>
1394
- <member name="M:NetSync.Pipeline.Security.EcdhKeyExchange.DeriveSessionSecret(System.Security.Cryptography.ECDiffieHellman,System.ReadOnlySpan{System.Byte},System.Int64)">
1395
- <summary>Derives the session secret from our keypair, their public key and the session token.</summary>
1476
+ <member name="M:NetSync.Pipeline.Security.Hkdf.Extract(System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte})">
1477
+ <summary>Extract: a pseudorandom key from input key material and a salt (empty salt = zeros).</summary>
1478
+ </member>
1479
+ <member name="M:NetSync.Pipeline.Security.Hkdf.Expand(System.Byte[],System.ReadOnlySpan{System.Byte},System.Int32)">
1480
+ <summary>Expand: <paramref name="length"/> bytes of output keyed by a pseudorandom key, bound to <paramref name="info"/>.</summary>
1396
1481
  </member>
1397
1482
  <member name="T:NetSync.Pipeline.Security.LinkSecurity">
1398
1483
  <summary>
@@ -1445,6 +1530,40 @@
1445
1530
  <member name="M:NetSync.Pipeline.Security.LinkSecurity.ComputeTag(System.Boolean,System.Byte[],System.Int32,System.Int32,System.Span{System.Byte})">
1446
1531
  <summary>Tag over slot ‖ counter ‖ inner of the envelope at buffer[offset..offset+count).</summary>
1447
1532
  </member>
1533
+ <member name="T:NetSync.Pipeline.Security.X25519">
1534
+ <summary>
1535
+ X25519 Diffie-Hellman (RFC 7748) in portable managed code: the same key exchange on
1536
+ every runtime, including the ones whose class library has no elliptic curves (Unity).
1537
+
1538
+ Field elements are 16 limbs of 16 bits in 64-bit integers (the TweetNaCl layout):
1539
+ compact, and every operation runs in constant time — no branch or array index
1540
+ depends on secret data.
1541
+ </summary>
1542
+ </member>
1543
+ <member name="M:NetSync.Pipeline.Security.X25519.GeneratePrivateKey(System.Span{System.Byte})">
1544
+ <summary>Fills <paramref name="privateKey"/> with a new random private key.</summary>
1545
+ </member>
1546
+ <member name="M:NetSync.Pipeline.Security.X25519.PublicKey(System.ReadOnlySpan{System.Byte},System.Span{System.Byte})">
1547
+ <summary>The public key for a private key: scalar multiplication of the base point (u = 9).</summary>
1548
+ </member>
1549
+ <member name="M:NetSync.Pipeline.Security.X25519.TrySharedSecret(System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.Span{System.Byte})">
1550
+ <summary>
1551
+ The shared secret of our private key and their public key. False when the result is
1552
+ all zero (their key is a low-order point): such a secret must not be used.
1553
+ </summary>
1554
+ </member>
1555
+ <member name="M:NetSync.Pipeline.Security.X25519.ScalarMultiply(System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.Span{System.Byte})">
1556
+ <summary>RFC 7748 X25519(k, u): the scalar is clamped, the top bit of u is ignored.</summary>
1557
+ </member>
1558
+ <member name="M:NetSync.Pipeline.Security.X25519.Swap(System.Span{System.Int64},System.Span{System.Int64},System.Int64)">
1559
+ <summary>Swaps p and q when bit is 1, in constant time.</summary>
1560
+ </member>
1561
+ <member name="M:NetSync.Pipeline.Security.X25519.Multiply(System.Span{System.Int64},System.ReadOnlySpan{System.Int64},System.ReadOnlySpan{System.Int64})">
1562
+ <summary>o = a·b; o may be the same span as a or b.</summary>
1563
+ </member>
1564
+ <member name="M:NetSync.Pipeline.Security.X25519.Invert(System.Span{System.Int64},System.ReadOnlySpan{System.Int64})">
1565
+ <summary>o = 1/i (i^(p-2)).</summary>
1566
+ </member>
1448
1567
  <member name="T:NetSync.ReliabilityMode">
1449
1568
  <summary>
1450
1569
  Delivery guarantees for a channel. Only meaningful on UDP: TCP channels are
@@ -1532,21 +1651,23 @@
1532
1651
  </member>
1533
1652
  <member name="T:NetSync.NetIdentity">
1534
1653
  <summary>
1535
- A server's long-term identity: an ECDSA P-256 key pair. The server signs every
1536
- ECDH handshake with it; clients that pin the public key
1654
+ A server's long-term identity: an X25519 key pair. Every handshake mixes an exchange
1655
+ with this key into the session keys, so only the holder of the private key can
1656
+ complete it; clients that pin the public key
1537
1657
  (<see cref="P:NetSync.EncryptionConfig.TrustedServerKeys"/>) refuse anyone else — this is
1538
1658
  what makes <see cref="F:NetSync.KeyExchangeMode.Ecdh"/> safe against an active
1539
1659
  man-in-the-middle, the way a pinned certificate does for TLS.
1540
1660
 
1541
1661
  Generate once, store the private key (<see cref="M:NetSync.NetIdentity.ExportPrivateKey"/>) like any
1542
1662
  secret, ship the public key (or its <see cref="P:NetSync.NetIdentity.Fingerprint"/>) with your clients.
1663
+ Works on every runtime: the implementation is part of the library.
1543
1664
  </summary>
1544
1665
  </member>
1545
1666
  <member name="F:NetSync.NetIdentity.PublicKeySize">
1546
- <summary>Raw public key: X ‖ Y, 32 bytes each.</summary>
1667
+ <summary>Size of <see cref="P:NetSync.NetIdentity.PublicKey"/>.</summary>
1547
1668
  </member>
1548
1669
  <member name="F:NetSync.NetIdentity.PrivateKeySize">
1549
- <summary>Exported private key: D ‖ X ‖ Y.</summary>
1670
+ <summary>Size of the exported private key.</summary>
1550
1671
  </member>
1551
1672
  <member name="P:NetSync.NetIdentity.PublicKey">
1552
1673
  <summary>The public key clients pin.</summary>
@@ -1555,10 +1676,7 @@
1555
1676
  <summary>Short human-readable form of <see cref="P:NetSync.NetIdentity.PublicKey"/> (for logs and UIs).</summary>
1556
1677
  </member>
1557
1678
  <member name="P:NetSync.NetIdentity.IsSupported">
1558
- <summary>
1559
- Whether this runtime can sign and verify with ECDSA P-256 (some Mono/IL2CPP builds
1560
- can't). Clients without it can't pin a server identity.
1561
- </summary>
1679
+ <summary>Always true: identities no longer depend on what the runtime's class library offers.</summary>
1562
1680
  </member>
1563
1681
  <member name="M:NetSync.NetIdentity.Generate">
1564
1682
  <summary>Creates a new random identity.</summary>
@@ -1567,11 +1685,14 @@
1567
1685
  <summary>Restores an identity from <see cref="M:NetSync.NetIdentity.ExportPrivateKey"/> output.</summary>
1568
1686
  </member>
1569
1687
  <member name="M:NetSync.NetIdentity.ExportPrivateKey">
1570
- <summary>The private key (D ‖ X ‖ Y). Treat it like a password.</summary>
1688
+ <summary>The private key. Treat it like a password.</summary>
1571
1689
  </member>
1572
1690
  <member name="M:NetSync.NetIdentity.GetFingerprint(System.Byte[])">
1573
1691
  <summary>"SHA256:" + the first 16 bytes of SHA-256(public key), hex.</summary>
1574
1692
  </member>
1693
+ <member name="M:NetSync.NetIdentity.TrySharedSecret(System.ReadOnlySpan{System.Byte},System.Span{System.Byte})">
1694
+ <summary>The exchange between this identity and a client's ephemeral key; false for an unusable key.</summary>
1695
+ </member>
1575
1696
  <member name="T:NetSync.Relay.IDatagramSocket">
1576
1697
  <summary>
1577
1698
  The UDP socket of a relay transport, as an interface: hole punching depends on how
@@ -1590,6 +1711,9 @@
1590
1711
  <member name="M:NetSync.Relay.DatagramSocket.ReceiveFrom(System.Byte[],System.Net.IPEndPoint@)">
1591
1712
  <summary>Single reader (the transport's receive thread).</summary>
1592
1713
  </member>
1714
+ <member name="M:NetSync.Relay.DatagramSocket.Dispose">
1715
+ <summary>Closes the socket, waking a receive blocked in it (the reader must already be cancelled).</summary>
1716
+ </member>
1593
1717
  <member name="T:NetSync.Relay.FramedConnection">
1594
1718
  <summary>
1595
1719
  A TCP connection carrying relay frames ([kind][length][body]) in both directions:
@@ -1622,7 +1746,14 @@
1622
1746
  <summary>A write stuck this long means the remote stopped reading.</summary>
1623
1747
  </member>
1624
1748
  <member name="M:NetSync.Relay.FramedConnection.DisposeAfterFlushAsync(System.Int32)">
1625
- <summary>Writes what is already queued (bounded wait), then closes.</summary>
1749
+ <summary>
1750
+ Closes without losing what is already queued: writes it (bounded wait), ends our
1751
+ side of the stream, and gives the remote the rest of the time to read it and close.
1752
+
1753
+ Closing the socket right after the last write is not enough: the bytes may still sit
1754
+ in the kernel's send buffer, and a close with a read pending discards them on some
1755
+ platforms (the connection is reset instead of finished).
1756
+ </summary>
1626
1757
  </member>
1627
1758
  <member name="T:NetSync.Relay.NetRelayServer">
1628
1759
  <summary>
@@ -1643,6 +1774,19 @@
1643
1774
  <member name="P:NetSync.Relay.NetRelayServer.MaxRooms">
1644
1775
  <summary>Most rooms at once.</summary>
1645
1776
  </member>
1777
+ <member name="P:NetSync.Relay.NetRelayServer.AccessKey">
1778
+ <summary>
1779
+ When set, only hosts that present this key (<see cref="P:NetSync.Relay.RelayRoom.AccessKey"/>) may open
1780
+ rooms: the relay serves your application instead of anyone who finds it. Clients
1781
+ don't need it — they need a room code. Null or empty = open to every host.
1782
+ </summary>
1783
+ </member>
1784
+ <member name="P:NetSync.Relay.NetRelayServer.CloseFlushTimeoutMs">
1785
+ <summary>
1786
+ How long a client closed by its host still gets what is already queued for it
1787
+ (the host's last messages, such as a kick notice) before the relay drops the link.
1788
+ </summary>
1789
+ </member>
1646
1790
  <member name="P:NetSync.Relay.NetRelayServer.MaxClientsPerRoom">
1647
1791
  <summary>Most clients per room (stream and datagram sides counted separately).</summary>
1648
1792
  </member>
@@ -1737,9 +1881,11 @@
1737
1881
  exchange configured they are authenticated envelopes it can't read or forge.
1738
1882
 
1739
1883
  TCP frames: [kind:1][bodyLength:4 BE][body]
1740
- HostHello 0x01 [roomLen:1][room] host claims a room
1884
+ HostHello 0x01 [hello] host claims a room
1741
1885
  HostWelcome 0x02 [secret:16] room is yours; the secret authorizes your UDP side
1742
- ClientHello 0x03 [roomLen:1][room] client joins a room's stream side
1886
+ ClientHello 0x03 [hello] client joins a room's stream side
1887
+ hello = [version:1][features:4][roomLen:1][room][keyLen:1][accessKey]; bytes after it are
1888
+ ignored, so later versions can append fields. A relay refuses a version it doesn't speak.
1743
1889
  ClientWelcome 0x04 []
1744
1890
  Refused 0x05 [reason utf8]
1745
1891
  Data 0x10 [message] client ⇄ relay
@@ -1749,9 +1895,9 @@
1749
1895
  Keepalive 0x14 []
1750
1896
 
1751
1897
  UDP datagrams: [kind:1][...]
1752
- HostRegister 0x80 [roomLen][room][secret:16] host → relay (repeated: keeps NAT mappings)
1898
+ HostRegister 0x80 [version:1][roomLen][room][secret:16] host → relay (repeated: keeps NAT mappings)
1753
1899
  HostRegistered 0x81 []
1754
- ClientRegister 0x82 [roomLen][room][nonce:8] client → relay
1900
+ ClientRegister 0x82 [version:1][roomLen][room][nonce:8] client → relay
1755
1901
  ClientRegistered 0x83 [clientId:4][hostEndpoint] relay → client (endpoint empty: no direct path)
1756
1902
  Introduce 0x84 [clientId:4][nonce:8][endpoint] relay → host: punch towards this client
1757
1903
  RelayData 0x85 client→relay [clientId:4][nonce:8][message]; relay→host [clientId:4][message];
@@ -1762,6 +1908,21 @@
1762
1908
  Endpoint: [family:1 (4|6)][address 4|16][port:2 BE]; family 0 = none.
1763
1909
  </summary>
1764
1910
  </member>
1911
+ <member name="F:NetSync.Relay.RelayProtocol.Version">
1912
+ <summary>Version of the relay protocol itself: a relay outlives the applications that use it.</summary>
1913
+ </member>
1914
+ <member name="F:NetSync.Relay.RelayProtocol.LocalFeatures">
1915
+ <summary>Feature bits this build understands (none are defined yet).</summary>
1916
+ </member>
1917
+ <member name="F:NetSync.Relay.RelayProtocol.MaxHelloBytes">
1918
+ <summary>Largest hello body a relay reads.</summary>
1919
+ </member>
1920
+ <member name="M:NetSync.Relay.RelayProtocol.EncodeHello(System.String,System.String)">
1921
+ <summary>The body of HostHello / ClientHello.</summary>
1922
+ </member>
1923
+ <member name="M:NetSync.Relay.RelayProtocol.TryReadHello(System.ReadOnlySpan{System.Byte},System.Byte@,System.String@,System.Byte[]@)">
1924
+ <summary>Reads a hello body; the version is returned even when the rest can't be understood.</summary>
1925
+ </member>
1765
1926
  <member name="F:NetSync.Relay.RelayProtocol.MaxFrameBody">
1766
1927
  <summary>Largest frame body: a full NetSync message plus the client id.</summary>
1767
1928
  </member>
@@ -1810,6 +1971,9 @@
1810
1971
  <member name="P:NetSync.Relay.RelayRoom.AllowDirect">
1811
1972
  <summary>Try a direct (hole-punched) UDP path; false = always through the relay.</summary>
1812
1973
  </member>
1974
+ <member name="P:NetSync.Relay.RelayRoom.AccessKey">
1975
+ <summary>Hosts only: the key of a relay that restricts who may open rooms (<see cref="P:NetSync.Relay.NetRelayServer.AccessKey"/>).</summary>
1976
+ </member>
1813
1977
  <member name="P:NetSync.Relay.RelayRoom.Tcp">
1814
1978
  <summary>Stream slot (<see cref="F:NetSync.TransportType.Tcp"/>) through the relay.</summary>
1815
1979
  </member>
@@ -1875,6 +2039,15 @@
1875
2039
  socket writes ignore cancellation.
1876
2040
  </summary>
1877
2041
  </member>
2042
+ <member name="T:NetSync.Sending.SendQueue.BatchBuffers">
2043
+ <summary>
2044
+ Coalescing buffers, shared by all queues. Not the shared array pool: that one keeps an
2045
+ array per thread, and a drain loop rents on one thread-pool thread and returns on
2046
+ another, so batches get stranded in thread caches and the pool allocates new 64 KB
2047
+ arrays now and then — the more often, the slower the machine. Any thread can take
2048
+ what any other returned here. Used once per batched write, so the lock is cheap.
2049
+ </summary>
2050
+ </member>
1878
2051
  <member name="P:NetSync.Sending.SendQueue.WriteStartedAtMs">
1879
2052
  <summary>Monotonic start time of the write in progress, 0 when idle.</summary>
1880
2053
  </member>
@@ -1903,6 +2076,13 @@
1903
2076
  (cancelled or queue shut down) the caller still owns it.
1904
2077
  </summary>
1905
2078
  </member>
2079
+ <member name="M:NetSync.Sending.SendQueue.EnqueueOrWaitAsync(System.Byte[],System.Int32,NetSync.Sending.SendPriority,System.Threading.CancellationToken)">
2080
+ <summary>
2081
+ Queues a pooled buffer, waiting for room when the queue is full: a sender that awaits
2082
+ its sends is slowed down to the pace of the connection instead of failing. The queue
2083
+ owns the buffer in every outcome (it goes back to the pool if this throws).
2084
+ </summary>
2085
+ </member>
1906
2086
  <member name="M:NetSync.Sending.SendQueue.TryTakeWrite(NetSync.Sending.SendQueue.Job@)">
1907
2087
  <summary>
1908
2088
  Takes the next write: the highest-priority job, plus — when coalescing — the
@@ -2064,6 +2244,13 @@
2064
2244
  <member name="F:NetSync.Transports.DisconnectReason.Kicked">
2065
2245
  <summary>The server deliberately disconnected this client (NetConnection.DisconnectAsync). No auto-reconnect.</summary>
2066
2246
  </member>
2247
+ <member name="F:NetSync.Transports.DisconnectReason.Overloaded">
2248
+ <summary>
2249
+ Polled delivery only: the event queue was full (<c>NetConfig.MaxPendingEvents</c>) when a
2250
+ message of a reliable channel arrived. Dropping it would break the channel's
2251
+ guarantee, so the connection is closed instead. Call PollEvents() more often.
2252
+ </summary>
2253
+ </member>
2067
2254
  <member name="T:NetSync.Transports.DualStack">
2068
2255
  <summary>
2069
2256
  Server sockets that accept IPv4 and IPv6 clients on one port (dual-stack), with
@@ -2181,7 +2368,7 @@
2181
2368
  </summary>
2182
2369
  </member>
2183
2370
  <member name="M:NetSync.Transports.MessageLink.CheckHealth(NetSync.Transports.TransportSettings,System.Boolean)">
2184
- <summary>Liveness check for a keepalive loop: null = fine, otherwise why the link is dead.</summary>
2371
+ <summary>Liveness check, once per keepalive round: null = fine, otherwise why the link is dead.</summary>
2185
2372
  </member>
2186
2373
  <member name="T:NetSync.Transports.PacketProtocol">
2187
2374
  <summary>
@@ -2250,6 +2437,24 @@
2250
2437
  buffer makes sure it will fit.
2251
2438
  </summary>
2252
2439
  </member>
2440
+ <member name="T:NetSync.Transports.SilenceTracker">
2441
+ <summary>
2442
+ Decides when a link has been silent long enough to call it dead.
2443
+
2444
+ Silence is counted in keepalive rounds this process actually ran, not only in elapsed
2445
+ time: while our own process is paused (a busy machine, a starved thread pool, a laptop
2446
+ waking up) we send no pings, so the peer can't answer them — the silence is ours, not
2447
+ the peer's. A link is dead when enough rounds in a row heard nothing
2448
+ (PingTimeoutMs / PingIntervalMs of them) and the timeout has also passed.
2449
+ Owned by one keepalive loop; not thread-safe.
2450
+ </summary>
2451
+ </member>
2452
+ <member name="M:NetSync.Transports.SilenceTracker.IsDead(System.Int64,System.Int64,NetSync.Transports.TransportSettings)">
2453
+ <summary>One keepalive round, after its ping went out. True = the peer is gone.</summary>
2454
+ <param name="lastHeardMs">When the peer was last heard from (pong or any packet, per caller).</param>
2455
+ <param name="nowMs">Current time.</param>
2456
+ <param name="settings">Ping interval and timeout.</param>
2457
+ </member>
2253
2458
  <member name="T:NetSync.Transports.Simulation.NetworkSimulation">
2254
2459
  <summary>
2255
2460
  A bad network, on demand — for development and testing only. Set
@@ -2301,11 +2506,21 @@
2301
2506
  <member name="M:NetSync.Transports.Simulation.Impairment.Apply(System.Action)">
2302
2507
  <summary>Schedules <paramref name="deliver"/> per the simulation (0, 1 or 2 times).</summary>
2303
2508
  </member>
2304
- <member name="T:NetSync.Transports.Simulation.SimulationClock">
2305
- <summary>
2306
- One background thread delivering delayed packets on time. Waits coarsely and spins
2307
- the last stretch: OS timers (15.6 ms on Windows) would distort small latencies.
2308
- </summary>
2509
+ <member name="T:NetSync.Transports.Simulation.SimulationLane">
2510
+ <summary>
2511
+ Delivers the delayed packets of one direction of one link, in due order, on its own
2512
+ thread — like the receive loop of a real link. One lane can't hold up another: a slow
2513
+ handler on one connection delays only that connection, as on a real network.
2514
+
2515
+ The thread sleeps until the next packet is due rather than spinning, so the simulator
2516
+ costs no CPU of its own. Sleeps last a whole timer tick, 15.6 ms by default on Windows,
2517
+ so while a lane runs there it asks for 1 ms ticks (affects this process only, since
2518
+ Windows 10 2004). The thread ends after a few idle seconds and starts again with the
2519
+ next packet.
2520
+ </summary>
2521
+ </member>
2522
+ <member name="T:NetSync.Transports.Simulation.TimerResolution">
2523
+ <summary>1 ms OS timer ticks while held (Windows; elsewhere sleeps are already that precise).</summary>
2309
2524
  </member>
2310
2525
  <member name="T:NetSync.Transports.Tcp.TcpFrameReader">
2311
2526
  <summary>
@@ -2469,6 +2684,9 @@
2469
2684
  <member name="P:NetSync.Transports.TransportPeer.PingMs">
2470
2685
  <summary>Last measured round-trip time in milliseconds, -1 when unknown.</summary>
2471
2686
  </member>
2687
+ <member name="F:NetSync.Transports.TransportPeer.Silence">
2688
+ <summary>Keepalive bookkeeping of the transport's ping loop (that loop only).</summary>
2689
+ </member>
2472
2690
  <member name="P:NetSync.Transports.TransportPeer.TransportState">
2473
2691
  <summary>Transport-specific state (e.g. the TCP socket and its send queue).</summary>
2474
2692
  </member>
@@ -2583,6 +2801,13 @@
2583
2801
  Batch type). Stops at the first malformed entry, or after <paramref name="maxPackets"/>.
2584
2802
  </summary>
2585
2803
  </member>
2804
+ <member name="M:NetSync.Transports.Udp.DatagramBatcher.WaitForSendingRound">
2805
+ <summary>
2806
+ Batches the drain loop already took are still being sent: the owner closes the socket
2807
+ right after Dispose, so wait for them (a Bye among them would be lost otherwise —
2808
+ more often the slower the machine). Datagram sends don't block, so this is short.
2809
+ </summary>
2810
+ </member>
2586
2811
  <member name="M:NetSync.Transports.Udp.DatagramBatcher.Dispose">
2587
2812
  <summary>Stops the drain loop; what is still queued is sent on the calling thread first.</summary>
2588
2813
  </member>
@@ -2601,6 +2826,12 @@
2601
2826
  <member name="F:NetSync.Transports.Udp.PathMtuProbe.Candidates">
2602
2827
  <summary>UDP payload sizes tried, largest first: Ethernet, PPPoE/tunnels, VPNs.</summary>
2603
2828
  </member>
2829
+ <member name="P:NetSync.Transports.Udp.PathMtuProbe.IsSupported">
2830
+ <summary>
2831
+ Whether this OS lets a UDP socket forbid fragmentation. Without that a probe proves
2832
+ nothing, so there is no probing (macOS: the runtime doesn't support the option).
2833
+ </summary>
2834
+ </member>
2604
2835
  <member name="M:NetSync.Transports.Udp.PathMtuProbe.ProbeAsync(System.Net.IPEndPoint,System.Int32,System.Threading.CancellationToken)">
2605
2836
  <summary>The largest confirmed datagram size, or 0 when nothing could be confirmed.</summary>
2606
2837
  </member>
@@ -2665,6 +2896,14 @@
2665
2896
  <member name="M:NetSync.Transports.Udp.UdpSockets.BindServer(System.Int32)">
2666
2897
  <summary>Dual-stack (IPv6 + IPv4) server socket where possible, IPv4-only otherwise.</summary>
2667
2898
  </member>
2899
+ <member name="M:NetSync.Transports.Udp.UdpSockets.RefuseIfHeldOverIpv4(System.Int32)">
2900
+ <summary>
2901
+ Windows and macOS let a dual-stack socket bind a port an IPv4 socket already holds, and
2902
+ the IPv4 socket then gets the IPv4 traffic: the server would hear nothing. Binding an
2903
+ IPv4 socket to the port first turns that into an ordinary "port in use" everywhere.
2904
+ (Windows also gets exclusive binding below; this covers the other platforms.)
2905
+ </summary>
2906
+ </member>
2668
2907
  <member name="M:NetSync.Transports.Udp.UdpSockets.RequireExclusivePort(System.Net.Sockets.Socket)">
2669
2908
  <summary>
2670
2909
  Windows lets an IPv4 socket and a dual-stack socket share a port number and delivers
@@ -2672,6 +2911,18 @@
2672
2911
  Exclusive binding turns that into an ordinary "port in use". Elsewhere it already is one.
2673
2912
  </summary>
2674
2913
  </member>
2914
+ <member name="M:NetSync.Transports.Udp.UdpSockets.Close(System.Net.Sockets.Socket)">
2915
+ <summary>
2916
+ Closes a socket whose receive loop may be blocked in it, waking that loop first (the
2917
+ loop must already be cancelled). Closing alone isn't enough everywhere: on macOS a
2918
+ UDP socket that isn't connected doesn't wake a thread blocked in it, and the close
2919
+ waits for that call — a stop would hang until the next datagram arrived. So a
2920
+ connected socket is shut down, and any other one gets an empty datagram from itself;
2921
+ the loops skip empty datagrams and then see the cancellation.
2922
+ (A receive timeout isn't an option: a socket whose receive timed out is in an
2923
+ undefined state on Windows, and can lose a datagram arriving just then elsewhere.)
2924
+ </summary>
2925
+ </member>
2675
2926
  <member name="M:NetSync.Transports.Udp.UdpSockets.DisableIcmpConnectionReset(System.Net.Sockets.Socket)">
2676
2927
  <summary>
2677
2928
  Windows reports an ICMP "port unreachable" for an earlier datagram as an error on
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "com.netsync.core",
3
- "version": "2.0.0-rc.4",
3
+ "version": "2.0.0-rc.5",
4
4
  "displayName": "NetSync Core",
5
5
  "description": "Zero-dependency networking core: TCP and UDP channels over one connection, reliable UDP, authentication and encryption, relay with hole punching, time sync, LAN discovery.",
6
6
  "unity": "2021.2",