Address Discovery and Server Initiated Connection Migration and NAT Traversal

[masa-koz]

Description

This pull request introduces several new features and enhancements related to connection migration, address management, and NAT traversal in the QUIC implementation. It adds new transport parameters and connection events, expands the connection state and data structures to support multiple addresses, and updates documentation to reflect these changes. Some CI workflow and build configuration updates are also included.

Protocol and Feature Enhancements:

• Added new transport parameters for Observed Address, Server Migration, and NAT Traverse, along with their encoding logic in the handshake (src/core/crypto_tls.c, src/core/crypto.c). [1] [2] [3] [4]
• Introduced new connection state flags and fields to track negotiation and runtime state for Observed Address, Server Migration, and NAT Traverse features (src/core/connection.h). [1] [2] [3] [4]
• Expanded the QUIC_CONNECTION structure to manage lists of bound and candidate addresses, and defined associated structs (src/core/connection.h). [1] [2]
• Implemented logic to add the local address to the connection's bound addresses upon creation (src/core/binding.c).
• Added new functions to process ADD_ADDRESS and REMOVE_ADDRESS frames and to send punch probes (src/core/connection.h).

API and Documentation Updates:

• Documented new connection settings and parameters for server migration, address handling, and NAT traversal in docs/Settings.md. [1] [2]
• Added documentation for new connection events: NOTIFY_OBSERVED_ADDRESS, NOTIFY_REMOTE_ADDRESS_ADDED, PATH_VALIDATED, and NOTIFY_REMOTE_ADDRESS_REMOVED, including their data structures and preview status (docs/api/QUIC_CONNECTION_EVENT.md). [1] [2] [3]

Build and CI Configuration:

• Enabled the preview-api feature by default in Cargo.toml.
• Removed the macos-latest-xlarge runner from the GitHub Actions matrix in .github/workflows/cargo.yml.
• Added a step to set up the .NET 10 SDK in the test workflow for Linux and macOS in .github/workflows/test.yml.

Bug Fixes and Minor Improvements:

• Fixed a logic bug to prevent double-handling of handshake confirmation in QuicCryptoHandshakeConfirmed and reordered key discarding for correctness (src/core/crypto.c). [1] [2]

These changes lay the groundwork for advanced connection migration and NAT traversal features, improve address management, and enhance the QUIC protocol's flexibility and observability.

Testing

Added for Server Initiated Migration

Documentation

Added

In general, when an expression is used only for its side effects and its value is intentionally ignored, you should make that explicit, typically by casting the call to (void) or, alternatively, by assigning it to a dummy variable or checking it. This documents the intent and silences analyzers that otherwise flag the expression as “having no effect”.

Here, the simplest, lowest‑risk fix is to cast the CxPlatStorageReadValue calls to void. We keep the call exactly as is and just wrap it in (void), e.g.:

(void)CxPlatStorageReadValue(...);

This indicates that we are deliberately discarding the return value, while still relying on the function’s side effects on Value and ValueLen. To be consistent and avoid similar warnings at other locations, we should apply this change to all calls in this contiguous block (lines 1472, 1483, 1494, 1504, 1514), not just the one at 1494, since they are structurally identical and likely analyzed the same way. No new methods or imports are required; we only modify the function calls in src/core/settings.c within the shown snippet.

To fix this, the call to CxPlatStorageReadValue should be explicitly cast to void so that it is clear its return value is intentionally ignored. This does not alter program behavior but signals both to static analysis tools and human readers that the function call is kept only for its (potential) side effects, even if those are not visible to the analyzer.

Concretely, in src/core/settings.c, within QuicSettingsSetDefault, locate the block starting at line 1501 (if (!Settings->IsSet.AddAddressMode) {). In that block, change the plain expression statement

CxPlatStorageReadValue(
    Storage,
    QUIC_SETTING_ADD_ADDRESS_MODE,
    (uint8_t*)&Value,
    &ValueLen);

to be explicitly cast to void:

(void)CxPlatStorageReadValue(
    Storage,
    QUIC_SETTING_ADD_ADDRESS_MODE,
    (uint8_t*)&Value,
    &ValueLen);

This aligns with the guidance given in the background and does not require any new methods, imports, or definitions.

In general, when a function’s return value is intentionally ignored but the function is still called for its side effects (such as writing via pointer parameters), static analysis tools may flag “expression has no effect”. The standard, explicit way to indicate that the return value is intentionally unused is to cast the call to void, e.g. (void)func(...);. This both preserves behavior and documents intent.

For this file, the best fix without changing functionality is to modify the specific call on line 1514 from

CxPlatStorageReadValue(
    Storage,
    QUIC_SETTING_IGNORE_UNREACHABLE,
    (uint8_t*)&Value,
    &ValueLen);

to explicitly discard the return value:

(void)CxPlatStorageReadValue(
    Storage,
    QUIC_SETTING_IGNORE_UNREACHABLE,
    (uint8_t*)&Value,
    &ValueLen);

This is consistent with the rule’s recommendation and matches standard C practice for intentionally-unused return values. No new methods, imports, or definitions are required. The change should be limited to src/core/settings.c at the shown region; no other behavior in the function is altered.