feat: Implement consumer handler in the Simulator

common/src/main/java/com/hedera/block/common/utils/Preconditions.java

@@ -27,11 +27,11 @@ public final class Preconditions { // @todo(381) change the APIs to accept non-n
      * we return it, else we throw {@link IllegalArgumentException}.
      *
      * @param toCheck a {@link String} to be checked if is blank as defined
-     * above
+     *                above
      * @return the {@link String} to be checked if it is not blank as defined
-     * above
+     *         above
      * @throws IllegalArgumentException if the input {@link String} to be
-     * checked is blank
+     *                                  checked is blank
      */
     public static String requireNotBlank(final String toCheck) {
         return requireNotBlank(toCheck, null);
@@ -43,14 +43,15 @@ public static String requireNotBlank(final String toCheck) {
      * {@link String#isBlank()}. If the given {@link String} is not blank, then
      * we return it, else we throw {@link IllegalArgumentException}.
      *
-     * @param toCheck a {@link String} to be checked if is blank as defined
-     * above
+     * @param toCheck      a {@link String} to be checked if is blank as defined
+     *                     above
      * @param errorMessage the error message to be used in the exception if the
-     * input {@link String} to be checked is blank, if null, a default message
+     *                     input {@link String} to be checked is blank, if null, a
+     *                     default message
      * @return the {@link String} to be checked if it is not blank as defined
-     * above
+     *         above
      * @throws IllegalArgumentException if the input {@link String} to be
-     * checked is blank
+     *                                  checked is blank
      */
     public static String requireNotBlank(final String toCheck, final String errorMessage) {
         if (StringUtilities.isBlank(toCheck)) {
@@ -69,7 +70,7 @@ public static String requireNotBlank(final String toCheck, final String errorMes
      * @param toCheck the number to check if it is a positive power of two
      * @return the number to check if it is positive
      * @throws IllegalArgumentException if the input number to check is not
-     * positive
+     *                                  positive
      */
     public static int requirePositive(final int toCheck) {
         return requirePositive(toCheck, null);
@@ -79,13 +80,14 @@ public static int requirePositive(final int toCheck) {
      * This method asserts a given integer is a positive. An integer is positive
      * if it is NOT equal to zero and is greater than zero.
      *
-     * @param toCheck the integer to check if it is a positive power of two
+     * @param toCheck      the integer to check if it is a positive power of two
      * @param errorMessage the error message to be used in the exception if the
-     * input integer to check is not positive, if null, a default message will
-     * be used
+     *                     input integer to check is not positive, if null, a
+     *                     default message will
+     *                     be used
      * @return the number to check if it is positive
      * @throws IllegalArgumentException if the input number to check is not
-     * positive
+     *                                  positive
      */
     public static int requirePositive(final int toCheck, final String errorMessage) {
         if (0 >= toCheck) {
@@ -105,7 +107,7 @@ public static int requirePositive(final int toCheck, final String errorMessage)
      * @param toCheck the long to check if it is a positive power of two
      * @return the long to check if it is positive
      * @throws IllegalArgumentException if the input long to check is not
-     * positive
+     *                                  positive
      */
     public static long requirePositive(final long toCheck) {
         return requirePositive(toCheck, null);
@@ -115,13 +117,14 @@ public static long requirePositive(final long toCheck) {
      * This method asserts a given long is a positive. A long is positive
      * if it is NOT equal to zero and is greater than zero.
      *
-     * @param toCheck the long to check if it is a positive power of two
+     * @param toCheck      the long to check if it is a positive power of two
      * @param errorMessage the error message to be used in the exception if the
-     * input long to check is not positive, if null, a default message will
-     * be used
+     *                     input long to check is not positive, if null, a default
+     *                     message will
+     *                     be used
      * @return the long to check if it is positive
      * @throws IllegalArgumentException if the input long to check is not
-     * positive
+     *                                  positive
      */
     public static long requirePositive(final long toCheck, final String errorMessage) {
         if (0L >= toCheck) {
@@ -134,14 +137,62 @@ public static long requirePositive(final long toCheck, final String errorMessage
         }
     }
 
+    /**
+     * Ensures that a given long value is greater than or equal to a specified base
+     * value.
+     * If the value does not meet the requirement, an
+     * {@link IllegalArgumentException} is thrown.
+     *
+     * <p>
+     * This method delegates the validation to
+     * {@link #requireGreaterOrEqual(long, long, String)},
+     * using a default error message if the check fails.
+     * </p>
+     *
+     * @param toTest the long value to test
+     * @param base   the base value to compare against
+     * @return the input {@code toTest} if it is greater than or equal to
+     *         {@code base}
+     * @throws IllegalArgumentException if {@code toTest} is less than {@code base}
+     */
+    public static long requireGreaterOrEqual(final long toTest, final long base) {
+        return requireGreaterOrEqual(toTest, base, null);
+    }
+
+    /**
+     * Ensures that a given long value is greater than or equal to a specified base
+     * value.
+     * If the value does not meet the requirement, an
+     * {@link IllegalArgumentException} is thrown.
+     *
+     * @param toTest       the long value to test
+     * @param base         the base value to compare against
+     * @param errorMessage the error message to include in the exception if the
+     *                     check fails;
+     *                     if {@code null}, a default message is used
+     * @return the input {@code toTest} if it is greater than or equal to
+     *         {@code base}
+     * @throws IllegalArgumentException if {@code toTest} is less than {@code base}
+     */
+    public static long requireGreaterOrEqual(final long toTest, final long base, final String errorMessage) {
+        if (toTest >= base) {
+            return toTest;
+        }
+
+        final String message = Objects.isNull(errorMessage)
+                ? "The input integer [%d] is required be greater or equal than [%d].".formatted(toTest, base)
+                : errorMessage;
+        throw new IllegalArgumentException(message);
+    }
+
     /**
      * This method asserts a given long is a whole number. A long is whole
      * if it is greater or equal to zero.
      *
      * @param toCheck the long to check if it is a whole number
      * @return the number to check if it is whole number
      * @throws IllegalArgumentException if the input number to check is not
-     * positive
+     *                                  positive
      */
     public static long requireWhole(final long toCheck) {
         return requireWhole(toCheck, null);
@@ -151,13 +202,14 @@ public static long requireWhole(final long toCheck) {
      * This method asserts a given long is a whole number. A long is whole
      * if it is greater or equal to zero.
      *
-     * @param toCheck the long to check if it is a whole number
+     * @param toCheck      the long to check if it is a whole number
      * @param errorMessage the error message to be used in the exception if the
-     * input long to check is not a whole number, if null, a default message will
-     * be used
+     *                     input long to check is not a whole number, if null, a
+     *                     default message will
+     *                     be used
      * @return the number to check if it is whole number
      * @throws IllegalArgumentException if the input number to check is not
-     * positive
+     *                                  positive
      */
     public static long requireWhole(final long toCheck, final String errorMessage) {
         if (toCheck >= 0) {
@@ -176,7 +228,7 @@ public static long requireWhole(final long toCheck, final String errorMessage) {
      * @param toCheck the number to check if it is a power of two
      * @return the number to check if it is a power of two
      * @throws IllegalArgumentException if the input number to check is not a
-     * power of two
+     *                                  power of two
      */
     public static int requirePowerOfTwo(final int toCheck) {
         return requirePowerOfTwo(toCheck, null);
@@ -185,13 +237,14 @@ public static int requirePowerOfTwo(final int toCheck) {
     /**
      * This method asserts a given integer is a power of two.
      *
-     * @param toCheck the number to check if it is a power of two
+     * @param toCheck      the number to check if it is a power of two
      * @param errorMessage the error message to be used in the exception if the
-     * input integer to check is not a power of two, if null, a default message
-     * will be used
+     *                     input integer to check is not a power of two, if null, a
+     *                     default message
+     *                     will be used
      * @return the number to check if it is a power of two
      * @throws IllegalArgumentException if the input number to check is not a
-     * power of two
+     *                                  power of two
      */
     public static int requirePowerOfTwo(final int toCheck, final String errorMessage) {
         if (!MathUtilities.isPowerOfTwo(toCheck)) {

common/src/test/java/com/hedera/block/common/CommonsTestUtility.java

@@ -207,6 +207,26 @@ public static Stream<Arguments> negativeIntegers() {
                 Arguments.of(-10_000_000));
     }
 
+    /**
+     * Provides valid test data for cases where the value to test is greater than or equal to the base value.
+     *
+     * @return a stream of arguments where each argument is a pair of {@code (toTest, base)} values,
+     *         such that {@code toTest >= base}.
+     */
+    public static Stream<Arguments> validGreaterOrEqualValues() {
+        return Stream.of(Arguments.of(10L, 5L), Arguments.of(5L, 5L), Arguments.of(0L, -5L), Arguments.of(100L, 50L));
+    }
+
+    /**
+     * Provides invalid test data for cases where the value to test is less than the base value.
+     *
+     * @return a stream of arguments where each argument is a pair of {@code (toTest, base)} values,
+     *         such that {@code toTest < base}.
+     */
+    public static Stream<Arguments> invalidGreaterOrEqualValues() {
+        return Stream.of(Arguments.of(3L, 5L), Arguments.of(-10L, -5L), Arguments.of(0L, 1L), Arguments.of(-1L, 0L));
+    }
+
     /**
      * Zero and some negative integers.
      */

common/src/test/java/com/hedera/block/common/utils/PreconditionsTest.java

@@ -106,6 +106,44 @@ void testRequireWholeFail(final int toTest) {
                 .withMessage(testErrorMessage);
     }
 
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requireGreaterOrEqual(long, long)} will return the input
+     * 'toTest' parameter if the check passes.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#validGreaterOrEqualValues")
+    void testRequireGreaterOrEqualPass(final long toTest, final long base) {
+        final Consumer<Long> asserts =
+                actual -> assertThat(actual).isGreaterThanOrEqualTo(base).isEqualTo(toTest);
+
+        final long actual = Preconditions.requireGreaterOrEqual(toTest, base);
+        assertThat(actual).satisfies(asserts);
+
+        final long actualOverload = Preconditions.requireGreaterOrEqual(toTest, base, "test error message");
+        assertThat(actualOverload).satisfies(asserts);
+    }
+
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requireGreaterOrEqual(long, long)} will throw an
+     * {@link IllegalArgumentException} if the check fails.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#invalidGreaterOrEqualValues")
+    void testRequireGreaterOrEqualFail(final long toTest, final long base) {
+        assertThatIllegalArgumentException().isThrownBy(() -> Preconditions.requireGreaterOrEqual(toTest, base));
+
+        final String testErrorMessage = "test error message";
+        assertThatIllegalArgumentException()
+                .isThrownBy(() -> Preconditions.requireGreaterOrEqual(toTest, base, testErrorMessage))
+                .withMessage(testErrorMessage);
+    }
+
     /**
      * This test aims to verify that the
      * {@link Preconditions#requirePositive(int)} will return the input 'toTest'

simulator/src/main/java/com/hedera/block/simulator/grpc/PublishStreamGrpcClient.java

@@ -68,6 +68,8 @@ public interface PublishStreamGrpcClient {
 
     /**
      * Shutdowns the channel.
+     *
+     * @throws InterruptedException if the thread is interrupted
      */
     void shutdown() throws InterruptedException;
 }

simulator/src/main/java/com/hedera/block/simulator/grpc/impl/ConsumerStreamGrpcClientImpl.java

@@ -85,6 +85,7 @@ public void init() {
     public void requestBlocks(long startBlock, long endBlock) throws InterruptedException {
         Preconditions.requireWhole(startBlock);
         Preconditions.requireWhole(endBlock);
+        Preconditions.requireGreaterOrEqual(endBlock, startBlock);
 
         consumerStreamObserver = new ConsumerStreamObserver(metricsService, streamLatch, lastKnownStatuses);
 
@@ -99,7 +100,7 @@ public void requestBlocks(long startBlock, long endBlock) throws InterruptedExce
     }
 
     @Override
-    public void completeStreaming() throws InterruptedException {
+    public void completeStreaming() {
         streamLatch.countDown();
         channel.shutdown();
     }

simulator/src/main/java/com/hedera/block/simulator/grpc/impl/PublishStreamGrpcClientImpl.java

@@ -193,6 +193,8 @@ public List<String> getLastKnownStatuses() {
 
     /**
      * Shutdowns the channel.
+     *
+     * @throws InterruptedException if the thread is interrupted
      */
     @Override
     public void shutdown() throws InterruptedException {