Clarify naming around spam filtering.

service/src/main/java/org/whispersystems/textsecuregcm/spam/FilterSpam.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2013-2021 Signal Messenger, LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+package org.whispersystems.textsecuregcm.spam;
+
+import javax.ws.rs.NameBinding;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A name-binding annotation that associates {@link SpamFilter}s with resource methods.
+ */
+@NameBinding
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD})
+public @interface FilterSpam {
+}

service/src/main/java/org/whispersystems/textsecuregcm/spam/RateLimitChallengeListener.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2013-2021 Signal Messenger, LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+package org.whispersystems.textsecuregcm.spam;
+
+
+import org.whispersystems.textsecuregcm.storage.Account;
+import java.io.IOException;
+
+public interface RateLimitChallengeListener {
+
+  void handleRateLimitChallengeAnswered(Account account);
+
+  /**
+   * Configures this rate limit challenge listener. This method will be called before the service begins processing any
+   * challenges.
+   *
+   * @param environmentName the name of the environment in which this listener is running (e.g. "staging" or "production")
+   * @throws IOException if the listener could not read its configuration source for any reason
+   */
+  void configure(String environmentName) throws IOException;
+}

service/src/main/java/org/whispersystems/textsecuregcm/spam/RateLimitChallengeType.java

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2013-2021 Signal Messenger, LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+package org.whispersystems.textsecuregcm.spam;
+
+public enum RateLimitChallengeType {
+
+  PUSH_CHALLENGE,
+  RECAPTCHA
+}

service/src/main/java/org/whispersystems/textsecuregcm/spam/ReportSpamTokenHandler.java

@@ -0,0 +1,47 @@
+package org.whispersystems.textsecuregcm.spam;
+
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Handles ReportSpamTokens during spam reports.
+ */
+public interface ReportSpamTokenHandler {
+
+  /**
+   * Handle spam reports using the given ReportSpamToken and other provided parameters.
+   *
+   * @param reportSpamToken binary data representing a spam report token.
+   * @return true if the token could be handled (and was), false otherwise.
+   */
+  CompletableFuture<Boolean> handle(
+      Optional<String> sourceNumber,
+      Optional<UUID> sourceAci,
+      Optional<UUID> sourcePni,
+      UUID messageGuid,
+      UUID spamReporterUuid,
+      byte[] reportSpamToken);
+
+  /**
+   * Handler which does nothing.
+   *
+   * @return the handler
+   */
+  static ReportSpamTokenHandler noop() {
+    return new ReportSpamTokenHandler() {
+      @Override
+      public CompletableFuture<Boolean> handle(
+          final Optional<String> sourceNumber,
+          final Optional<UUID> sourceAci,
+          final Optional<UUID> sourcePni,
+          final UUID messageGuid,
+          final UUID spamReporterUuid,
+          final byte[] reportSpamToken) {
+        return CompletableFuture.completedFuture(false);
+      }
+    };
+  }
+
+
+}

service/src/main/java/org/whispersystems/textsecuregcm/spam/ReportSpamTokenProvider.java

@@ -0,0 +1,38 @@
+package org.whispersystems.textsecuregcm.spam;
+
+import javax.ws.rs.container.ContainerRequestContext;
+import java.util.Optional;
+import java.util.function.Function;
+
+/**
+ * Generates ReportSpamTokens to be used for spam reports.
+ */
+public interface ReportSpamTokenProvider {
+
+  /**
+   * Generate a new ReportSpamToken
+   *
+   * @param context the message request context
+   * @return either a generated token or nothing
+   */
+  Optional<byte[]> makeReportSpamToken(ContainerRequestContext context);
+
+  /**
+   * Provider which generates nothing
+   *
+   * @return the provider
+   */
+  static ReportSpamTokenProvider noop() {
+    return create(c -> Optional.empty());
+  }
+
+  /**
+   * Provider which generates ReportSpamTokens using the given function
+   *
+   * @param fn function from message requests to optional tokens
+   * @return the provider
+   */
+  static ReportSpamTokenProvider create(Function<ContainerRequestContext, Optional<byte[]>> fn) {
+    return fn::apply;
+  }
+}

service/src/main/java/org/whispersystems/textsecuregcm/spam/SpamFilter.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2013-2021 Signal Messenger, LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+package org.whispersystems.textsecuregcm.spam;
+
+import io.dropwizard.lifecycle.Managed;
+import javax.ws.rs.container.ContainerRequestFilter;
+import java.io.IOException;
+
+/**
+ * A spam filter is a {@link ContainerRequestFilter} that filters requests to message-sending endpoints to
+ * detect and respond to patterns of spam.
+ * <p/>
+ * Spam filters are managed components that are generally loaded dynamically via a
+ * {@link java.util.ServiceLoader}. Their {@link #configure(String)} method will be called prior to be adding to the
+ * server's pool of {@link Managed} objects.
+ * <p/>
+ * Spam filters must be annotated with {@link FilterSpam}, a name binding annotation that
+ * restricts the endpoints to which the filter may apply.
+ */
+public interface SpamFilter extends ContainerRequestFilter, Managed {
+
+  /**
+   * Configures this spam filter. This method will be called before the filter is added to the server's pool
+   * of managed objects and before the server processes any requests.
+   *
+   * @param environmentName the name of the environment in which this filter is running (e.g. "staging" or "production")
+   * @throws IOException if the filter could not read its configuration source for any reason
+   */
+  void configure(String environmentName) throws IOException;
+
+  /**
+   * Builds a spam report token provider. This will generate tokens used by the spam reporting system.
+   *
+   * @return the configured spam report token provider.
+   */
+  ReportSpamTokenProvider getReportSpamTokenProvider();
+
+  /**
+   * Builds a spam report token handler. This will handle tokens received by the spam reporting system.
+   *
+   * @return the configured spam report token handler
+   */
+  ReportSpamTokenHandler getReportSpamTokenHandler();
+
+}