isapego commented on code in PR #7357:
URL: https://github.com/apache/ignite-3/pull/7357#discussion_r2669735887
##########
modules/client/DEVNOTES.md:
##########
@@ -0,0 +1,106 @@
+# Client Internals
+
+This document describes the internal architecture and design decisions of the
Apache Ignite 3 client.
+
+## Glossary
+
+- **Node** / **Server** / **Server Node**: A single cluster member (see
`IgniteImpl`)
+ - Multiple nodes can run in a single JVM
+- **Cluster**: A group of interconnected nodes
+- **Client** (formerly "Thin Client"): A single instance of `IgniteClient`
(see `TcpIgniteClient`)
+ - A client connects to one or more servers
+- **Channel** / **Connection**: A single TCP connection between a client and a
server (see `TcpClientChannel`)
+
+---
+
+## Connection Management
+
+### Overview
+
+Connection management involves three primary concerns:
+
+1. **Address Resolution**: Get server addresses
+2. **Connection Establishment**: Establish connections using resolved addresses
+3. **Connection Selection**: Choose an appropriate connection for each
operation
+
+These concerns are handled concurrently:
+
+- Background executor refreshes server addresses (periodically and/or on
specific events)
+- Background executor establishes new connections and maintains existing ones
(reconnects if necessary)
+- Operation threads select connections for operations
+
+### Connection Lifecycle
+
+#### Initial Connection
+
+When `IgniteClient.builder().addresses("foo:10800", "192.168.0.1").build()` is
called:
+
+1. **Build endpoint list** - For each provided address:
+ - Extract port if present, otherwise use default port
+ - Resolve DNS if necessary (a hostname can resolve to multiple IP addresses)
+
+2. **Establish first connection** - Iterate over endpoints and attempt to
connect to each one until successful
+
+Once the first connection is established, the client is fully functional and
the `IgniteClient` instance is returned to the user.
+
+#### Additional Connections
+
+Additional connections are established in the background after the initial
connection is made. This provides redundancy and load distribution.
+
+#### Connection Maintenance
+
+Each connection exchanges periodic heartbeats with the server:
+
+- If a heartbeat fails, the connection is considered broken and closed
+- A background task attempts to re-establish the connection
+
+#### Server Discovery
+
+New server addresses can be discovered through two mechanisms:
+
+1. The configured `IgniteClientConfiguration.addressesFinder`
+2. DNS resolution of provided addresses
+
+When new addresses are discovered:
Review Comment:
There should be some info on when we attempting discovery. Is it attempted
only once in the beginning? Is it periodic? What is the interval? Is it
configurable?
##########
modules/client/DEVNOTES.md:
##########
@@ -0,0 +1,106 @@
+# Client Internals
+
+This document describes the internal architecture and design decisions of the
Apache Ignite 3 client.
+
+## Glossary
+
+- **Node** / **Server** / **Server Node**: A single cluster member (see
`IgniteImpl`)
+ - Multiple nodes can run in a single JVM
+- **Cluster**: A group of interconnected nodes
+- **Client** (formerly "Thin Client"): A single instance of `IgniteClient`
(see `TcpIgniteClient`)
+ - A client connects to one or more servers
+- **Channel** / **Connection**: A single TCP connection between a client and a
server (see `TcpClientChannel`)
+
+---
+
+## Connection Management
+
+### Overview
+
+Connection management involves three primary concerns:
+
+1. **Address Resolution**: Get server addresses
+2. **Connection Establishment**: Establish connections using resolved addresses
+3. **Connection Selection**: Choose an appropriate connection for each
operation
+
+These concerns are handled concurrently:
+
+- Background executor refreshes server addresses (periodically and/or on
specific events)
+- Background executor establishes new connections and maintains existing ones
(reconnects if necessary)
+- Operation threads select connections for operations
+
+### Connection Lifecycle
+
+#### Initial Connection
+
+When `IgniteClient.builder().addresses("foo:10800", "192.168.0.1").build()` is
called:
+
+1. **Build endpoint list** - For each provided address:
+ - Extract port if present, otherwise use default port
+ - Resolve DNS if necessary (a hostname can resolve to multiple IP addresses)
Review Comment:
Should we clarify that all the resolved addresses are added to the endpoint
list?
##########
modules/client/DEVNOTES.md:
##########
@@ -0,0 +1,106 @@
+# Client Internals
+
+This document describes the internal architecture and design decisions of the
Apache Ignite 3 client.
+
+## Glossary
+
+- **Node** / **Server** / **Server Node**: A single cluster member (see
`IgniteImpl`)
+ - Multiple nodes can run in a single JVM
+- **Cluster**: A group of interconnected nodes
+- **Client** (formerly "Thin Client"): A single instance of `IgniteClient`
(see `TcpIgniteClient`)
+ - A client connects to one or more servers
+- **Channel** / **Connection**: A single TCP connection between a client and a
server (see `TcpClientChannel`)
+
+---
+
+## Connection Management
+
+### Overview
+
+Connection management involves three primary concerns:
+
+1. **Address Resolution**: Get server addresses
+2. **Connection Establishment**: Establish connections using resolved addresses
+3. **Connection Selection**: Choose an appropriate connection for each
operation
+
+These concerns are handled concurrently:
+
+- Background executor refreshes server addresses (periodically and/or on
specific events)
+- Background executor establishes new connections and maintains existing ones
(reconnects if necessary)
+- Operation threads select connections for operations
+
+### Connection Lifecycle
+
+#### Initial Connection
+
+When `IgniteClient.builder().addresses("foo:10800", "192.168.0.1").build()` is
called:
+
+1. **Build endpoint list** - For each provided address:
+ - Extract port if present, otherwise use default port
+ - Resolve DNS if necessary (a hostname can resolve to multiple IP addresses)
+
+2. **Establish first connection** - Iterate over endpoints and attempt to
connect to each one until successful
+
+Once the first connection is established, the client is fully functional and
the `IgniteClient` instance is returned to the user.
+
+#### Additional Connections
+
+Additional connections are established in the background after the initial
connection is made. This provides redundancy and load distribution.
Review Comment:
```suggestion
Additional connections are established in the background after the initial
connection is made. This provides robustness and load distribution.
```
##########
modules/client/DEVNOTES.md:
##########
@@ -0,0 +1,106 @@
+# Client Internals
+
+This document describes the internal architecture and design decisions of the
Apache Ignite 3 client.
+
+## Glossary
+
+- **Node** / **Server** / **Server Node**: A single cluster member (see
`IgniteImpl`)
+ - Multiple nodes can run in a single JVM
+- **Cluster**: A group of interconnected nodes
+- **Client** (formerly "Thin Client"): A single instance of `IgniteClient`
(see `TcpIgniteClient`)
+ - A client connects to one or more servers
+- **Channel** / **Connection**: A single TCP connection between a client and a
server (see `TcpClientChannel`)
+
+---
+
+## Connection Management
+
+### Overview
+
+Connection management involves three primary concerns:
+
+1. **Address Resolution**: Get server addresses
+2. **Connection Establishment**: Establish connections using resolved addresses
+3. **Connection Selection**: Choose an appropriate connection for each
operation
+
+These concerns are handled concurrently:
+
+- Background executor refreshes server addresses (periodically and/or on
specific events)
+- Background executor establishes new connections and maintains existing ones
(reconnects if necessary)
+- Operation threads select connections for operations
+
+### Connection Lifecycle
+
+#### Initial Connection
+
+When `IgniteClient.builder().addresses("foo:10800", "192.168.0.1").build()` is
called:
+
+1. **Build endpoint list** - For each provided address:
+ - Extract port if present, otherwise use default port
+ - Resolve DNS if necessary (a hostname can resolve to multiple IP addresses)
+
+2. **Establish first connection** - Iterate over endpoints and attempt to
connect to each one until successful
+
+Once the first connection is established, the client is fully functional and
the `IgniteClient` instance is returned to the user.
+
+#### Additional Connections
+
+Additional connections are established in the background after the initial
connection is made. This provides redundancy and load distribution.
+
+#### Connection Maintenance
+
+Each connection exchanges periodic heartbeats with the server:
+
+- If a heartbeat fails, the connection is considered broken and closed
+- A background task attempts to re-establish the connection
+
+#### Server Discovery
+
+New server addresses can be discovered through two mechanisms:
+
+1. The configured `IgniteClientConfiguration.addressesFinder`
+2. DNS resolution of provided addresses
+
+When new addresses are discovered:
+
+- They are added to the list of known server endpoints
+- New connections are established to these endpoints in the background
+
+### Connection Selection Strategy
+
+For each operation, the client selects a connection using the following
algorithm:
+
+1. **Check operation type**: Is it a single-key operation (e.g., `get`, `put`,
`remove`)?
+ - **Yes**:
+ - Use partition awareness logic to find the target node name
+ - If an active connection to that node exists, use it
+ - Otherwise, proceed to step 2
+ - **No**: Proceed to step 2
+
+2. **Round-robin selection**: Pick an active connection using round-robin
strategy
+
+3. **Fallback**: If no active connections exist, attempt to establish a new
connection to one of the known server endpoints
+
Review Comment:
What happens if we can not establish new connection? Is there a timeout? Is
RetryPolicy used in this case?
##########
modules/client/DEVNOTES.md:
##########
@@ -0,0 +1,106 @@
+# Client Internals
+
+This document describes the internal architecture and design decisions of the
Apache Ignite 3 client.
+
+## Glossary
+
+- **Node** / **Server** / **Server Node**: A single cluster member (see
`IgniteImpl`)
+ - Multiple nodes can run in a single JVM
+- **Cluster**: A group of interconnected nodes
+- **Client** (formerly "Thin Client"): A single instance of `IgniteClient`
(see `TcpIgniteClient`)
+ - A client connects to one or more servers
+- **Channel** / **Connection**: A single TCP connection between a client and a
server (see `TcpClientChannel`)
+
+---
+
+## Connection Management
+
+### Overview
+
+Connection management involves three primary concerns:
+
+1. **Address Resolution**: Get server addresses
+2. **Connection Establishment**: Establish connections using resolved addresses
+3. **Connection Selection**: Choose an appropriate connection for each
operation
+
+These concerns are handled concurrently:
+
+- Background executor refreshes server addresses (periodically and/or on
specific events)
+- Background executor establishes new connections and maintains existing ones
(reconnects if necessary)
+- Operation threads select connections for operations
+
+### Connection Lifecycle
+
+#### Initial Connection
+
+When `IgniteClient.builder().addresses("foo:10800", "192.168.0.1").build()` is
called:
+
+1. **Build endpoint list** - For each provided address:
+ - Extract port if present, otherwise use default port
+ - Resolve DNS if necessary (a hostname can resolve to multiple IP addresses)
+
+2. **Establish first connection** - Iterate over endpoints and attempt to
connect to each one until successful
+
+Once the first connection is established, the client is fully functional and
the `IgniteClient` instance is returned to the user.
+
+#### Additional Connections
+
+Additional connections are established in the background after the initial
connection is made. This provides redundancy and load distribution.
+
+#### Connection Maintenance
+
+Each connection exchanges periodic heartbeats with the server:
+
+- If a heartbeat fails, the connection is considered broken and closed
+- A background task attempts to re-establish the connection
Review Comment:
Minor: Not sure if "task" is a widely used term in Java.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
