dom/quota/ArtificialFailure.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef DOM_QUOTA_ARTIFICIALFAILURE_H_
   8 #define DOM_QUOTA_ARTIFICIALFAILURE_H_
   9
  10 #include <cstdint>
  11
  12 #include "nsIQuotaArtificialFailure.h"
  13
  14 enum class nsresult : uint32_t;
  15
  16 namespace mozilla {
  17
  18 struct Ok;
  19 template <typename V, typename E>
  20 class Result;
  21
  22 }  // namespace mozilla
  23
  24 namespace mozilla::dom::quota {
  25
  26 /**
  27  * Checks if an artificial failure should be triggered based on the specified
  28  * category and the configured probability.
  29  *
  30  * This method evaluates if the provided failure category matches the
  31  * categories set in the preferences. If a match is found, it then checks
  32  * the probability of triggering an artificial failure. A random value is
  33  * generated to determine if the failure should occur based on this
  34  * probability. If both the category matches and the random value falls within
  35  * the defined probability, the method returns an error code indicating the
  36  * artificial failure. Otherwise, it returns a successful result.
  37  *
  38  * @param aCategory - The failure category to check against the configured
  39  *   categories for triggering an artificial failure. It must have only one bit
  40  *   set.
  41  * @returns Result<Ok, nsresult> - An Ok result if no failure occurs; an Err
  42  *   result containing an error code if an artificial failure is triggered.
  43  *
  44  * Note:
  45  * Consider replacing the preferences with a dedicated class with static
  46  * methods for entering and leaving artificial failure mode, something like
  47  * `ChaosMode`. The class would also implement an interface, for example
  48  * `nsIQuotaArtificialFailure` allowing access from scripts.
  49  *
  50  * Example usage:
  51  * This example demonstrates the usage of `ArtificialFailure` in conjunction
  52  * with the `QM_TRY` macro to handle potential artificial failures gracefully.
  53  * The `QM_TRY` macro will return early if an artificial failure occurs, with
  54  * the corresponding error code from `ArtificialFailure`.
  55  *
  56  * ```cpp
  57  * QM_TRY(ArtificialFailure(
  58  *     nsIQuotaArtificialFailure::CATEGORY_INITIALIZE_ORIGIN));
  59  * ```
  60  */
  61 Result<Ok, nsresult> ArtificialFailure(
  62     nsIQuotaArtificialFailure::Category aCategory);
  63
  64 }  // namespace mozilla::dom::quota
  65
  66 #endif  // DOM_QUOTA_ARTIFICIALFAILURE_H_