This is an automated email from the ASF dual-hosted git repository.

markt-asf pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/main by this push:
     new a9907f0894 Document Tribes transport architecture (#1134)
a9907f0894 is described below

commit a9907f0894a93bac29081683d94d7de78edc8b27
Author: sainadh777 <[email protected]>
AuthorDate: Tue Nov 17 07:48:32 2026 -0800

    Document Tribes transport architecture (#1134)
    
    * Document Tribes transport architecture
    
    
    Co-authored-by: Mark Thomas <[email protected]>
---
 TODO.md                           |  11 ++-
 webapps/docs/changelog.xml        |  10 +++
 webapps/docs/tribes/transport.xml | 148 +++++++++++++++++++++++++++++++++++++-
 3 files changed, 161 insertions(+), 8 deletions(-)

diff --git a/TODO.md b/TODO.md
index 32bd52f87f..6f2b19d344 100644
--- a/TODO.md
+++ b/TODO.md
@@ -806,18 +806,17 @@ These are bugs, correctness issues, or missing 
functionality that may affect pro
 
 ## Documentation TODOs
 
-### 75. Tribes Documentation (6 files)
+### 75. Tribes Documentation (5 files)
 
 | # | File:Line | Description | Fix Idea | Effort | Difficulty |
 |---|-----------|-------------|----------|--------|------------|
-| 75.1 | `docs/tribes/transport.xml:33` | Empty TODO placeholder | Write 
transport layer documentation: NIO vs BIO sender, UDP vs TCP, configuration 
options. | 2-3 days | Medium |
 | 75.3 | `docs/tribes/setup.xml:33` | Empty TODO placeholder | Write cluster 
setup guide: single-point vs multi-point, load balancer config, session 
replication. | 3-5 days | Medium |
 | 75.4 | `docs/tribes/membership.xml:33` | Empty TODO placeholder | Document 
membership service: multicast, static members, dynamic discovery. | 1-2 days | 
Medium |
 | 75.5 | `docs/tribes/interceptors.xml:33` | Empty TODO placeholder | Document 
all cluster interceptors: fault tolerance, flow control, message dispatch, etc. 
| 2-3 days | Medium |
 | 75.6 | `docs/tribes/faq.xml:33` | Empty TODO placeholder | Compile common 
clustering questions and answers from mailing lists and JIRA. | 2-3 days | 
Medium |
 | 75.7 | `docs/tribes/developers.xml:33` | Empty TODO placeholder | Developer 
guide for extending Tribes: custom channels, interceptors, senders. | 2-3 days 
| Medium |
 
-**Total estimated effort: 12-19 days, Medium difficulty**
+**Total estimated effort: 10-16 days, Medium difficulty**
 
 ---
 
@@ -1037,15 +1036,15 @@ These are IDE-generated stub methods with `// TODO 
Auto-generated method stub` c
 | High-Priority TODOs | ~25 | ~50-80 | Medium-High |
 | Medium-Priority TODOs | ~20 | ~25-40 | Medium |
 | Low-Priority / Cosmetic | ~15 | ~25-45 | Low-Medium |
-| Documentation | 11 | ~17-27 | Medium |
+| Documentation | 10 | ~15-24 | Medium |
 | Test Code | ~20 | ~15-25 | Low-Medium |
 | Auto-Generated Stubs | ~90 | ~5-8 | Low |
-| **Total** | **~196** | **~192-275** | **Mixed** |
+| **Total** | **~195** | **~190-272** | **Mixed** |
 
 ### Priority Recommendations
 
 1. **Immediate**: Fix DeltaManager session replication (items 1.1-1.7) - these 
affect cluster correctness
 2. **Short-term**: Fix DBCP double-close (6.1-6.2), BaseModelMBean 
notification removal (7.1), PersistentManagerBase LRU (5.1)
 3. **Medium-term**: SSL rewrite variables (2.1-2.8), HTTP/2 HPACK optimization 
(23.1-23.3), ThreadPoolExecutor AQS (13.1)
-4. **Long-term**: WebXml i18n support (30.1), CGIServlet overhaul (63.1), 
Tribes documentation (75.1-75.7)
+4. **Long-term**: WebXml i18n support (30.1), CGIServlet overhaul (63.1), 
Tribes documentation (75.3-75.7)
 5. **Backlog**: Auto-generated stubs, cosmetic items, test improvements
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index b4c0fabbb5..af6ecf4819 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -376,6 +376,16 @@
       </fix>
     </changelog>
   </subsection>
+  <subsection name="Cluster">
+    <changelog>
+      <!-- Entries for backport and removal before 12.0.0-M1 below this line 
-->
+      <docs>
+        Expand the Tribes transport documentation to describe the current NIO
+        sender and receiver pipeline, TCP and UDP selection, delivery options,
+        configuration and security considerations. (sainadh777)
+      </docs>
+    </changelog>
+  </subsection>
   <subsection name="WebSocket">
     <changelog>
       <update>
diff --git a/webapps/docs/tribes/transport.xml 
b/webapps/docs/tribes/transport.xml
index 3b036714b6..4fae41735e 100644
--- a/webapps/docs/tribes/transport.xml
+++ b/webapps/docs/tribes/transport.xml
@@ -28,9 +28,153 @@
 
 <body>
 
+<section name="Table of Contents">
+<toc/>
+</section>
+
+<section name="Overview">
+  <p>
+    The Tribes transport moves application and replication messages between
+    known cluster members. Membership discovery is a separate part of the
+    channel. It supplies the address and ports that the transport uses for each
+    destination.
+  </p>
+  <p>
+    Sending and receiving are deliberately separate. The sender opens
+    connections on demand for outbound messages, while the receiver owns the
+    listening sockets and the worker pool for inbound messages. The current
+    implementations use Java non-blocking I/O (NIO).
+  </p>
+</section>
+
+<section name="Sending messages">
+  <p>
+    The default channel sender is <code>ReplicationTransmitter</code>. It
+    delegates network delivery to <code>PooledParallelSender</code>, which uses
+    a pool of <code>ParallelNioSender</code> instances. A message addressed to
+    multiple members can therefore be written to those members in parallel,
+    and independent messages do not have to share one connection.
+  </p>
+  <p>
+    Each NIO sender manages the socket for a destination and applies the
+    configured connection timeout, retry, buffer and keep-alive settings.
+    Connections may be reused until a <code>keepAliveCount</code> or
+    <code>keepAliveTime</code> limit closes them.
+  </p>
+</section>
+
+<section name="Receiving messages">
+  <p>
+    <code>NioReceiver</code> accepts incoming connections and uses a selector
+    to detect sockets that are ready for reading. Completed messages are passed
+    to a pool of <code>NioReplicationTask</code> workers. The workers decode 
the
+    Tribes message, return any requested acknowledgement and pass the message
+    up through the channel interceptor stack.
+  </p>
+  <p>
+    This design lets a small receiver thread pool service many connections.
+    The pool size should be tuned for the number of members, message rate,
+    message processing cost and available CPU rather than simply set as high as
+    possible.
+  </p>
+</section>
+
+<section name="TCP and UDP">
+  <p>
+    TCP is the default transport for data messages. A message sent with
+    <code>Channel.SEND_OPTIONS_UDP</code> uses UDP instead. UDP delivery
+    requires a <code>udpPort</code> on the receiver so that each member can
+    advertise a destination UDP port.
+  </p>
+  <p>
+    TCP is appropriate for the normal replication path and for messages that
+    may exceed a single datagram. UDP avoids establishing a TCP connection, but
+    applications must account for datagram size limits, loss and reordering.
+    Transport selection is made per message, so a channel can carry both TCP
+    and UDP traffic.
+  </p>
+</section>
+
+<section name="Delivery options">
+  <p>
+    Send options are bit flags and may be combined for each message:
+  </p>
+  <ul>
+    <li>
+      With no acknowledgement option, completion means the message was written
+      to the transport.
+    </li>
+    <li>
+      <code>SEND_OPTIONS_USE_ACK</code> waits for the destination to confirm
+      receipt. This is the default option.
+    </li>
+    <li>
+      <code>SEND_OPTIONS_SYNCHRONIZED_ACK</code>, when combined with
+      <code>SEND_OPTIONS_USE_ACK</code>, waits until the destination has also
+      processed the message.
+    </li>
+    <li>
+      <code>SEND_OPTIONS_ASYNCHRONOUS</code> hands delivery to the
+      <code>MessageDispatchInterceptor</code> queue when that interceptor is in
+      the channel stack.
+    </li>
+  </ul>
+  <p>
+    Acknowledgements detect a delivery or processing failure and report it to
+    the sender. They do not provide transaction semantics across multiple
+    destinations.
+  </p>
+</section>
+
+<section name="Configuration">
+  <subsection name="Sender">
+    <p>
+      Configure the sender's nested <code>Transport</code> element to control
+      its connection pool, timeouts, retry count, socket buffers and keep-alive
+      policy. See the
+      <a href="../config/cluster-sender.html">Cluster Sender reference</a> for
+      the complete attribute list and defaults.
+    </p>
+  </subsection>
+
+  <subsection name="Receiver">
+    <p>
+      The receiver configuration defines its bind address, TCP port, optional
+      UDP port, automatic port range, worker limits and socket buffers. See the
+      <a href="../config/cluster-receiver.html">Cluster Receiver reference</a>
+      for the complete attribute list and defaults.
+    </p>
+  </subsection>
+
+  <subsection name="Tuning">
+    <p>
+      Start with the defaults and measure under representative traffic. If
+      senders wait for a pooled connection, review <code>poolSize</code> and
+      <code>maxWait</code>. If receiving work queues behind available sockets,
+      review the receiver's thread limits and the time spent by channel
+      listeners. Increasing buffers or thread counts without measuring can add
+      memory use and scheduling overhead without increasing throughput.
+    </p>
+  </subsection>
+</section>
 
-<section name="Transport">
-    <p>TODO</p>
+<section name="Network and security">
+  <p>
+    Every member must advertise an address and port reachable by the other
+    members. Firewalls and network policy must allow the receiver's TCP port
+    and, when used, its UDP port. Membership traffic and data transport traffic
+    use separate sockets and may require separate network rules.
+  </p>
+  <p>
+    Cluster traffic should use a trusted network. If a trusted network is not
+    available, configure the channel to use TLS with static membership and a
+    secure receiver port. TLS protects confidentiality and integrity, but not
+    availability. See the
+    <a href="../config/cluster.html#Security">Cluster security reference</a>
+    and the
+    <a href="https://tomcat.apache.org/security-model.html";>Tomcat security
+    model</a> when designing the cluster network.
+  </p>
 </section>
 </body>
 


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to