@openfeature/flagd-provider 0.13.3 → 0.13.4

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright OpenFeature Maintainers
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -28,17 +28,26 @@ Options can be defined in the constructor or as environment variables. Construct
 ### Available Configuration Options
 
 | Option name                            | Environment variable name      | Type    | Default                                                        | Supported values |
-| -------------------------------------- | ------------------------------ | ------- |----------------------------------------------------------------| ---------------- |
+| -------------------------------------- | ------------------------------ | ------- |----------------------------------------------------------------|------------------|
 | host                                   | FLAGD_HOST                     | string  | localhost                                                      |                  |
 | port                                   | FLAGD_PORT                     | number  | [resolver specific defaults](#resolver-type-specific-defaults) |                  |
 | tls                                    | FLAGD_TLS                      | boolean | false                                                          |                  |
 | socketPath                             | FLAGD_SOCKET_PATH              | string  | -                                                              |                  |
+| certPath                               | FLAGD_SERVER_CERT_PATH         | string  | -                                                              |                  |
 | resolverType                           | FLAGD_RESOLVER                 | string  | rpc                                                            | rpc, in-process  |
 | offlineFlagSourcePath                  | FLAGD_OFFLINE_FLAG_SOURCE_PATH | string  | -                                                              |                  |
-| selector                               | FLAGD_SOURCE_SELECTOR          | string  | -                                                              |                  |
+| selector                               | FLAGD_SOURCE_SELECTOR          | string  | -                                                              | rpc & in-process (see [Selector](#selector))  |
 | cache                                  | FLAGD_CACHE                    | string  | lru                                                            | lru, disabled    |
 | maxCacheSize                           | FLAGD_MAX_CACHE_SIZE           | int     | 1000                                                           |                  |
 | defaultAuthority                       | FLAGD_DEFAULT_AUTHORITY        | string  | -                                                              | rpc, in-process  |
+| keepAliveTime                          | FLAGD_KEEP_ALIVE_TIME_MS       | number  | 0                                                              | rpc, in-process  |
+| retryBackoffMs                         | FLAGD_RETRY_BACKOFF_MS         | int     | 1000                                                           | in-process       |
+| retryBackoffMaxMs                      | FLAGD_RETRY_BACKOFF_MAX_MS     | int     | 120000                                                         | in-process       |
+| retryGracePeriod                       | FLAGD_RETRY_GRACE_PERIOD       | int     | 5                                                              |                  |
+| fatalStatusCodes                       | FLAGD_FATAL_STATUS_CODES       | string[]| -                                                              |                  |
+
+> [!NOTE]
+> The `selector` option automatically uses the `flagd-selector` header (the preferred approach per [flagd#1814](https://github.com/open-feature/flagd/issues/1814)) while maintaining backward compatibility with older flagd versions. See [Selector](#selector) for details.
 
 #### Resolver type-specific Defaults
 
@@ -94,6 +103,46 @@ To enable this mode, you should provide a valid flag configuration file with the
 Offline mode uses `fs.watchFile` and polls every 5 seconds for changes to the file.
 This mode is useful for local development, test cases, and for offline applications.
 
+### Selector
+
+The `selector` option allows filtering flag configurations and evaluations based on flag sets or sources. This is useful when multiple flag configurations are available and you want to target a specific subset.
+
+**RPC mode:**
+```ts
+  OpenFeature.setProvider(new FlagdProvider({
+      selector: 'flagSetId=payment-flags',
+  }))
+```
+
+**In-process mode:**
+```ts
+  OpenFeature.setProvider(new FlagdProvider({
+      resolverType: 'in-process',
+      selector: 'flagSetId=app-flags',
+  }))
+```
+
+Or via environment variable:
+
+```bash
+export FLAGD_SOURCE_SELECTOR="flagSetId=app-flags"
+```
+
+> [!IMPORTANT]
+> **Selector normalization ([flagd#1814](https://github.com/open-feature/flagd/issues/1814))**
+>
+> As part of [flagd#1814](https://github.com/open-feature/flagd/issues/1814), the flagd project is normalizing selector handling across all services (sync, evaluation, and OFREP) to use the `flagd-selector` gRPC metadata header.
+>
+> **Current implementation:**
+> - The JS SDK **automatically passes the selector via the `flagd-selector` header** for both RPC and in-process modes
+> - For in-process mode backward compatibility with older flagd versions, the selector is **also sent in the request body**
+> - Both methods work with current flagd versions
+> - In a future major version of flagd, the request body selector field may be removed
+>
+> **No migration needed:**
+>
+> Users do not need to make any code changes. The SDK handles selector normalization automatically.
+
 ### Default Authority usage (optional)
 
 This is useful for complex routing or service-discovery use cases that involve a proxy (e.g., Envoy).
@@ -106,6 +155,40 @@ Please refer to this [GitHub issue](https://github.com/open-feature/js-sdk-contr
   }))
 ```
 
+### Keepalive Configuration (optional)
+
+gRPC keepalive prevents idle connections from being closed.
+This option only applies to RPC and in-process resolvers (streaming connections).
+Set to `0` to disable keepalive (default).
+
+```ts
+  OpenFeature.setProvider(new FlagdProvider({
+      resolverType: 'in-process',
+      keepAliveTime: 30000, // Send keepalive ping every 30 seconds
+  }))
+```
+
+### Retry Grace Period (optional)
+
+The `retryGracePeriod` controls how long (in seconds) the provider will retry reconnecting before transitioning from `STALE` to `ERROR` state:
+
+```ts
+  OpenFeature.setProvider(new FlagdProvider({
+      retryGracePeriod: 5, // Retry for 5 seconds before moving to ERROR state
+  }))
+```
+
+### Fatal Status Codes (optional)
+
+Configure which gRPC status codes should be treated as fatal errors on the first connection attempt.
+When a fatal status code is encountered during initial connection, the provider will not retry and will emit a `PROVIDER_FATAL` error.
+
+```ts
+OpenFeature.setProvider(new FlagdProvider({
+  fatalStatusCodes: ['UNAUTHENTICATED', 'PERMISSION_DENIED']
+}))
+```
+
 ### Supported Events
 
 The flagd provider emits `PROVIDER_READY`, `PROVIDER_ERROR` and `PROVIDER_CONFIGURATION_CHANGED` events.