init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/Connection.md

@@ -0,0 +1,121 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Connection/IConnection.cs
+generated_at: "2026-04-16T02:19:32.551940+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "a6aead5143a016b8"
+---
+
+# Connection
+
+## Documentation: `IConnection` Interface
+
+### 1. Purpose  
+The `IConnection` interface defines a standardized abstraction for network connection management within the DTS system, supporting both synchronous and asynchronous send/receive operations, connection lifecycle control (including soft disconnect/reconnect semantics), and socket-level configuration. It serves as the foundational contract for all connection implementations (e.g., TCP, UDP, custom transports), enabling decoupled communication logic across the system while preserving consistent behavior for connection state, data transfer, and error handling.
+
+### 2. Public Interface  
+
+- **`Task<int> SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)`**  
+  Asynchronously sends data from `sendBuffer`, starting at `bufferStartOffset`, for `bufferSizeToSend` bytes. Returns the number of bytes sent.
+
+- **`bool IsSoftDisconnected { get; }`**  
+  Indicates whether the connection is in a *soft disconnected* state—i.e., previously connected, then voluntarily disconnected with the expectation of reconnection.
+
+- **`void SoftDisconnect()`**  
+  Voluntarily disconnects the connection *without* fully closing underlying resources, preserving state for later reconnection.
+
+- **`void SoftConnect()`**  
+  Re-establishes a connection previously soft-disconnected, restoring communication capability.
+
+- **`System.Net.Sockets.SocketFlags Flags { get; set; }`**  
+  Gets or sets the socket flags used for send/receive operations (e.g., `DontRoute`, `OutOfBand`).
+
+- **`event EventHandler OnDisconnected`**  
+  Raised when the connection is fully disconnected (not soft-disconnected).
+
+- **`void KeepAliveErrorReceived()`**  
+  Explicitly signals that a keep-alive timeout/error occurred (e.g., no timely response received). Implementation likely triggers disconnection or retry logic.
+
+- **`string ConnectString { get; }`**  
+  Returns the connection string used to establish the connection (e.g., `"tcp://192.168.1.10:5000"`).
+
+- **`bool Connected { get; }`**  
+  Indicates whether the connection is currently active (i.e., not disconnected or soft-disconnected).
+
+- **`void Create(string connectString)`**  
+  Initializes the connection using the provided `connectString`.
+
+- **`void Create(string connectString, string hostIPAddress)`**  
+  Initializes the connection using `connectString` and an explicit `hostIPAddress` (likely for override or validation).
+
+- **`string GetConnectionData()`**  
+  Returns diagnostic or metadata information about the current connection state (e.g., remote endpoint, protocol details).
+
+- **`IAsyncResult BeginConnect(AsyncCallback callback, object callbackObject)`**  
+  Initiates an asynchronous connection attempt.
+
+- **`void EndConnect(IAsyncResult ar)`**  
+  Completes an asynchronous connection attempt.
+
+- **`IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback callback, object state)`**  
+  Initiates an asynchronous disconnection. If `reuseSocket` is `true`, the underlying socket may be reused.
+
+- **`void EndDisconnect(IAsyncResult asyncResult)`**  
+  Completes an asynchronous disconnection.
+
+- **`IAsyncResult BeginAccept(AsyncCallback callback, object state)`**  
+  Initiates an asynchronous accept operation (for server-side connections).
+
+- **`IConnection EndAccept(IAsyncResult asyncResult)`**  
+  Completes an asynchronous accept operation and returns a new `IConnection` representing the accepted client connection.
+
+- **`void Bind(int port)`**  
+  Binds the connection to a local port (typically used for server-side listening).
+
+- **`void Listen(int backlog)`**  
+  Begins listening for incoming connections with the specified `backlog` queue size.
+
+- **`IAsyncResult BeginSend(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend, AsyncCallback callback, object callbackObject)`**  
+  Initiates an asynchronous send operation.
+
+- **`int EndSend(IAsyncResult ar)`**  
+  Completes an asynchronous send operation and returns the number of bytes sent.
+
+- **`IAsyncResult BeginReceive(byte[] receiveBuffer, int bufferStartOffset, int maxSizeToReceive, AsyncCallback callback, object state)`**  
+  Initiates an asynchronous receive operation.
+
+- **`int EndReceive(IAsyncResult ar)`**  
+  Completes an asynchronous receive operation and returns the number of bytes received.
+
+> **Note**: Two methods—`GetCurrentUploadRate()` and `GetCurrentDownloadRate()`—are commented out and not part of the active interface.
+
+### 3. Invariants  
+- `Connected` must be `true` only when the underlying socket is actively connected (excluding soft-disconnected state).  
+- `IsSoftDisconnected` must be `true` only after `SoftDisconnect()` is called and before `SoftConnect()` is called.  
+- `OnDisconnected` must be raised only when the connection transitions to a *non-recoverable* (hard) disconnect state, not during soft disconnects.  
+- `SendAsync`, `BeginSend`, `EndSend`, `BeginReceive`, `EndReceive` must only be invoked when `Connected` is `true` (behavior on violation is undefined per interface—implementation-dependent).  
+- `SoftConnect()` must succeed only if `IsSoftDisconnected` is `true`.  
+- `Flags` must be applied consistently to all socket operations (send/receive/connect/accept).  
+- `KeepAliveErrorReceived()` must be called only when a keep-alive failure is detected (e.g., timeout without response).
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `System` (core types: `Task`, `EventHandler`, `IAsyncResult`, `AsyncCallback`, `object`)  
+  - `System.Threading.Tasks` (for `Task<int>`)  
+  - `System.Net.Sockets` (for `SocketFlags`)  
+- **Implemented by**: Concrete connection classes (e.g., `TcpConnection`, `UdpConnection`)—not visible in this file but implied by usage.  
+- **Used by**: Higher-level components requiring network communication (e.g., protocol handlers, device managers, session controllers).  
+- **No direct dependency on other DTS modules** is visible in this interface, though `ConnectString` format and `GetConnectionData()` output likely conform to internal conventions.
+
+### 5. Gotchas  
+- **Soft vs. Hard Disconnect**: `SoftDisconnect()` does *not* raise `OnDisconnected`; only full disconnections do. Confusing these can lead to incorrect state management.  
+- **`Connected` vs. `IsSoftDisconnected`**: `Connected` is `false` when `IsSoftDisconnected` is `true`. Code must check both states explicitly if distinguishing soft-disconnect is required.  
+- **`BeginAccept`/`EndAccept`**: Returns a *new* `IConnection` instance—consumers must manage its lifecycle (including disposal).  
+- **`reuseSocket` in `BeginDisconnect`**: If `true`, the socket may be reused; if `false`, it may be closed. Behavior depends on implementation.  
+- **No rate-limiting API**: The commented-out `GetCurrentUploadRate()`/`GetCurrentDownloadRate()` suggest rate monitoring was considered but not implemented—do not assume rate data is available.  
+- **`Create` overloads**: The two `Create` methods differ only by `hostIPAddress`; the purpose of the second parameter is unclear without implementation—likely for override or validation.  
+- **No timeout parameters**: All async operations lack explicit timeout configuration—timeouts are likely handled internally or via `KeepAliveErrorReceived()`.  
+- **No exception contract**: The interface does not specify exceptions (e.g., `ObjectDisposedException` after `SoftDisconnect`/`SoftConnect`), leaving error handling implementation-defined.  
+
+None identified beyond those above.