Upgraded to Netty 4

In addition, made the following changes to the way the handler works:

* Messages are buffered in a hash map by sequence ID if it's not the
  right time for the sequence.
* Removed subsequence ordering - writes for a given request are required
  to be sequential without the pipelining handler, so with it we can
  assume the same.
* Replaced buffer limit with back pressure - if the number of in flight
  requests exceeds a high water mark, the handler now exerts back
  pressure on the client by blocking read completed events, and unblocks
  them, and requests a new read, when a low watermark is reached.

Author: jroper

.gitignore

@@ -1,22 +1 @@
-# Extracted from https://github.com/ulrich/macaron-factory/blob/master/.gitignore
-# Ignore all dotfiles...
-.*
-# except for .gitignore
-!.gitignore
-
-# Ignore Play! working directory #
-db
-eclipse
-lib
-log
-logs
-modules
-precompiled
-project/project
-project/target
 target
-tmp
-test-result
-server.pid
-*.iml
-*.eml

.travis.yml

@@ -0,0 +1,8 @@
+language: java
+jdk:
+  - oraclejdk8
+  - openjdk7
+cache:
+  directories:
+    - $HOME/.m2
+

README.md

@@ -4,12 +4,7 @@ netty-http-pipelining
 This library adds http pipelining capability to Netty.
 
 Inserting the HttpPipeliningHandler into a pipeline will cause message events containing an HttpRequest to become transformed
-into OrderedUpstreamMessageEvents. The OrderedUpstreamMessageEvent retains context such that a handler further upstream can
-compose it and reply with an OrderedDownstreamChannelEvent in any order and in parallel. The HttpPipeliningHandler will
+into SequencedHttpRequest. The SequencedHttpRequest retains context such that a handler further upstream can
+compose it and reply with an SequencedOutboundMessage in any order and in parallel. The HttpPipeliningHandler will
 ensure that http replies are sent back in the order that the http pipelining specification requires i.e. the order in which
 replies are returned must correlate to the order in which requests are made.
-
-The chunking of http replies is handled. Limits are also available within the handler to cap the buffering of replies
-in order to avoid memory exhaustion.
-
-Please refer to the HttpPipeliningHandlerTest for a comprehensive illustration of usage.

pom.xml

@@ -41,8 +41,8 @@
     <dependencies>
         <dependency>
             <groupId>io.netty</groupId>
-            <artifactId>netty</artifactId>
-            <version>3.10.1.Final</version>
+            <artifactId>netty-codec-http</artifactId>
+            <version>4.0.29.Final</version>
         </dependency>
         <dependency>
             <groupId>junit</groupId>

src/main/java/com/typesafe/netty/http/pipelining/HttpPipeliningHandler.java

@@ -1,110 +1,233 @@
 package com.typesafe.netty.http.pipelining;
 
-import org.jboss.netty.channel.*;
-import org.jboss.netty.handler.codec.http.HttpRequest;
+
+import io.netty.channel.*;
+import io.netty.handler.codec.http.*;
+import io.netty.util.collection.IntObjectHashMap;
+import io.netty.util.collection.IntObjectMap;
 
 import java.util.*;
 
 /**
  * Implements HTTP pipelining ordering, ensuring that responses are completely served in the same order as their
- * corresponding requests. NOTE: A side effect of using this handler is that upstream HttpRequest objects will
- * cause the original message event to be effectively transformed into an OrderedUpstreamMessageEvent. Conversely
- * OrderedDownstreamChannelEvent objects are expected to be received for the correlating response objects.
+ * corresponding requests.
+ *
+ * Each incoming request is assigned a sequence number, which is provided in the wrapping {@link SequencedHttpRequest}.
+ * When a handler writes a response and a response body, it must wrap each of those messages in a
+ * {@link SequencedOutboundMessage} with the corresponding sequence from that request.  It must send at least one
+ * message in response to the request, and the last, and only the last message it sends must have the last flag set.
+ *
+ * If messages are sent after the last message is sent, these messages may end up being buffered until the sequence
+ * number overflows and cycles back. If messages for a given sequence number are not sent sequentially, similar
+ * behaviour could also occur.
+ *
+ * There is no limit to the amount of messages that this handler will buffer for a particular sequence number.  It is
+ * the responsibility of the handler sending the outbound messages to handle back pressure via promises associated
+ * with each write event - if this is done, the buffering will be inherently bounded by back pressure.
  *
- * @author Christopher Hunt
+ * This handler does however put a bound on the maximum number of in flight requests that it will handle, configured by
+ * inFlightRequestsLowWatermark and inFlightRequestsHighWatermark. When the high watermark is exceeded, the handler will
+ * push back on the client. When the low watermark is reached, the handler will start reading again.  This back pressure
+ * mechanism only works if ChannelOptions.AUTO_READ is false.
+ *
+ * This back pressure is implemented by blocking channelReadComplete events, so assumes that the following handlers
+ * will not request reading unless they receive this event.  Note that the handler does nothing to actually block
+ * incoming requests when the high watermark is reached, it only pushes back on the TCP connection.  If there are more
+ * requests in the TCP buffer before this back pressure takes effect, these requests will still be sent to the following
+ * handlers.
+ *
+ * If channelReadComplete is invoked while the high watermark is reached, then when the low watermark is reached, this
+ * will be fired again, to signal demand.
  */
-public class HttpPipeliningHandler extends SimpleChannelHandler {
+public class HttpPipeliningHandler extends ChannelDuplexHandler {
+
+    /**
+     * The sequence of received HTTP requests.
+     */
+    private int receiveSequence = 0;
+
+    /**
+     * The currently sending sequence of HTTP requests.
+     */
+    private int currentlySendingSequence = 1;
 
-    public static final int INITIAL_EVENTS_HELD = 3;
-    public static final int MAX_EVENTS_HELD = 10000;
+    /**
+     * Whether the high watermark has been exceeded.
+     */
+    private boolean highWatermarkReached = false;
+
+    /**
+     * If the high watermark has been exceeded, whether a channel read complete has occurred.
+     */
+    private boolean channelReadCompleteOccurred = false;
 
-    private final int maxEventsHeld;
+    /**
+     * A write message with a promise of when it's written.
+     */
+    private static class WriteMessage {
+        /**
+         * The written message.
+         */
+        final SequencedOutboundMessage message;
+
+        /**
+         * The future that is redeemed once the message is written.
+         */
+        final ChannelPromise promise;
+
+        public WriteMessage(SequencedOutboundMessage message, ChannelPromise promise) {
+            this.message = message;
+            this.promise = promise;
+        }
+    }
 
-    private int sequence;
-    private int nextRequiredSequence;
-    private int nextRequiredSubsequence;
+    /**
+     * The buffered events, by sequence
+     */
+    private final IntObjectMap<List<WriteMessage>> bufferedEvents = new IntObjectHashMap<>();
 
-    private final Queue<OrderedDownstreamChannelEvent> holdingQueue;
+    private final int inFlightRequestsLowWatermark;
+    private final int inFlightRequestsHighWatermark;
 
+    /**
+     * Create the pipelining handler with low and high watermarks of 2 and 4.
+     */
     public HttpPipeliningHandler() {
-        this(MAX_EVENTS_HELD);
+        this(2, 4);
     }
 
     /**
-     * @param maxEventsHeld the maximum number of channel events that will be retained prior to aborting the channel
-     *                      connection. This is required as events cannot queue up indefintely; we would run out of
-     *                      memory if this was the case.
+     * Create the pipelining handler.
+     *
+     * @param inFlightRequestsLowWatermark The low watermark for in flight requests, where, if the high watermark has
+     *                                     been exceeded, the handler will start reading again. Must be at least 0.
+     * @param inFlightRequestsHighWatermark The high watermark, once in flight requests has exceeded this, the handler
+     *                                      will stop reading, pushing back on the client.  Must be greater than the
+     *                                      low watermark.
      */
-    public HttpPipeliningHandler(final int maxEventsHeld) {
-        this.maxEventsHeld = maxEventsHeld;
-
-        holdingQueue = new PriorityQueue<OrderedDownstreamChannelEvent>(INITIAL_EVENTS_HELD, new Comparator<OrderedDownstreamChannelEvent>() {
-            @Override
-            public int compare(OrderedDownstreamChannelEvent o1, OrderedDownstreamChannelEvent o2) {
-                final int delta = o1.getOrderedUpstreamMessageEvent().getSequence() - o2.getOrderedUpstreamMessageEvent().getSequence();
-                if (delta == 0) {
-                    return o1.getSubsequence() - o2.getSubsequence();
-                } else {
-                    return delta;
-                }
-            }
-        });
+    public HttpPipeliningHandler(int inFlightRequestsLowWatermark, int inFlightRequestsHighWatermark) {
+        if (inFlightRequestsLowWatermark < 0) {
+            throw new IllegalArgumentException("inFlightRequestsLowWatermark must be an least 0, was " + inFlightRequestsLowWatermark);
+        }
+        if (inFlightRequestsHighWatermark <= inFlightRequestsLowWatermark) {
+            throw new IllegalArgumentException("inFlightRequestsHighWatermark must be greater than inFlightRequestsLowWatermark, but was " + inFlightRequestsHighWatermark);
+        }
+        this.inFlightRequestsLowWatermark = inFlightRequestsLowWatermark;
+        this.inFlightRequestsHighWatermark = inFlightRequestsHighWatermark;
     }
 
-    public int getMaxEventsHeld() {
-        return maxEventsHeld;
+    private int inFlight() {
+        return receiveSequence - currentlySendingSequence + 1;
     }
 
     @Override
-    public void messageReceived(final ChannelHandlerContext ctx, final MessageEvent e) {
-        final Object msg = e.getMessage();
-        if (msg instanceof HttpRequest) {
-            ctx.sendUpstream(new OrderedUpstreamMessageEvent(sequence++, e.getChannel(), msg, e.getRemoteAddress()));
+    public void channelReadComplete(ChannelHandlerContext ctx) throws Exception {
+        // Only forward read complete if we haven't exceeded the high watermark
+        if (!highWatermarkReached) {
+            ctx.fireChannelReadComplete();
         } else {
-            ctx.sendUpstream(e);
+            // Store the fact that read complete has been requested.
+            channelReadCompleteOccurred = true;
+        }
+    }
+
+    @Override
+    public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
+        Object toSend = msg;
+
+        // Wrap message in sequenced if it needs to be
+        if (msg instanceof HttpRequest) {
+            receiveSequence++;
+            HttpRequest request = (HttpRequest) msg;
+            toSend = new SequencedHttpRequest(receiveSequence, request);
+        }
+
+        // If we've reached the end of an http request, and we're at or over the high watermark,
+        // set it to reached.
+        if (msg instanceof LastHttpContent && inFlight() >= inFlightRequestsHighWatermark) {
+            highWatermarkReached = true;
         }
+
+        ctx.fireChannelRead(toSend);
     }
 
     @Override
-    public void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e)
-            throws Exception {
-        if (e instanceof OrderedDownstreamChannelEvent) {
-
-            boolean channelShouldClose = false;
-
-            synchronized (holdingQueue) {
-                if (holdingQueue.size() < maxEventsHeld) {
-
-                    final OrderedDownstreamChannelEvent currentEvent = (OrderedDownstreamChannelEvent) e;
-                    holdingQueue.add(currentEvent);
-
-                    while (!holdingQueue.isEmpty()) {
-                        final OrderedDownstreamChannelEvent nextEvent = holdingQueue.peek();
-                        if (nextEvent.getOrderedUpstreamMessageEvent().getSequence() != nextRequiredSequence |
-                                nextEvent.getSubsequence() != nextRequiredSubsequence) {
-                            break;
-                        }
-                        holdingQueue.remove();
-                        ctx.sendDownstream(nextEvent.getChannelEvent());
-                        if (nextEvent.isLast()) {
-                            ++nextRequiredSequence;
-                            nextRequiredSubsequence = 0;
-                        } else {
-                            ++nextRequiredSubsequence;
-                        }
-                    }
-
-                } else {
-                    channelShouldClose = true;
-                }
+    public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) throws Exception {
+        if (msg instanceof SequencedOutboundMessage) {
+            SequencedOutboundMessage sequenced = (SequencedOutboundMessage) msg;
+
+            writeInSequence(ctx, sequenced, promise);
+        } else {
+            ctx.write(msg, promise);
+        }
+    }
+
+    private void progressToNextSendingSequence(ChannelHandlerContext ctx) {
+        currentlySendingSequence++;
+
+        int inFlight = this.inFlight();
+        // If we're now at the low water mark, set it to false
+        if (highWatermarkReached && inFlight == inFlightRequestsLowWatermark) {
+            highWatermarkReached = false;
+
+            // Check if, while we were over the high watermark, a channel read had occurred
+            // that we blocked
+            if (channelReadCompleteOccurred) {
+                // Send it on
+                ctx.fireChannelReadComplete();
+                channelReadCompleteOccurred = false;
+            }
+        }
+    }
+
+    /**
+     * Write the next sequences, if buffered.
+     */
+    private void flushNextSequences(ChannelHandlerContext ctx) {
+        progressToNextSendingSequence(ctx);
+
+        List<WriteMessage> toFlush = bufferedEvents.get(currentlySendingSequence);
+
+        // Loop while we still have a sequence to flush
+        while (toFlush != null) {
+
+            bufferedEvents.remove(currentlySendingSequence);
+
+            WriteMessage lastWritten = null;
+
+            // Flush each event
+            for (WriteMessage message: toFlush) {
+                ctx.write(message.message.getMessage(), message.promise);
+                lastWritten = message;
             }
 
-            if (channelShouldClose) {
-                Channels.close(e.getChannel());
+            // If the last message that we wrote was the last message for that sequence,
+            // then increment the sequence and maybe get the next sequence from the buffer.
+            if (lastWritten != null && lastWritten.message.isLast()) {
+                progressToNextSendingSequence(ctx);
+                toFlush = bufferedEvents.get(currentlySendingSequence);
+            } else {
+                toFlush = null;
             }
-        } else {
-            super.handleDownstream(ctx, e);
         }
     }
 
+    /**
+     * Write the message in sequence.
+     */
+    private void writeInSequence(ChannelHandlerContext ctx, SequencedOutboundMessage sequenced, ChannelPromise promise) {
+        if (sequenced.getSequence() == currentlySendingSequence) {
+            ctx.write(sequenced.getMessage(), promise);
+            if (sequenced.isLast()) {
+                flushNextSequences(ctx);
+            }
+        } else {
+            List<WriteMessage> sequenceBuffer = bufferedEvents.get(sequenced.getSequence());
+            if (sequenceBuffer == null) {
+                sequenceBuffer = new ArrayList<>();
+                bufferedEvents.put(sequenced.getSequence(), sequenceBuffer);
+            }
+            sequenceBuffer.add(new WriteMessage(sequenced, promise));
+        }
+    }
 }