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]