Clarify the behavior of some extension points

turms-im · Dec 4, 2023 · ae93a34 · ae93a34
1 parent 28dead8
commit ae93a34
Show file tree

Hide file tree

Showing 6 changed files with 126 additions and 5 deletions.
diff --git a/turms-gateway/src/main/java/im/turms/gateway/infra/plugin/extension/UserAuthenticator.java b/turms-gateway/src/main/java/im/turms/gateway/infra/plugin/extension/UserAuthenticator.java
@@ -30,11 +30,12 @@
 public interface UserAuthenticator extends ExtensionPoint {
 
     /**
-     * @return 1. Return Mono.just(true) if the user is authenticated.
+     * @return 1. Return a {@link Mono} that emits true if the user is authenticated.
      *         <p>
-     *         2. Return Mono.just(false) if the user is unauthenticated.
+     *         2. Return a {@link Mono} that emits false if the user is unauthenticated.
      *         <p>
-     *         3. Return Mono.empty() if the authentication should be processed by the next handler.
+     *         3. Return a {@link Mono} that completes without emitting any value if you want the
+     *         next handler to decide if the user is authenticated or not.
      */
     Mono<Boolean> authenticate(@NotNull UserLoginInfo userLoginInfo);
 

diff --git a/...s-service/src/main/java/im/turms/service/infra/plugin/extension/ClientRequestHandler.java b/...s-service/src/main/java/im/turms/service/infra/plugin/extension/ClientRequestHandler.java
@@ -31,7 +31,11 @@
 public interface ClientRequestHandler extends ExtensionPoint {
 
     /**
-     * @return returning Mono.empty() will pass the request to downstream to handle.
+     * @return 1. Return a {@link Mono} that completes without emitting any request handler result
+     *         if you want to pass the original client request to the next handler to handle.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a request handler result as the final handle
+     *         result if you don't want to pass the client request to the next handler to handle.
      */
     Mono<RequestHandlerResult> handle(@NotNull ClientRequest clientRequest);
 

diff --git a/...rvice/src/main/java/im/turms/service/infra/plugin/extension/ClientRequestTransformer.java b/...rvice/src/main/java/im/turms/service/infra/plugin/extension/ClientRequestTransformer.java
@@ -30,7 +30,11 @@
 public interface ClientRequestTransformer extends ExtensionPoint {
 
     /**
-     * @return the returned {@link ClientRequest} will be passed to downstream.
+     * @return 1. Return a {@link Mono} that completes without emitting any client request if you
+     *         want to use the initial (original) client request as the final client request.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a client request if you want to pass the client
+     *         request to the next transformer to transform.
      */
     Mono<ClientRequest> transform(@NotNull ClientRequest clientRequest);
 

diff --git a/...src/main/java/im/turms/service/infra/plugin/extension/ExpiredMessageDeletionNotifier.java b/...src/main/java/im/turms/service/infra/plugin/extension/ExpiredMessageDeletionNotifier.java
@@ -33,6 +33,13 @@
  */
 public interface ExpiredMessageDeletionNotifier extends ExtensionPoint {
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any list, or emits an empty
+     *         list if you don't want to delete any message.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a non-empty list if you want to delete messages
+     *         in the list.
+     */
     Mono<List<Message>> getMessagesToDelete(@NotEmpty List<Message> messages);
 
 }
diff --git a/...ce/src/main/java/im/turms/service/infra/plugin/extension/RequestHandlerResultHandler.java b/...ce/src/main/java/im/turms/service/infra/plugin/extension/RequestHandlerResultHandler.java
@@ -31,13 +31,29 @@
  */
 public interface RequestHandlerResultHandler extends ExtensionPoint {
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any request handler result
+     *         if you don't want to pass the client request result to the next handler and want to
+     *         stop notification propagation.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a request handler result if you want to pass the
+     *         client request to the next handler.
+     */
     default Mono<RequestHandlerResult> beforeNotify(
             @NotNull RequestHandlerResult result,
             @NotNull Long requesterId,
             @NotNull DeviceType requesterDevice) {
         return Mono.empty();
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any request handler result
+     *         if you don't want to pass the client request result to the next handler and want to
+     *         stop notification propagation.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a request handler result if you want to pass the
+     *         client request to the next handler.
+     */
     default Mono<RequestHandlerResult> afterNotify(
             @NotNull RequestHandlerResult result,
             @NotNull Long requesterId,

diff --git a/...service/src/main/java/im/turms/service/infra/plugin/extension/StorageServiceProvider.java b/...service/src/main/java/im/turms/service/infra/plugin/extension/StorageServiceProvider.java
@@ -26,6 +26,7 @@
 import reactor.core.publisher.Mono;
 
 import im.turms.server.common.access.admin.web.MediaType;
+import im.turms.server.common.access.common.ResponseStatusCode;
 import im.turms.server.common.infra.exception.NotImplementedException;
 import im.turms.server.common.infra.plugin.ExtensionPoint;
 import im.turms.server.common.infra.time.DateRange;
@@ -44,6 +45,14 @@ default Mono<Void> deleteUserProfilePicture(
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryUserProfilePictureUploadInfo(
             @NotNull Long requesterId,
             @Nullable String resourceName,
@@ -52,6 +61,14 @@ default Mono<Map<String, String>> queryUserProfilePictureUploadInfo(
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryUserProfilePictureDownloadInfo(
             @NotNull Long requesterId,
             @NotNull Long userId,
@@ -68,6 +85,14 @@ default Mono<Void> deleteGroupProfilePicture(
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryGroupProfilePictureUploadInfo(
             @NotNull Long requesterId,
             @NotNull Long groupId,
@@ -77,6 +102,14 @@ default Mono<Map<String, String>> queryGroupProfilePictureUploadInfo(
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryGroupProfilePictureDownloadInfo(
             @NotNull Long requesterId,
             @NotNull Long groupId,
@@ -126,6 +159,14 @@ default Mono<Void> unshareMessageAttachmentWithGroup(
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryMessageAttachmentUploadInfo(
             @NotNull Long requesterId,
             @Nullable String resourceName,
@@ -134,6 +175,14 @@ default Mono<Map<String, String>> queryMessageAttachmentUploadInfo(
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryMessageAttachmentUploadInfoInPrivateConversation(
             @NotNull Long requesterId,
             @NotNull Long userId,
@@ -143,6 +192,14 @@ default Mono<Map<String, String>> queryMessageAttachmentUploadInfoInPrivateConve
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryMessageAttachmentUploadInfoInGroupConversation(
             @NotNull Long requesterId,
             @NotNull Long groupId,
@@ -152,6 +209,14 @@ default Mono<Map<String, String>> queryMessageAttachmentUploadInfoInGroupConvers
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a map if you want to respond the client request
+     *         with the map.
+     */
     default Mono<Map<String, String>> queryMessageAttachmentDownloadInfo(
             @NotNull Long requesterId,
             @Nullable Long messageAttachmentIdNum,
@@ -162,12 +227,28 @@ default Mono<Map<String, String>> queryMessageAttachmentDownloadInfo(
 
     // Message attachment - Info
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a list if you want to respond the client request
+     *         with the list.
+     */
     default Mono<List<StorageResourceInfo>> queryMessageAttachmentInfosUploadedByRequester(
             @NotNull Long requesterId,
             @Nullable DateRange creationDateRange) {
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a list if you want to respond the client request
+     *         with the list.
+     */
     default Mono<List<StorageResourceInfo>> queryMessageAttachmentInfosInPrivateConversations(
             @NotNull Long requesterId,
             @Nullable Set<Long> userIds,
@@ -176,6 +257,14 @@ default Mono<List<StorageResourceInfo>> queryMessageAttachmentInfosInPrivateConv
         return Mono.error(new NotImplementedException());
     }
 
+    /**
+     * @return 1. Return a {@link Mono} that completes without emitting any value if you want to
+     *         respond the client request with the status code
+     *         {@link ResponseStatusCode#NO_CONTENT}.
+     *         <p>
+     *         2. Return a {@link Mono} that emits a list if you want to respond the client request
+     *         with the list.
+     */
     default Mono<List<StorageResourceInfo>> queryMessageAttachmentInfosInGroupConversations(
             @NotNull Long requesterId,
             @Nullable Set<Long> groupIds,