Package org.apache.cassandra.db.guardrails

Class Threshold

  • Direct Known Subclasses:
    MaxThreshold, MinThreshold
    public abstract class Threshold
extends Guardrail
    A guardrail based on numeric threshold(s).

    A Threshold guardrail defines (up to) 2 thresholds, one at which a warning is issued, and a lower one at which the operation is aborted with an exception. Only one of those thresholds can be activated if desired.

    This guardrail only handles guarding positive values.

    • Field Detail

      • warnThreshold

        protected java.util.function.ToLongFunction<ClientState> warnThreshold

      • failThreshold

        protected java.util.function.ToLongFunction<ClientState> failThreshold

      • messageProvider

        protected final org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider messageProvider

    • Constructor Detail

      • Threshold

        public Threshold​(java.lang.String name,
                 @Nullable
                 java.lang.String reason,
                 java.util.function.ToLongFunction<ClientState> warnThreshold,
                 java.util.function.ToLongFunction<ClientState> failThreshold,
                 org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider messageProvider)
        Creates a new threshold guardrail.
        Parameters:
        name - the identifying name of the guardrail
        reason - the optional description of the reason for guarding the operation
        warnThreshold - a ClientState-based provider of the value above which a warning should be triggered.
        failThreshold - a ClientState-based provider of the value above which the operation should be aborted.
        messageProvider - a function to generate the warning or error message if the guardrail is triggered

    • Method Detail

      • compare

        protected abstract boolean compare​(long value,
                                   long threshold)

      • errMsg

        protected java.lang.String errMsg​(boolean isWarning,
                                  java.lang.String what,
                                  long value,
                                  long thresholdValue)

      • failValue

        protected abstract long failValue​(ClientState state)

      • warnValue

        protected abstract long warnValue​(ClientState state)

      • enabled

        public boolean enabled​(@Nullable
                       ClientState state)
        Description copied from class: Guardrail
        Checks whether this guardrail is enabled or not. This will be enabled if the database is initialized and the authenticated user (if specified) is not system nor superuser.
        Overrides:
        enabled in class Guardrail
        Parameters:
        state - the client state, used to skip the check if the query is internal or is done by a superuser. A null value means that the check should be done regardless of the query.
        Returns:
        true if this guardrail is enabled, false otherwise.

      • triggersOn

        public boolean triggersOn​(long value,
                          @Nullable
                          ClientState state)
        Checks whether the provided value would trigger a warning or failure if passed to guard(long, java.lang.String, boolean, org.apache.cassandra.service.ClientState).

        This method is optional (does not have to be called) but can be used in the case where the "what" argument to guard(long, java.lang.String, boolean, org.apache.cassandra.service.ClientState) is expensive to build to save doing so in the common case (of the guardrail not being triggered).

        Parameters:
        value - the value to test.
        state - The client state, used to skip the check if the query is internal or is done by a superuser. A null value means that the check should be done regardless of the query.
        Returns:
        true if value is above the warning or failure thresholds of this guardrail, false otherwise.

      • warnsOn

        public boolean warnsOn​(long value,
                       @Nullable
                       ClientState state)

      • failsOn

        public boolean failsOn​(long value,
                       @Nullable
                       ClientState state)

      • guard

        public void guard​(long value,
                  java.lang.String what,
                  boolean containsUserData,
                  @Nullable
                  ClientState state)
        Apply the guardrail to the provided value, warning or failing if appropriate.
        Parameters:
        value - The value to check.
        what - A string describing what value is a value of. This is used in the error message if the guardrail is triggered. For instance, say the guardrail guards the size of column values, then this argument must describe which column of which row is triggering the guardrail for convenience.
        containsUserData - whether the what contains user data that should be redacted on external systems.
        state - The client state, used to skip the check if the query is internal or is done by a superuser. A null value means that the check should be done regardless of the query.