HTTPCLIENT-2396 - add Server-Sent Events client to HttpClient5.

httpclient5-sse/pom.xml

@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+   ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+   ====================================================================
+
+   This software consists of voluntary contributions made by many
+   individuals on behalf of the Apache Software Foundation.  For more
+   information on the Apache Software Foundation, please see
+   <http://www.apache.org />.
+ --><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.apache.httpcomponents.client5</groupId>
+    <artifactId>httpclient5-parent</artifactId>
+    <version>5.6-alpha2-SNAPSHOT</version>
+  </parent>
+  <artifactId>httpclient5-sse</artifactId>
+  <name>Apache HttpClient sse</name>
+  <inceptionYear>2011</inceptionYear>
+  <description>Apache HttpComponents Client Server-Sent</description>
+  <packaging>jar</packaging>
+
+  <properties>
+    <Automatic-Module-Name>org.apache.httpcomponents.client5.httpclient5.sse</Automatic-Module-Name>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.httpcomponents.client5</groupId>
+      <artifactId>httpclient5</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.httpcomponents.client5</groupId>
+      <artifactId>httpclient5</artifactId>
+      <scope>test</scope>
+      <classifier>tests</classifier>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-slf4j-impl</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.hamcrest</groupId>
+      <artifactId>hamcrest</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <reporting>
+    <plugins>
+      <plugin>
+        <artifactId>maven-project-info-reports-plugin</artifactId>
+        <inherited>false</inherited>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>index</report>
+              <report>dependencies</report>
+              <report>dependency-info</report>
+              <report>summary</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <version>0.21.2</version>
+        <configuration>
+          <skip>true</skip>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+
+</project>

httpclient5-sse/src/main/java/org/apache/hc/client5/http/sse/BackoffStrategy.java

@@ -0,0 +1,57 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.client5.http.sse;
+
+/**
+ * Computes the next reconnect delay for SSE (in milliseconds).
+ * <p>
+ * Implementations may also override {@link #shouldReconnect(int, long, Long)}
+ * to decline reconnects entirely (e.g., a "no strategy" that never reconnects).
+ */
+public interface BackoffStrategy {
+
+    /**
+     * @param attempt           consecutive reconnect attempt number (1-based)
+     * @param previousDelayMs   last delay used (0 for first attempt)
+     * @param serverRetryHintMs value from server 'retry:' (ms) or HTTP Retry-After, or null if none
+     * @return delay in milliseconds (>= 0)
+     */
+    long nextDelayMs(int attempt, long previousDelayMs, Long serverRetryHintMs);
+
+    /**
+     * Whether a reconnect should be attempted at all.
+     * Default is {@code true} for backward compatibility.
+     *
+     * @param attempt           consecutive reconnect attempt number (1-based)
+     * @param previousDelayMs   last delay used (0 for first attempt)
+     * @param serverRetryHintMs value from server 'retry:' (ms) or HTTP Retry-After, or null if none
+     * @return true to reconnect, false to stop
+     */
+    default boolean shouldReconnect(final int attempt, final long previousDelayMs, final Long serverRetryHintMs) {
+        return true;
+    }
+}

httpclient5-sse/src/main/java/org/apache/hc/client5/http/sse/EventSource.java

@@ -0,0 +1,134 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.client5.http.sse;
+
+import java.util.Map;
+
+import org.apache.hc.core5.annotation.Contract;
+
+/**
+ * Represents a Server-Sent Events (SSE) connection to a remote resource.
+ *
+ * <p>This interface exposes the minimal control surface for an SSE stream:
+ * starting, cancelling, header management, and basic state and offset (Last-Event-ID).
+ * Implementations are provided by this module (for example, via
+ * a factory such as {@code SseExecutor#open(...)}), which wires the
+ * {@link EventSourceListener} that receives events.</p>
+ *
+ * <h3>Thread-safety</h3>
+ * <p>Implementations should be safe for concurrent use: {@link #start()} and
+ * {@link #cancel()} are expected to be idempotent, and header methods should be
+ * safe to call at any time prior to (re)connect.</p>
+ *
+ * <h3>Last-Event-ID</h3>
+ * <p>{@code Last-Event-ID} follows the SSE spec: the most recent non-null event
+ * id is remembered by the implementation and can be sent on subsequent reconnects
+ * so the server can resume the stream.</p>
+ *
+ * @since 5.6
+ */
+@Contract
+public interface EventSource {
+
+    /**
+     * Begins streaming events.
+     * <ul>
+     *   <li>Idempotent: calling when already started is a no-op.</li>
+     *   <li>Non-blocking: returns immediately.</li>
+     *   <li>Reconnects: implementation-specific and driven by configuration.</li>
+     * </ul>
+     *
+     * @since 5.6
+     */
+    void start();
+
+    /**
+     * Cancels the stream and prevents further reconnects.
+     * <ul>
+     *   <li>Idempotent: safe to call multiple times.</li>
+     *   <li>Implementations should eventually invoke the listener’s
+     *       {@code onClosed()} exactly once.</li>
+     * </ul>
+     *
+     * @since 5.6
+     */
+    void cancel();
+
+    /**
+     * Returns the last seen event id or {@code null} if none has been observed.
+     *
+     * @return the last event id, or {@code null}
+     * @since 5.6
+     */
+    String lastEventId();
+
+    /**
+     * Sets the outbound {@code Last-Event-ID} that will be sent on the next connect
+     * or reconnect attempt. Passing {@code null} clears the value.
+     *
+     * @param id the id to send, or {@code null} to clear
+     * @since 5.6
+     */
+    void setLastEventId(String id);
+
+    /**
+     * Sets or replaces a request header for subsequent (re)connects.
+     * Header names are case-insensitive per RFC 7230/9110.
+     *
+     * @param name  header name (non-null)
+     * @param value header value (may be empty but not null)
+     * @since 5.6
+     */
+    void setHeader(String name, String value);
+
+    /**
+     * Removes a previously set request header for subsequent (re)connects.
+     *
+     * @param name header name to remove (non-null)
+     * @since 5.6
+     */
+    void removeHeader(String name);
+
+    /**
+     * Returns a snapshot of the currently configured headers that will be used
+     * for the next request. The returned map is a copy and may be modified
+     * by the caller without affecting the {@code EventSource}.
+     *
+     * @return copy of headers to be sent
+     * @since 5.6
+     */
+    Map<String, String> getHeaders();
+
+    /**
+     * Indicates whether the SSE connection is currently open.
+     * Implementations may report {@code false} during backoff between reconnects.
+     *
+     * @return {@code true} if the transport is open and events may be received
+     * @since 5.6
+     */
+    boolean isConnected();
+}