experiment/SecExperimentInternal.h

   1 //
   2 //  SecExperimentInternal.h
   3 //  Security
   4 //
   5
   6 #ifndef SecExperimentInternal_h
   7 #define SecExperimentInternal_h
   8
   9 #include <Security/SecExperimentPriv.h>
  10
  11 SEC_ASSUME_NONNULL_BEGIN
  12
  13 extern const NSString *SecExperimentConfigurationKeyFleetSampleRate;
  14 extern const NSString *SecExperimentConfigurationKeyDeviceSampleRate;
  15 extern const NSString *SecExperimentConfigurationKeyExperimentIdentifier;
  16 extern const NSString *SecExperimentConfigurationKeyConfigurationData;
  17
  18 @interface SecExperimentConfig : NSObject
  19 @property (readonly) NSString *identifier;
  20 @property (readonly) uint32_t fleetSampleRate;
  21 @property (readonly) uint32_t deviceSampleRate;
  22 @property (readonly) NSDictionary *configurationData;
  23 @property (readonly) BOOL isSampled;
  24 - (instancetype)initWithConfiguration:(NSDictionary *)configuration;
  25
  26 // Note: these functions are exposed for testing purposes only.
  27 - (uint32_t)hostHash;
  28 - (BOOL)shouldRunWithSamplingRate:(NSNumber *)sampleRate;
  29 @end
  30
  31 @interface SecExperiment : NSObject
  32 @property (readonly) NSString *name;
  33 @property (readonly, nullable) NSString *identifier;
  34 @property (readonly) BOOL samplingDisabled;
  35 - (instancetype)initWithName:(const char *)name;
  36 - (BOOL)experimentIsAllowedForProcess;
  37 - (BOOL)isSamplingDisabledWithDefault:(BOOL)defaultValue;
  38 - (BOOL)isSamplingDisabled;
  39 - (SecExperimentConfig *)copyExperimentConfiguration;
  40
  41 // Note: These functions are exposed for testing purposes only.
  42 - (NSDictionary *)copyExperimentConfigurationFromUserDefaults;
  43 - (NSDictionary *)copyRemoteExperimentAsset;
  44 - (NSDictionary *)copyRandomExperimentConfigurationFromAsset:(NSDictionary *)asset;
  45 @end
  46
  47 /*!
  48  * @function sec_experiment_create_with_inner_experiment
  49  *
  50  * @abstract
  51  *      Create an ARC-able `sec_experiment_t` instance wrapping an internal `SecExperiment` object.
  52  *
  53  * @param experiment
  54  *      The experiment
  55  *
  56  * @return a `sec_experiment_t` instance.
  57  */
  58 SEC_RETURNS_RETAINED _Nullable sec_experiment_t
  59 sec_experiment_create_with_inner_experiment(SecExperiment *experiment);
  60
  61 /*!
  62  * @function sec_experiment_run_internal
  63  *
  64  * @abstract
  65  *      Asynchronously run an experiment, optionally disabling sampling if desired.
  66  *
  67  *      Note: This function MUST NOT be called outside of tests.
  68  *
  69  * @param experiment
  70  *      A `sec_experiment_t` to run.
  71  *
  72  * @param sampling_disabled
  73  *      Flag to disable sampling.
  74  *
  75  * @param queue
  76  *      Queue on which to run the experiment.
  77  *
  78  * @param run_block
  79  *      A `sec_experiment_run_block_t` block upon which to execute the given experiment.
  80  *
  81  * @param skip_block
  82  *      An optional `sec_experiment_skip_block_t` block that is invoked when the chosen experiment is skipped.
  83  *
  84  * @param synchronous
  85  *      A boolean indicating if the given experiment should be run synchronously (true) or asynchronously (false).
  86  *
  87  * @return True if the experiment was started, and false otherwise.
  88  */
  89 bool
  90 sec_experiment_run_internal(sec_experiment_t experiment,
  91                             bool sampling_disabled,
  92                             dispatch_queue_t _Nullable queue,
  93                             sec_experiment_run_block_t run_block,
  94                             sec_experiment_skip_block_t _Nullable skip_block,
  95                             bool synchronous);
  96
  97 /*!
  98 * @function sec_experiment_get_run_count
  99 *
 100 * @abstract
 101 *      Determine the number of times an experiment ran.
 102 *
 103 * @param experiment
 104 *      A `sec_experiment_t` instance.
 105 *
 106 * @return Number of times the experiment was run.
 107 */
 108 size_t
 109 sec_experiment_get_run_count(sec_experiment_t experiment);
 110
 111 /*!
 112  * @function sec_experiment_get_successful_run_count
 113  *
 114  * @abstract
 115  *      Determine the number of times an experiment successfully ran.
 116  *
 117  * @param experiment
 118  *      A `sec_experiment_t` instance.
 119  *
 120  * @return Number of times the experiment was run successfully.
 121 */
 122 size_t
 123 sec_experiment_get_successful_run_count(sec_experiment_t experiment);
 124
 125 /*!
 126  * @function sec_experiment_get_identifier
 127  *
 128  * @abstract
 129  *      Get the selected experiment identifier.
 130  *
 131  * @param experiment
 132  *      A `sec_experiment_t` instance.
 133  *
 134  * @return The internal experiment identifier, or NULL if one was not yet chosen.
 135 */
 136 const char * _Nullable
 137 sec_experiment_get_identifier(sec_experiment_t experiment);
 138
 139 SEC_ASSUME_NONNULL_END
 140
 141 #endif /* SecExperimentInternal_h */