@datadog/mobile-react-native 3.5.2 → 3.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/README.md +2 -2
  2. package/android/build.gradle +8 -7
  3. package/android/src/main/kotlin/com/datadog/reactnative/DdRumImplementation.kt +1 -0
  4. package/android/src/main/kotlin/com/datadog/reactnative/DdSdkConfiguration.kt +0 -1
  5. package/android/src/main/kotlin/com/datadog/reactnative/DdSdkImplementation.kt +10 -3
  6. package/android/src/main/kotlin/com/datadog/reactnative/DdSdkReactNativePackage.kt +0 -1
  7. package/android/src/main/kotlin/com/datadog/reactnative/SdkVersion.kt +1 -1
  8. package/android/src/test/kotlin/com/datadog/reactnative/DdSdkTest.kt +124 -49
  9. package/ios/Sources/DdLogsImplementation.swift +2 -2
  10. package/ios/Sources/DdSdkConfiguration.swift +0 -1
  11. package/ios/Sources/SdkVersion.swift +1 -1
  12. package/lib/commonjs/flags/FlagsClient.js +268 -3
  13. package/lib/commonjs/flags/FlagsClient.js.map +1 -1
  14. package/lib/commonjs/flags/configuration/context.js +70 -0
  15. package/lib/commonjs/flags/configuration/context.js.map +1 -0
  16. package/lib/commonjs/flags/configuration/index.js +39 -0
  17. package/lib/commonjs/flags/configuration/index.js.map +1 -0
  18. package/lib/commonjs/flags/configuration/precomputed.js +172 -0
  19. package/lib/commonjs/flags/configuration/precomputed.js.map +1 -0
  20. package/lib/commonjs/flags/configuration/types.js +33 -0
  21. package/lib/commonjs/flags/configuration/types.js.map +1 -0
  22. package/lib/commonjs/flags/configuration/wire.js +19 -0
  23. package/lib/commonjs/flags/configuration/wire.js.map +1 -0
  24. package/lib/commonjs/flags/internal.js +7 -3
  25. package/lib/commonjs/flags/internal.js.map +1 -1
  26. package/lib/commonjs/index.js +13 -0
  27. package/lib/commonjs/index.js.map +1 -1
  28. package/lib/commonjs/version.js +1 -1
  29. package/lib/module/flags/FlagsClient.js +268 -3
  30. package/lib/module/flags/FlagsClient.js.map +1 -1
  31. package/lib/module/flags/configuration/context.js +62 -0
  32. package/lib/module/flags/configuration/context.js.map +1 -0
  33. package/lib/module/flags/configuration/index.js +18 -0
  34. package/lib/module/flags/configuration/index.js.map +1 -0
  35. package/lib/module/flags/configuration/precomputed.js +165 -0
  36. package/lib/module/flags/configuration/precomputed.js.map +1 -0
  37. package/lib/module/flags/configuration/types.js +27 -0
  38. package/lib/module/flags/configuration/types.js.map +1 -0
  39. package/lib/module/flags/configuration/wire.js +13 -0
  40. package/lib/module/flags/configuration/wire.js.map +1 -0
  41. package/lib/module/flags/internal.js +7 -3
  42. package/lib/module/flags/internal.js.map +1 -1
  43. package/lib/module/index.js +2 -1
  44. package/lib/module/index.js.map +1 -1
  45. package/lib/module/version.js +1 -1
  46. package/lib/typescript/flags/FlagsClient.d.ts +96 -0
  47. package/lib/typescript/flags/FlagsClient.d.ts.map +1 -1
  48. package/lib/typescript/flags/configuration/context.d.ts +20 -0
  49. package/lib/typescript/flags/configuration/context.d.ts.map +1 -0
  50. package/lib/typescript/flags/configuration/index.d.ts +5 -0
  51. package/lib/typescript/flags/configuration/index.d.ts.map +1 -0
  52. package/lib/typescript/flags/configuration/precomputed.d.ts +25 -0
  53. package/lib/typescript/flags/configuration/precomputed.d.ts.map +1 -0
  54. package/lib/typescript/flags/configuration/types.d.ts +24 -0
  55. package/lib/typescript/flags/configuration/types.d.ts.map +1 -0
  56. package/lib/typescript/flags/configuration/wire.d.ts +2 -0
  57. package/lib/typescript/flags/configuration/wire.d.ts.map +1 -0
  58. package/lib/typescript/flags/internal.d.ts.map +1 -1
  59. package/lib/typescript/flags/types.d.ts +1 -1
  60. package/lib/typescript/flags/types.d.ts.map +1 -1
  61. package/lib/typescript/index.d.ts +4 -2
  62. package/lib/typescript/index.d.ts.map +1 -1
  63. package/lib/typescript/version.d.ts +1 -1
  64. package/package.json +3 -2
  65. package/src/flags/FlagsClient.ts +305 -3
  66. package/src/flags/__tests__/FlagsClient.test.ts +596 -0
  67. package/src/flags/__tests__/internal.test.ts +45 -0
  68. package/src/flags/configuration/__tests__/context.test.ts +120 -0
  69. package/src/flags/configuration/__tests__/precomputed.test.ts +301 -0
  70. package/src/flags/configuration/__tests__/wire.test.ts +127 -0
  71. package/src/flags/configuration/context.ts +76 -0
  72. package/src/flags/configuration/index.ts +27 -0
  73. package/src/flags/configuration/precomputed.ts +215 -0
  74. package/src/flags/configuration/types.ts +47 -0
  75. package/src/flags/configuration/wire.ts +15 -0
  76. package/src/flags/internal.ts +6 -3
  77. package/src/flags/types.ts +3 -1
  78. package/src/index.tsx +8 -0
  79. package/src/version.ts +1 -1
@@ -8,10 +8,61 @@ import { InternalLog } from '../InternalLog';
8
8
  import { SdkVerbosity } from '../config/types/SdkVerbosity';
9
9
  import type { DdNativeFlagsType } from '../nativeModulesTypes';
10
10
 
11
+ // Imported directly (not via the module index): context matching is an internal helper,
12
+ // used here only to detect a runtime context an offline precomputed configuration cannot honor.
13
+ import { contextMatchesConfiguration } from './configuration/context';
14
+ import { decodePrecomputedFlags, normalizeWireContext } from './configuration';
15
+ import type {
16
+ ParsedFlagsConfiguration,
17
+ ParsedPrecomputedConfiguration
18
+ } from './configuration';
11
19
  import { processEvaluationContext } from './internal';
12
20
  import type { FlagCacheEntry } from './internal';
13
21
  import type { JsonValue, EvaluationContext, FlagDetails } from './types';
14
22
 
23
+ /**
24
+ * Error codes an offline configuration result can carry:
25
+ * - `INVALID_CONTEXT`: the active context does not match the precomputed snapshot.
26
+ * - `PROVIDER_NOT_READY`: an offline operation ran with no configuration loaded.
27
+ * - `GENERAL`: the loaded configuration is unusable (malformed/unsupported/undecodable).
28
+ */
29
+ export type ConfigurationErrorCode =
30
+ | 'INVALID_CONTEXT'
31
+ | 'PROVIDER_NOT_READY'
32
+ | 'GENERAL';
33
+
34
+ /**
35
+ * Outcome of loading a configuration or reconciling it against the active evaluation context,
36
+ * returned by the offline APIs ({@link FlagsClient.setConfiguration},
37
+ * {@link FlagsClient.setEvaluationContextWithoutFetching},
38
+ * {@link FlagsClient.resetEvaluationContextWithoutFetching}).
39
+ *
40
+ * `'ready'` means the configuration can be served against the active context; `'error'` carries
41
+ * the precise reason so the OpenFeature provider surfaces the correct code and evaluation returns
42
+ * that code with the coded default.
43
+ *
44
+ * @internal Consumers observe OpenFeature provider events/evaluation details, not this result.
45
+ */
46
+ export type ConfigurationResult =
47
+ | { status: 'ready' }
48
+ | { status: 'error'; errorCode: ConfigurationErrorCode };
49
+
50
+ /**
51
+ * The decoded outcome of the last loaded offline configuration. Load validity (`kind`) is stored
52
+ * separately from context compatibility so that later context changes reconcile against a decoded
53
+ * snapshot **without re-decoding** and can never promote an invalid load to a servable state.
54
+ *
55
+ * `'none'` = no offline configuration engaged (the online/fetch path, or nothing loaded yet).
56
+ */
57
+ type LoadedConfigurationState =
58
+ | { kind: 'none' }
59
+ | { kind: 'invalid'; errorCode: ConfigurationErrorCode }
60
+ | {
61
+ kind: 'precomputed';
62
+ configuration: ParsedPrecomputedConfiguration;
63
+ flags: Map<string, FlagCacheEntry>;
64
+ };
65
+
15
66
  export class FlagsClient {
16
67
  // eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
17
68
  private nativeFlags: DdNativeFlagsType = require('../specs/NativeDdFlags')
@@ -19,9 +70,34 @@ export class FlagsClient {
19
70
 
20
71
  private clientName: string;
21
72
 
73
+ // The context the app explicitly set — the online fetch context, or the offline override via
74
+ // {@link setEvaluationContextWithoutFetching}. `undefined` means "no external override": an
75
+ // offline precomputed configuration is then served against its own embedded context. Tracked
76
+ // separately from {@link evaluationContext} so that adopting a configuration's embedded context
77
+ // is never mistaken for an app-set override (which would spuriously fail a later replacement).
78
+ private externalContext: EvaluationContext | undefined = undefined;
79
+
80
+ // The effective context evaluation and exposure tracking run against: the external override
81
+ // when set, otherwise the loaded configuration's embedded context.
22
82
  private evaluationContext: EvaluationContext | undefined = undefined;
23
83
 
24
- private flagsCache: Record<string, FlagCacheEntry> = {};
84
+ // The servable flag cache. On the online path it holds the native-fetched flags; on the
85
+ // offline path it mirrors the decoded snapshot when the configuration is servable. A Map
86
+ // (not a plain object) so a flag keyed like an inherited property ("toString",
87
+ // "__proto__") is looked up as data via `.get()` and never resolves an `Object.prototype`
88
+ // member — important now the cache can be fed from untrusted wire data.
89
+ private flagsCache: Map<string, FlagCacheEntry> = new Map();
90
+
91
+ // The decoded outcome of the last loaded offline configuration (see the type).
92
+ private loadedConfiguration: LoadedConfigurationState = { kind: 'none' };
93
+
94
+ // Internal serving status. `'none'` = online path (serve `flagsCache`); `'ready'` = serve
95
+ // the offline snapshot; `'error'` = serve coded defaults with `configurationError`.
96
+ private configurationStatus: 'none' | 'ready' | 'error' = 'none';
97
+
98
+ private configurationError:
99
+ | { errorCode: ConfigurationErrorCode; errorMessage: string }
100
+ | undefined = undefined;
25
101
 
26
102
  constructor(clientName: string = 'default') {
27
103
  this.clientName = clientName;
@@ -56,6 +132,24 @@ export class FlagsClient {
56
132
  // Make sure to process the incoming context because we don't support nested object values in context.
57
133
  const processedContext = processEvaluationContext(context);
58
134
 
135
+ // Entering online mode drops any offline overlay *before* fetching, so a failed fetch falls
136
+ // back to coded defaults rather than continuing to serve a stale offline snapshot. Using one
137
+ // client for both online and offline is unsupported (give the offline provider its own
138
+ // `clientName`), so warn when an offline configuration is discarded here. Online-only clients
139
+ // have no overlay, so this does not touch their keep-last-known-flags-on-failure behavior.
140
+ if (this.loadedConfiguration.kind !== 'none') {
141
+ InternalLog.log(
142
+ `An offline configuration was loaded for '${this.clientName}' but an online fetch was requested; discarding it and serving default values on failure. Use a separate client for the offline provider.`,
143
+ SdkVerbosity.WARN
144
+ );
145
+ this.loadedConfiguration = { kind: 'none' };
146
+ this.configurationStatus = 'none';
147
+ this.configurationError = undefined;
148
+ this.flagsCache = new Map();
149
+ this.evaluationContext = undefined;
150
+ this.externalContext = undefined;
151
+ }
152
+
59
153
  try {
60
154
  const result = await this.nativeFlags.setEvaluationContext(
61
155
  this.clientName,
@@ -63,9 +157,19 @@ export class FlagsClient {
63
157
  processedContext.attributes ?? {}
64
158
  );
65
159
 
160
+ this.externalContext = processedContext;
66
161
  this.evaluationContext = processedContext;
67
- this.flagsCache = result;
162
+ this.flagsCache = new Map(Object.entries(result));
163
+
164
+ // A successful online fetch is authoritative: reset to the clean online state so a
165
+ // prior offline error status (e.g. PROVIDER_NOT_READY from an offline op with no
166
+ // configuration loaded) can't keep serving coded defaults over the fetched flags.
167
+ this.loadedConfiguration = { kind: 'none' };
168
+ this.configurationStatus = 'none';
169
+ this.configurationError = undefined;
68
170
  } catch (error) {
171
+ // A failed fetch leaves the previous online cache in place (keep-last-known); any offline
172
+ // overlay was already dropped above, so no stale offline snapshot is served.
69
173
  if (error instanceof Error) {
70
174
  InternalLog.log(
71
175
  `Error setting flag evaluation context: ${error.message}`,
@@ -77,6 +181,191 @@ export class FlagsClient {
77
181
  }
78
182
  };
79
183
 
184
+ /**
185
+ * Set the evaluation context **without** fetching a configuration from the network, then
186
+ * reconcile the loaded configuration against it.
187
+ *
188
+ * The offline counterpart to {@link setEvaluationContext}: records the active context and
189
+ * reconciles with no native request. A precomputed configuration is single-subject, so a
190
+ * context that does not match the one it was computed for reconciles to an error
191
+ * (`INVALID_CONTEXT`) and evaluation serves defaults. With no configuration loaded the
192
+ * result is `PROVIDER_NOT_READY`. Intended for offline providers that own their
193
+ * configuration via `setConfiguration` and must not fetch on a context change.
194
+ *
195
+ * @param context The evaluation context to associate with the current client.
196
+ */
197
+ setEvaluationContextWithoutFetching = (
198
+ context: EvaluationContext
199
+ ): ConfigurationResult => {
200
+ this.externalContext = processEvaluationContext(context);
201
+
202
+ return this.reconcile();
203
+ };
204
+
205
+ /**
206
+ * Clear any externally-set evaluation context and reconcile.
207
+ *
208
+ * This is the offline counterpart to clearing/omitting an OpenFeature context: it drops the
209
+ * external override so a loaded precomputed configuration is served against **its embedded
210
+ * context** again. Clearing the override (rather than skipping) matters so that a
211
+ * configuration loaded *after* a clear is not judged against a stale override. With no
212
+ * configuration loaded the result is `PROVIDER_NOT_READY`.
213
+ */
214
+ resetEvaluationContextWithoutFetching = (): ConfigurationResult => {
215
+ this.externalContext = undefined;
216
+
217
+ return this.reconcile();
218
+ };
219
+
220
+ /**
221
+ * Load a configuration (parsed from a `ConfigurationWire` string via
222
+ * `configurationFromString`) into the client for offline evaluation, then reconcile it
223
+ * against the active context.
224
+ *
225
+ * For a precomputed configuration this decodes the snapshot once and adopts its embedded
226
+ * evaluation context when none is set — **no network request is made**. An unusable
227
+ * configuration reconciles to an error (`GENERAL`); a context mismatch to `INVALID_CONTEXT`.
228
+ *
229
+ * @param configuration The configuration to load.
230
+ *
231
+ * @example
232
+ * ```ts
233
+ * const configuration = configurationFromString(wire);
234
+ * flagsClient.setConfiguration(configuration);
235
+ *
236
+ * const value = flagsClient.getBooleanValue('new-feature', false);
237
+ * ```
238
+ */
239
+ setConfiguration = (
240
+ configuration: ParsedFlagsConfiguration
241
+ ): ConfigurationResult => {
242
+ this.loadedConfiguration = this.loadConfiguration(configuration);
243
+
244
+ return this.reconcile();
245
+ };
246
+
247
+ /**
248
+ * Decode a supplied configuration into a {@link LoadedConfigurationState} **once**, capturing
249
+ * whether the load itself is valid (independent of the active context). Later context changes
250
+ * reconcile against this stored state without re-decoding, and can never turn an invalid load
251
+ * into a servable one.
252
+ *
253
+ * FORWARD-COMPAT SEAM: when a rules-based configuration is supported, it must be handled here
254
+ * BEFORE the precomputed guard — rules are context-agnostic and must NOT be classified invalid.
255
+ */
256
+ private loadConfiguration = (
257
+ configuration: ParsedFlagsConfiguration
258
+ ): LoadedConfigurationState => {
259
+ const precomputed = configuration?.precomputed;
260
+
261
+ // An empty configuration (a failed/lenient wire parse, or a wire with no precomputed
262
+ // branch) is unusable. `configurationFromString` collapses malformed input and
263
+ // unsupported versions to the same empty shape, so this is classified as `GENERAL`.
264
+ if (!precomputed) {
265
+ InternalLog.log(
266
+ `No usable precomputed configuration was provided for '${this.clientName}'.`,
267
+ SdkVerbosity.WARN
268
+ );
269
+ return { kind: 'invalid', errorCode: 'GENERAL' };
270
+ }
271
+
272
+ try {
273
+ const flags = decodePrecomputedFlags(precomputed.response);
274
+
275
+ return { kind: 'precomputed', configuration: precomputed, flags };
276
+ } catch (error) {
277
+ // Decoding rejects unsupported payloads (e.g. obfuscated) — an unsupported kind,
278
+ // classified as `GENERAL`.
279
+ if (error instanceof Error) {
280
+ InternalLog.log(
281
+ `Unsupported flags configuration for '${this.clientName}': ${error.message}`,
282
+ SdkVerbosity.WARN
283
+ );
284
+ }
285
+ return { kind: 'invalid', errorCode: 'GENERAL' };
286
+ }
287
+ };
288
+
289
+ /**
290
+ * Reconcile the stored {@link LoadedConfigurationState} against the active evaluation context
291
+ * and (re)compute the servable flag cache and configuration status/result.
292
+ *
293
+ * The stored load validity is consulted **before** context compatibility, so a context change
294
+ * can never promote an invalid (or absent) load to `ready`.
295
+ */
296
+ private reconcile = (): ConfigurationResult => {
297
+ const loaded = this.loadedConfiguration;
298
+
299
+ // No offline configuration engaged: an offline operation with nothing loaded is not ready.
300
+ if (loaded.kind === 'none') {
301
+ return this.enterError(
302
+ 'PROVIDER_NOT_READY',
303
+ `The evaluation context is not usable for '${this.clientName}': no configuration is loaded. Provide a configuration via setConfiguration.`
304
+ );
305
+ }
306
+
307
+ // The load itself failed (malformed/unsupported/undecodable) — independent of context.
308
+ if (loaded.kind === 'invalid') {
309
+ return this.enterError(
310
+ loaded.errorCode,
311
+ `The loaded configuration for '${this.clientName}' is not usable. Provide a valid precomputed configuration.`
312
+ );
313
+ }
314
+
315
+ const { configuration, flags } = loaded;
316
+
317
+ // A precomputed snapshot is bound to the subject it was computed for. If the app set an
318
+ // *external* context that does not match, it cannot be served (offline never fetches), so
319
+ // it is an error and evaluation serves coded defaults. Only an external override is checked
320
+ // here — the configuration's own embedded context (adopted below when no override is set)
321
+ // matches by construction, so replacing one snapshot with another for a different subject
322
+ // stays `ready`. The decoded snapshot is retained for a later matching context.
323
+ if (
324
+ this.externalContext &&
325
+ !contextMatchesConfiguration(
326
+ configuration.context,
327
+ this.externalContext
328
+ )
329
+ ) {
330
+ return this.enterError(
331
+ 'INVALID_CONTEXT',
332
+ `The evaluation context does not match the precomputed configuration for '${this.clientName}'. Serving default values. Set a matching context, or use a rules-based configuration for per-context evaluation.`
333
+ );
334
+ }
335
+
336
+ // Serve against the external override when set, otherwise the configuration's embedded
337
+ // context (a context-agnostic configuration falls back to an empty context).
338
+ this.evaluationContext =
339
+ this.externalContext ?? this.embeddedContext(configuration);
340
+ this.flagsCache = flags;
341
+ this.configurationStatus = 'ready';
342
+ this.configurationError = undefined;
343
+
344
+ return { status: 'ready' };
345
+ };
346
+
347
+ /** The evaluation context a precomputed configuration was computed for (empty if agnostic). */
348
+ private embeddedContext = (
349
+ configuration: ParsedPrecomputedConfiguration
350
+ ): EvaluationContext => {
351
+ return configuration.context
352
+ ? normalizeWireContext(configuration.context)
353
+ : { targetingKey: '', attributes: {} };
354
+ };
355
+
356
+ /** Record an error status + message, clear the servable cache, and return the result. */
357
+ private enterError = (
358
+ errorCode: ConfigurationErrorCode,
359
+ errorMessage: string
360
+ ): ConfigurationResult => {
361
+ this.flagsCache = new Map();
362
+ this.configurationStatus = 'error';
363
+ this.configurationError = { errorCode, errorMessage };
364
+ InternalLog.log(errorMessage, SdkVerbosity.WARN);
365
+
366
+ return { status: 'error', errorCode };
367
+ };
368
+
80
369
  private track = (flag: FlagCacheEntry, context: EvaluationContext) => {
81
370
  // A non-blocking call; don't await this.
82
371
  this.nativeFlags
@@ -102,6 +391,19 @@ export class FlagsClient {
102
391
  defaultValue: T,
103
392
  type: 'boolean' | 'string' | 'number' | 'object'
104
393
  ): FlagDetails<T> => {
394
+ // An offline configuration that cannot be served against the active context surfaces the
395
+ // precise error code (INVALID_CONTEXT / GENERAL / PROVIDER_NOT_READY) with the coded
396
+ // default. The OpenFeature provider maps this to a PROVIDER_ERROR / ERROR state.
397
+ if (this.configurationStatus === 'error' && this.configurationError) {
398
+ return {
399
+ key,
400
+ value: defaultValue,
401
+ reason: 'ERROR',
402
+ errorCode: this.configurationError.errorCode,
403
+ errorMessage: this.configurationError.errorMessage
404
+ };
405
+ }
406
+
105
407
  if (!this.evaluationContext) {
106
408
  return {
107
409
  key,
@@ -113,7 +415,7 @@ export class FlagsClient {
113
415
  }
114
416
 
115
417
  // Retrieve the flag from the cache.
116
- const flag = this.flagsCache[key];
418
+ const flag = this.flagsCache.get(key);
117
419
 
118
420
  if (!flag) {
119
421
  return {