lws-fault-injection.h (8933B)
1/* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 * 24 * Fault injection api if built with LWS_WITH_SYS_FAULT_INJECTION 25 */ 26 27typedef struct lws_xos { 28 uint64_t s[4]; 29} lws_xos_t; 30 31/** 32 * lws_xos_init() - seed xoshiro256 PRNG 33 * 34 * \param xos: the prng state object to initialize 35 * \param seed: the 64-bit seed 36 * 37 * Initialize PRNG \xos with the starting state represented by \p seed 38 */ 39LWS_VISIBLE LWS_EXTERN void 40lws_xos_init(struct lws_xos *xos, uint64_t seed); 41 42/** 43 * lws_xos() - get next xoshiro256 PRNG result and update state 44 * 45 * \param xos: the PRNG state to use 46 * 47 * Returns next 64-bit PRNG result. These are cheap to get, 48 * quite a white noise sequence, and completely deterministic 49 * according to the seed it was initialized with. 50 */ 51LWS_VISIBLE LWS_EXTERN uint64_t LWS_WARN_UNUSED_RESULT 52lws_xos(struct lws_xos *xos); 53 54/** 55 * lws_xos_percent() - return 1 a given percent of the time on average 56 * 57 * \param xos: the PRNG state to use 58 * \param percent: chance in 100 of returning 1 59 * 60 * Returns 1 if next random % 100 is < \p percent, such that 61 * 100 always returns 1, 0 never returns 1, and the chance linearly scales 62 * inbetween 63 */ 64LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 65lws_xos_percent(struct lws_xos *xos, int percent); 66 67#if defined(LWS_WITH_SYS_FAULT_INJECTION) 68 69enum { 70 LWSFI_ALWAYS, 71 LWSFI_DETERMINISTIC, /* do .count injections after .pre then stop */ 72 LWSFI_PROBABILISTIC, /* .pre % chance of injection */ 73 LWSFI_PATTERN, /* use .count bits in .pattern after .pre */ 74 LWSFI_PATTERN_ALLOC, /* as _PATTERN, but .pattern is malloc'd */ 75 LWSFI_RANGE /* pick a number between pre and count */ 76}; 77 78typedef struct lws_fi { 79 const char *name; 80 const uint8_t *pattern; 81 uint64_t pre; 82 uint64_t count; 83 uint64_t times; /* start at 0, tracks usage */ 84 char type; /* LWSFI_* */ 85} lws_fi_t; 86 87typedef struct lws_fi_ctx { 88 lws_dll2_owner_t fi_owner; 89 struct lws_xos xos; 90 const char *name; 91} lws_fi_ctx_t; 92 93/** 94 * lws_fi() - find out if we should perform the named fault injection this time 95 * 96 * \param fic: fault injection tracking context 97 * \param fi_name: name of fault injection 98 * 99 * This checks if the named fault is configured in the fi tracking context 100 * provided, if it is, then it will make a decision if the named fault should 101 * be applied this time, using the tracking in the named lws_fi_t. 102 * 103 * If the provided context has a parent, that is also checked for the named fi 104 * item recursively, with the first found being used to determine if to inject 105 * or not. 106 * 107 * If LWS_WITH_SYS_FAULT_INJECTION is not defined, then this always return 0. 108 */ 109LWS_VISIBLE LWS_EXTERN int 110lws_fi(const lws_fi_ctx_t *fic, const char *fi_name); 111 112/** 113 * lws_fi_range() - get a random number from a range 114 * 115 * \param fic: fault injection tracking context 116 * \param fi_name: name of fault injection 117 * \param result: points to uint64_t to be set to the result 118 * 119 * This lets you get a random number from an externally-set range, set using a 120 * fault injection syntax like "myfault(123..456)". That will cause us to 121 * return a number between those two inclusive, from the seeded PRNG. 122 * 123 * This is useful when you used lws_fi() with its own fault name to decide 124 * whether to inject the fault, and then the code to cause the fault needs 125 * additional constrained pseudo-random fuzzing for, eg, delays before issuing 126 * the fault. 127 * 128 * Returns 0 if \p *result is set, else nonzero for failure. 129 */ 130LWS_VISIBLE LWS_EXTERN int 131lws_fi_range(const lws_fi_ctx_t *fic, const char *name, uint64_t *result); 132 133/** 134 * lws_fi_add() - add an allocated copy of fault injection to a context 135 * 136 * \param fic: fault injection tracking context 137 * \param fi: the fault injection details 138 * 139 * This allocates a copy of \p fi and attaches it to the fault injection context 140 * \p fic. \p fi can go out of scope after this safely. 141 */ 142LWS_VISIBLE LWS_EXTERN int 143lws_fi_add(lws_fi_ctx_t *fic, const lws_fi_t *fi); 144 145/** 146 * lws_fi_remove() - remove an allocated copy of fault injection from a context 147 * 148 * \param fic: fault injection tracking context 149 * \param name: the fault injection name to remove 150 * 151 * This looks for the named fault injection and removes and destroys it from 152 * the specified fault injection context 153 */ 154LWS_VISIBLE LWS_EXTERN void 155lws_fi_remove(lws_fi_ctx_t *fic, const char *name); 156 157/** 158 * lws_fi_import() - transfers all the faults from one context to another 159 * 160 * \param fic_dest: the fault context to receive the faults 161 * \param fic_src: the fault context that will be emptied out into \p fic_dest 162 * 163 * This is used to initialize created object fault injection contexts from 164 * the caller. 165 */ 166LWS_VISIBLE LWS_EXTERN void 167lws_fi_import(lws_fi_ctx_t *fic_dest, const lws_fi_ctx_t *fic_src); 168 169/** 170 * lws_fi_inherit_copy() - attach copies of matching fault injection objects to dest 171 * 172 * \param fic_dest: destination Fault Injection context 173 * \param fic_src: parent fault context that may contain matching rules 174 * \param scope: the name of the path match required, eg, "vh" 175 * \param value: the dynamic name of our match, eg, "myvhost" 176 * 177 * If called with scope "vh" and value "myvhost", then matches faults starting 178 * "vh=myvhost/", strips that part of the name if it matches and makes a copy 179 * of the rule with the modified name attached to the destination Fault Injection 180 * context. 181 */ 182LWS_VISIBLE LWS_EXTERN void 183lws_fi_inherit_copy(lws_fi_ctx_t *fic_dest, const lws_fi_ctx_t *fic_src, 184 const char *scope, const char *value); 185 186/** 187 * lws_fi_destroy() - removes all allocated fault injection entries 188 * 189 * \param fic: fault injection tracking context 190 * 191 * This walks any allocated fault injection entries in \p fic and detaches and 192 * destroys them. It doesn't try to destroc \p fic itself, since this is 193 * not usually directly allocated. 194 */ 195LWS_VISIBLE LWS_EXTERN void 196lws_fi_destroy(const lws_fi_ctx_t *fic); 197 198/** 199 * lws_fi_deserialize() - adds fault in string form to Fault Injection Context 200 * 201 * \p fic: the fault injection context 202 * \p sers: the string serializing the desired fault details 203 * 204 * This turns a string like "ss=captive_portal_detect/wsi/dnsfail(10%)" into 205 * a fault injection struct added to the fault injection context \p fic 206 * 207 * You can prepare the context creation info .fic with these before creating 208 * the context, and use namespace paths on those to target other objects. 209 */ 210 211LWS_VISIBLE LWS_EXTERN void 212lws_fi_deserialize(lws_fi_ctx_t *fic, const char *sers); 213 214LWS_VISIBLE LWS_EXTERN int 215_lws_fi_user_wsi_fi(struct lws *wsi, const char *name); 216LWS_VISIBLE LWS_EXTERN int 217_lws_fi_user_context_fi(struct lws_context *ctx, const char *name); 218 219#if defined(LWS_WITH_SECURE_STREAMS) 220struct lws_ss_handle; 221LWS_VISIBLE LWS_EXTERN int 222_lws_fi_user_ss_fi(struct lws_ss_handle *h, const char *name); 223#if defined(LWS_WITH_SECURE_STREAMS_PROXY_API) 224struct lws_sspc_handle; 225LWS_VISIBLE LWS_EXTERN int 226_lws_fi_user_sspc_fi(struct lws_sspc_handle *h, const char *name); 227#endif 228#endif 229 230#define lws_fi_user_wsi_fi(_wsi, _name) _lws_fi_user_wsi_fi(_wsi, _name) 231#define lws_fi_user_context_fi(_ctx, _name) _lws_fi_user_context_fi(_ctx, _name) 232#define lws_fi_user_ss_fi(_h, _name) _lws_fi_user_ss_fi(_h, _name) 233#define lws_fi_user_sspc_fi(_h, _name) _lws_fi_user_sspc_fi(_h, _name) 234 235#else 236 237/* 238 * Helper so we can leave lws_fi() calls embedded in the code being tested, 239 * if fault injection is not enabled then it just always says "no" at buildtime. 240 */ 241 242#define lws_fi(_fi_name, _fic) (0) 243#define lws_fi_destroy(_x) 244#define lws_fi_inherit_copy(_a, _b, _c, _d) 245#define lws_fi_deserialize(_x, _y) 246#define lws_fi_user_wsi_fi(_wsi, _name) (0) 247#define lws_fi_user_context_fi(_wsi, _name) (0) 248#define lws_fi_user_ss_fi(_h, _name) (0) 249#define lws_fi_user_sspc_fi(_h, _name) (0) 250 251#endif