Refinements in logic

Signed-off-by: Emilien Bevierre <emilien.bevierre@couchbase.com>

Author: emilienbev

src/main/java/org/springframework/data/couchbase/core/ReactiveFindBySearchOperationSupport.java

@@ -104,7 +104,7 @@ static class ReactiveFindBySearchSupport<T> implements ReactiveFindBySearch<T> {
 
 		@Override
 		public TerminatingFindBySearch<T> matching(SearchRequest searchRequest) {
-			Assert.notNull(searchRequest, "SearchRequest must not be null!");
+			Assert.notNull(searchRequest, "SearchRequest must not be null");
 			return new ReactiveFindBySearchSupport<>(template, domainType, returnType, indexName, searchRequest,
 					scanConsistency, scope, collection, options, sort, highlightStyle, highlightFields, facets,
 					fields, limitSkip, support);
@@ -120,7 +120,7 @@ public FindBySearchWithProjection<T> withIndex(String indexName) {
 
 		@Override
 		public <R> FindBySearchWithFields<R> as(final Class<R> returnType) {
-			Assert.notNull(returnType, "returnType must not be null!");
+			Assert.notNull(returnType, "returnType must not be null");
 			return new ReactiveFindBySearchSupport<>(template, domainType, returnType, indexName, searchRequest,
 					scanConsistency, scope, collection, options, sort, highlightStyle, highlightFields, facets,
 					fields, limitSkip, support);
@@ -316,18 +316,20 @@ private Mono<SearchResult<T>> collectFullResult(ReactiveSearchResult reactiveRes
 		}
 
 		/**
-		 * Hydrates a SearchRow into an entity via KV GET, silently skipping documents that have been
+		 * Hydrates a SearchRow into an entity via KV GET, skipping documents that have been
 		 * deleted between the FTS index update and the KV fetch (stale index entries).
+		 * <p>
+		 * Misses are logged at WARN so operators can detect index staleness; persistent or high-volume
+		 * misses typically indicate an out-of-sync FTS index.
 		 */
 		private Mono<T> hydrateRow(SearchRow row) {
 			return template.findById(returnType)
 					.inScope(scope)
 					.inCollection(collection)
 					.one(row.id())
 					.onErrorResume(com.couchbase.client.core.error.DocumentNotFoundException.class, ex -> {
-						if (LOG.isDebugEnabled()) {
-							LOG.debug("Skipping stale FTS result for document id '{}': document not found in KV", row.id());
-						}
+						LOG.warn("Skipping stale FTS result for document id '{}': document not found in KV "
+								+ "(index '{}' may be out of sync)", row.id(), indexName);
 						return Mono.empty();
 					});
 		}

src/main/java/org/springframework/data/couchbase/repository/Search.java

@@ -30,7 +30,18 @@
  * The FTS index name must be specified via {@link SearchIndex} on the method or entity class.
  * <p>
  * Supports positional parameter placeholders ({@code ?0}, {@code ?1}, etc.) which are replaced with method argument
- * values at execution time. Example:
+ * values at execution time.
+ * <p>
+ * <strong>Parameter binding semantics (injection considerations):</strong> String and {@link Enum} values are always
+ * emitted as quoted FTS phrases ({@code "..."}), with embedded {@code "} and {@code \} escaped. This prevents a
+ * parameter value from breaking out of its phrase context and injecting FTS operators ({@code AND}, {@code OR},
+ * {@code :}, {@code *}, field selectors, etc.). {@link Number} and {@link Boolean} values are emitted verbatim so they
+ * remain usable with range operators (e.g. {@code rating:>=?0}); their types are validated, so no operator injection
+ * is possible. Because string parameters are always phrase-quoted, there is no way to pass a <em>raw</em> FTS term or
+ * operator through a placeholder. Construct a {@link com.couchbase.client.java.search.SearchRequest} and use the
+ * template API ({@code CouchbaseOperations.findBySearch(...)}) if you need that.
+ * <p>
+ * Example:
  * <pre>
  * &#64;Search("description:pool AND city:\"San Francisco\"")
  * &#64;SearchIndex("hotel-search-index")

src/main/java/org/springframework/data/couchbase/repository/query/ReactiveSearchBasedCouchbaseQuery.java

@@ -37,6 +37,11 @@
  * Supports positional parameter substitution ({@code ?0}, {@code ?1}, etc.) in the query string.
  * Supports {@link Pageable} parameters for limit/skip pagination.
  * Supports {@link org.springframework.data.couchbase.repository.ScanConsistency} for FTS scan consistency.
+ * <p>
+ * {@link org.springframework.data.domain.Page} and {@link org.springframework.data.domain.Slice} return types are
+ * <em>not</em> supported on reactive search methods. Use the imperative repository or the reactive template API
+ * ({@link org.springframework.data.couchbase.core.ReactiveFindBySearchOperation.TerminatingFindBySearch#result()})
+ * if you need total row counts alongside entities.
  *
  * @author Emilien Bevierre
  * @since 6.2
@@ -86,6 +91,13 @@ public ReactiveCouchbaseQueryMethod getQueryMethod() {
 	}
 
 	private Object executeDependingOnType(ParametersParameterAccessor accessor, SearchRequest request) {
+		if (method.isPageQuery() || method.isSliceQuery()) {
+			throw new UnsupportedOperationException(
+					"Page and Slice return types are not supported for reactive @Search repository methods. "
+							+ "Use the imperative repository for pagination, or the reactive template API "
+							+ "(ReactiveCouchbaseOperations.findBySearch(...).result()) to access total rows.");
+		}
+
 		ReactiveFindBySearchOperation.FindBySearchWithQuery<?> queryOp = createQueryOperation(accessor, true);
 
 		if (method.isCountQuery()) {

src/test/java/org/springframework/data/couchbase/repository/query/ReactiveSearchBasedCouchbaseQueryTests.java

@@ -36,6 +36,10 @@
 import org.springframework.data.couchbase.domain.User;
 import org.springframework.data.couchbase.repository.Search;
 import org.springframework.data.couchbase.repository.SearchIndex;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Slice;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.mapping.context.MappingContext;
 import org.springframework.data.projection.SpelAwareProxyProjectionFactory;
@@ -93,6 +97,20 @@ void executeResolvesReactiveWrapperParameters() {
 		assertEquals("\"match\"", capturedQuery.get());
 	}
 
+	@Test
+	void rejectsPageReturnTypeAtConstruction() {
+		Throwable thrown = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
+				() -> createQueryMethod("searchPaged", "match", PageRequest.of(0, 10)));
+		org.junit.jupiter.api.Assertions.assertInstanceOf(InvalidDataAccessApiUsageException.class, thrown.getCause());
+	}
+
+	@Test
+	void rejectsSliceReturnTypeAtConstruction() {
+		Throwable thrown = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
+				() -> createQueryMethod("searchSliced", "match", PageRequest.of(0, 10)));
+		org.junit.jupiter.api.Assertions.assertInstanceOf(InvalidDataAccessApiUsageException.class, thrown.getCause());
+	}
+
 	@Test
 	void executeRejectsSpringSortParameters() {
 		ReactiveSearchBasedCouchbaseQuery query = new ReactiveSearchBasedCouchbaseQuery(
@@ -117,6 +135,14 @@ interface TestReactiveSearchRepository extends ReactiveCrudRepository<User, Stri
 		@Search("?0")
 		@SearchIndex("test-index")
 		Flux<User> searchSorted(String query, Sort sort);
+
+		@Search("?0")
+		@SearchIndex("test-index")
+		Mono<Page<User>> searchPaged(String query, Pageable pageable);
+
+		@Search("?0")
+		@SearchIndex("test-index")
+		Mono<Slice<User>> searchSliced(String query, Pageable pageable);
 	}
 
 	interface NameOnly {