@openfeature/flagd-provider 0.10.3 → 0.10.5

package/README.md

@@ -1,7 +1,6 @@
 # Server-Side flagd Provider
 
-Flagd is a simple daemon for evaluating feature flags.
-It is designed to conform to OpenFeature schema for flag definitions.
+This provider is designed to use flagd's [evaluation protocol](https://github.com/open-feature/schemas/blob/main/protobuf/schema/v1/schema.proto), or locally evaluate flags defined in a flagd [flag definition](https://github.com/open-feature/schemas/blob/main/json/flagd-definitions.json).
 This repository and package provides the client code for interacting with it via the OpenFeature server-side JavaScript SDK.
 
 ## Installation
@@ -35,8 +34,9 @@ Options can be defined in the constructor or as environment variables. Construct
 | tls                                    | FLAGD_TLS                      | boolean | false     |                  |
 | socketPath                             | FLAGD_SOCKET_PATH              | string  | -         |                  |
 | resolverType                           | FLAGD_SOURCE_RESOLVER          | string  | rpc       | rpc, in-process  |
+| offlineFlagSourcePath                  | FLAGD_OFFLINE_FLAG_SOURCE_PATH | string  | -         |                  |
 | selector                               | FLAGD_SOURCE_SELECTOR          | string  | -         |                  |
-| cache                                  | FLAGD_CACHE                    | string  | lru       | lru,disabled     |
+| cache                                  | FLAGD_CACHE                    | string  | lru       | lru, disabled    |
 | maxCacheSize                           | FLAGD_MAX_CACHE_SIZE           | int     | 1000      |                  |
 
 Below are examples of usage patterns.
@@ -45,7 +45,7 @@ Below are examples of usage patterns.
 
 This is the default mode of operation of the provider.
 In this mode, FlagdProvider communicates with flagd via the gRPC protocol.
-Flag evaluations take place remotely at the connected [flagd](https://flagd.dev/) instance.
+Flag evaluations take place remotely on the connected [flagd](https://flagd.dev/) instance.
 
 ```ts
   OpenFeature.setProvider(new FlagdProvider())
@@ -74,6 +74,19 @@ Flag configurations for evaluation are obtained via gRPC protocol using [sync pr
 
 In the above example, the provider expects a flag sync service implementation to be available at `localhost:8013` (default host and port).
 
+In-process resolver can also work in an offline mode.
+To enable this mode, you should provide a valid flag configuration file with the option `offlineFlagSourcePath`.
+
+```
+  OpenFeature.setProvider(new FlagdProvider({
+      resolverType: 'in-process',
+      offlineFlagSourcePath: './flags.json',
+  }))
+```
+
+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.
+
 ### Supported Events
 
 The flagd provider emits `PROVIDER_READY`, `PROVIDER_ERROR` and `PROVIDER_CONFIGURATION_CHANGED` events.

package/index.cjs.js

@@ -8,6 +8,8 @@ var connectivityState = require('@grpc/grpc-js/build/src/connectivity-state');
 var lruCache = require('lru-cache');
 var util$6 = require('util');
 var flagdCore = require('@openfeature/flagd-core');
+var core = require('@openfeature/core');
+var fs = require('fs');
 
 const EVENT_CONFIGURATION_CHANGE = 'configuration_change';
 const EVENT_PROVIDER_READY = 'provider_ready';
@@ -32,10 +34,11 @@ var ENV_VAR;
     ENV_VAR["FLAGD_MAX_CACHE_SIZE"] = "FLAGD_MAX_CACHE_SIZE";
     ENV_VAR["FLAGD_SOURCE_SELECTOR"] = "FLAGD_SOURCE_SELECTOR";
     ENV_VAR["FLAGD_RESOLVER"] = "FLAGD_RESOLVER";
+    ENV_VAR["FLAGD_OFFLINE_FLAG_SOURCE_PATH"] = "FLAGD_OFFLINE_FLAG_SOURCE_PATH";
 })(ENV_VAR || (ENV_VAR = {}));
 const getEnvVarConfig = () => {
     var _a;
-    return (Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (process.env[ENV_VAR.FLAGD_HOST] && {
+    return (Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (process.env[ENV_VAR.FLAGD_HOST] && {
         host: process.env[ENV_VAR.FLAGD_HOST],
     })), (Number(process.env[ENV_VAR.FLAGD_PORT]) && {
         port: Number(process.env[ENV_VAR.FLAGD_PORT]),
@@ -51,6 +54,8 @@ const getEnvVarConfig = () => {
         selector: process.env[ENV_VAR.FLAGD_SOURCE_SELECTOR],
     })), ((process.env[ENV_VAR.FLAGD_RESOLVER] === 'rpc' || process.env[ENV_VAR.FLAGD_RESOLVER] === 'in-process') && {
         resolverType: process.env[ENV_VAR.FLAGD_RESOLVER],
+    })), (process.env[ENV_VAR.FLAGD_OFFLINE_FLAG_SOURCE_PATH] && {
+        offlineFlagSourcePath: process.env[ENV_VAR.FLAGD_OFFLINE_FLAG_SOURCE_PATH],
     })));
 };
 function getConfig(options = {}) {
@@ -5942,13 +5947,15 @@ class GRPCService {
             if (data && typeof data === 'object' && 'flags' in data && (data === null || data === void 0 ? void 0 : data['flags'])) {
                 const flagChangeMessage = data;
                 const flagsChanged = Object.keys(flagChangeMessage.flags || []);
-                // remove each changed key from cache
-                flagsChanged.forEach((key) => {
-                    var _a, _b;
-                    if ((_a = this._cache) === null || _a === void 0 ? void 0 : _a.delete(key)) {
-                        (_b = this.logger) === null || _b === void 0 ? void 0 : _b.debug(`${FlagdProvider.name}: evicted key: ${key} from cache.`);
-                    }
-                });
+                if (this._cacheEnabled) {
+                    // remove each changed key from cache
+                    flagsChanged.forEach((key) => {
+                        var _a, _b;
+                        if ((_a = this._cache) === null || _a === void 0 ? void 0 : _a.delete(key)) {
+                            (_b = this.logger) === null || _b === void 0 ? void 0 : _b.debug(`${FlagdProvider.name}: evicted key: ${key} from cache.`);
+                        }
+                    });
+                }
                 changedCallback(flagsChanged);
             }
         }
@@ -5961,7 +5968,7 @@ class GRPCService {
     }
     handleError(reconnectCallback, changedCallback, disconnectCallback) {
         var _a, _b;
-        disconnectCallback();
+        disconnectCallback('streaming connection error, will attempt reconnect...');
         (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`${FlagdProvider.name}: streaming connection error, will attempt reconnect...`);
         (_b = this._cache) === null || _b === void 0 ? void 0 : _b.clear();
         this.reconnect(reconnectCallback, changedCallback, disconnectCallback);
@@ -6356,6 +6363,18 @@ function isSet(value) {
  */
 class GrpcFetch {
     constructor(config, syncServiceClient, logger) {
+        /**
+         * Initialized will be set to true once the initial connection is successful
+         * and the first payload has been received. Subsequent reconnects will not
+         * change the initialized value.
+         */
+        this._initialized = false;
+        /**
+         * Is connected represents the current known connection state. It will be
+         * set to true once the first payload has been received.but will be set to
+         * false if the connection is lost.
+         */
+        this._isConnected = false;
         const { host, port, tls, socketPath, selector } = config;
         this._syncClient = syncServiceClient
             ? syncServiceClient
@@ -6363,55 +6382,131 @@ class GrpcFetch {
         this._logger = logger;
         this._request = { providerId: '', selector: selector ? selector : '' };
     }
-    connect(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback) {
-        return new Promise((resolve, reject) => this.listen(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback, resolve, reject));
+    connect(dataCallback, reconnectCallback, changedCallback, disconnectCallback) {
+        return new Promise((resolve, reject) => this.listen(dataCallback, reconnectCallback, changedCallback, disconnectCallback, resolve, reject)).then(() => {
+            this._initialized = true;
+        });
     }
     disconnect() {
         var _a;
-        (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Disconnecting gRPC sync connection');
-        closeStreamIfDefined(this._syncStream);
-        this._syncClient.close();
+        return __awaiter(this, void 0, void 0, function* () {
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Disconnecting gRPC sync connection');
+            closeStreamIfDefined(this._syncStream);
+            this._syncClient.close();
+        });
     }
-    listen(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback, resolveConnect, rejectConnect) {
+    listen(dataCallback, reconnectCallback, changedCallback, disconnectCallback, resolveConnect, rejectConnect) {
+        var _a;
+        (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Starting gRPC sync connection');
         closeStreamIfDefined(this._syncStream);
         this._syncStream = this._syncClient.syncFlags(this._request);
         this._syncStream.on('data', (data) => {
-            var _a;
-            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Received sync payload');
-            dataFillCallback(data.flagConfiguration);
-            changedCallback([]); // flags changed list not supported
-            // if resolveConnect is undefined, this is a reconnection; we only want to fire the reconnect callback in that case
+            var _a, _b, _c, _d;
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug(`Received sync payload`);
+            try {
+                const changes = dataCallback(data.flagConfiguration);
+                if (this._initialized && changes.length > 0) {
+                    changedCallback(changes);
+                }
+            }
+            catch (err) {
+                (_b = this._logger) === null || _b === void 0 ? void 0 : _b.debug('Error processing sync payload: ', (_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : 'unknown error');
+            }
             if (resolveConnect) {
                 resolveConnect();
             }
-            else {
+            else if (!this._isConnected) {
+                // Not the first connection and there's no active connection.
+                (_d = this._logger) === null || _d === void 0 ? void 0 : _d.debug('Reconnected to gRPC sync');
                 reconnectCallback();
             }
+            this._isConnected = true;
         });
         this._syncStream.on('error', (err) => {
-            var _a;
-            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.error('Connection error, attempting to reconnect', err);
-            disconnectCallback();
-            rejectConnect === null || rejectConnect === void 0 ? void 0 : rejectConnect(new serverSdk.GeneralError('Failed to connect stream'));
-            this.reconnect(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback);
+            var _a, _b, _c;
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.error('Connection error, attempting to reconnect');
+            (_b = this._logger) === null || _b === void 0 ? void 0 : _b.debug(err);
+            this._isConnected = false;
+            const errorMessage = (_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : 'Failed to connect to syncFlags stream';
+            disconnectCallback(errorMessage);
+            rejectConnect === null || rejectConnect === void 0 ? void 0 : rejectConnect(new serverSdk.GeneralError(errorMessage));
+            this.reconnect(dataCallback, reconnectCallback, changedCallback, disconnectCallback);
         });
     }
-    reconnect(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback) {
+    reconnect(dataCallback, reconnectCallback, changedCallback, disconnectCallback) {
         const channel = this._syncClient.getChannel();
         channel.watchConnectivityState(channel.getConnectivityState(true), Infinity, () => {
-            this.listen(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback);
+            this.listen(dataCallback, reconnectCallback, changedCallback, disconnectCallback);
+        });
+    }
+}
+
+const encoding = 'utf8';
+class FileFetch {
+    constructor(filename, logger) {
+        this._filename = filename;
+        this._logger = logger;
+    }
+    connect(dataFillCallback, _, changedCallback) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Starting file sync connection');
+            try {
+                const output = yield fs.promises.readFile(this._filename, encoding);
+                // Don't emit the change event for the initial read
+                dataFillCallback(output);
+                // Using watchFile instead of watch to support virtualized host file systems.
+                fs.watchFile(this._filename, () => __awaiter(this, void 0, void 0, function* () {
+                    var _c;
+                    try {
+                        const data = yield fs.promises.readFile(this._filename, encoding);
+                        const changes = dataFillCallback(data);
+                        if (changes.length > 0) {
+                            changedCallback(changes);
+                        }
+                    }
+                    catch (err) {
+                        (_c = this._logger) === null || _c === void 0 ? void 0 : _c.error(`Error reading file: ${err}`);
+                    }
+                }));
+            }
+            catch (err) {
+                if (err instanceof core.OpenFeatureError) {
+                    throw err;
+                }
+                else {
+                    switch (err === null || err === void 0 ? void 0 : err.code) {
+                        case 'ENOENT':
+                            throw new core.GeneralError(`File not found: ${this._filename}`);
+                        case 'EACCES':
+                            throw new core.GeneralError(`File not accessible: ${this._filename}`);
+                        default:
+                            (_b = this._logger) === null || _b === void 0 ? void 0 : _b.debug(`Error reading file: ${err}`);
+                            throw new core.GeneralError();
+                    }
+                }
+            }
+        });
+    }
+    disconnect() {
+        return __awaiter(this, void 0, void 0, function* () {
+            fs.unwatchFile(this._filename);
         });
     }
 }
 
 class InProcessService {
     constructor(config, dataFetcher, logger) {
-        this.logger = logger;
+        this.config = config;
         this._flagdCore = new flagdCore.FlagdCore(undefined, logger);
-        this._dataFetcher = dataFetcher ? dataFetcher : new GrpcFetch(config, undefined, logger);
+        this._dataFetcher = dataFetcher
+            ? dataFetcher
+            : config.offlineFlagSourcePath
+                ? new FileFetch(config.offlineFlagSourcePath, logger)
+                : new GrpcFetch(config, undefined, logger);
     }
     connect(reconnectCallback, changedCallback, disconnectCallback) {
-        return this._dataFetcher.connect(this.fill.bind(this), reconnectCallback, changedCallback, disconnectCallback);
+        return this._dataFetcher.connect(this.setFlagConfiguration.bind(this), reconnectCallback, changedCallback, disconnectCallback);
     }
     disconnect() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -6419,25 +6514,43 @@ class InProcessService {
         });
     }
     resolveBoolean(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveBooleanEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('boolean', flagKey, defaultValue, context, logger);
+        });
     }
     resolveNumber(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveNumberEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('number', flagKey, defaultValue, context, logger);
+        });
     }
     resolveString(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveStringEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('string', flagKey, defaultValue, context, logger);
+        });
     }
     resolveObject(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveObjectEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('object', flagKey, defaultValue, context, logger);
+        });
     }
-    fill(flags) {
-        var _a;
-        try {
-            this._flagdCore.setConfigurations(flags);
-        }
-        catch (err) {
-            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(err);
-        }
+    evaluate(type, flagKey, defaultValue, context, logger) {
+        const details = this._flagdCore.resolve(type, flagKey, defaultValue, context, logger);
+        return Object.assign(Object.assign({}, details), { flagMetadata: this.addFlagMetadata() });
+    }
+    /**
+     * Adds the flag metadata to the resolution details
+     */
+    addFlagMetadata() {
+        return Object.assign({}, (this.config.selector ? { scope: this.config.selector } : {}));
+    }
+    /**
+     * Sets the flag configuration
+     * @param flags The flags to set as stringified JSON
+     * @returns {string[]} The flags that have changed
+     * @throws — {Error} If the configuration string is invalid.
+     */
+    setFlagConfiguration(flags) {
+        return this._flagdCore.setConfigurations(flags);
     }
 }
 
@@ -6484,9 +6597,10 @@ class FlagdProvider {
             this._status = serverSdk.ProviderStatus.READY;
         })
             .catch((err) => {
-            var _a;
+            var _a, _b;
             this._status = serverSdk.ProviderStatus.ERROR;
-            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`${this.metadata.name}: error during initialization: ${err.message}, ${err.stack}`);
+            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`${this.metadata.name}: error during initialization: ${err.message}`);
+            (_b = this.logger) === null || _b === void 0 ? void 0 : _b.debug(err);
             throw err;
         });
     }
@@ -6519,9 +6633,9 @@ class FlagdProvider {
         this._status = serverSdk.ProviderStatus.READY;
         this._events.emit(serverSdk.ProviderEvents.Ready);
     }
-    handleError() {
+    handleError(message) {
         this._status = serverSdk.ProviderStatus.ERROR;
-        this._events.emit(serverSdk.ProviderEvents.Error);
+        this._events.emit(serverSdk.ProviderEvents.Error, { message });
     }
     handleChanged(flagsChanged) {
         this._events.emit(serverSdk.ProviderEvents.ConfigurationChanged, { flagsChanged });

package/index.esm.js

@@ -4,6 +4,8 @@ import { ConnectivityState } from '@grpc/grpc-js/build/src/connectivity-state';
 import { LRUCache } from 'lru-cache';
 import { promisify } from 'util';
 import { FlagdCore } from '@openfeature/flagd-core';
+import { OpenFeatureError, GeneralError as GeneralError$1 } from '@openfeature/core';
+import { promises, watchFile, unwatchFile } from 'fs';
 
 const EVENT_CONFIGURATION_CHANGE = 'configuration_change';
 const EVENT_PROVIDER_READY = 'provider_ready';
@@ -28,10 +30,11 @@ var ENV_VAR;
     ENV_VAR["FLAGD_MAX_CACHE_SIZE"] = "FLAGD_MAX_CACHE_SIZE";
     ENV_VAR["FLAGD_SOURCE_SELECTOR"] = "FLAGD_SOURCE_SELECTOR";
     ENV_VAR["FLAGD_RESOLVER"] = "FLAGD_RESOLVER";
+    ENV_VAR["FLAGD_OFFLINE_FLAG_SOURCE_PATH"] = "FLAGD_OFFLINE_FLAG_SOURCE_PATH";
 })(ENV_VAR || (ENV_VAR = {}));
 const getEnvVarConfig = () => {
     var _a;
-    return (Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (process.env[ENV_VAR.FLAGD_HOST] && {
+    return (Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (process.env[ENV_VAR.FLAGD_HOST] && {
         host: process.env[ENV_VAR.FLAGD_HOST],
     })), (Number(process.env[ENV_VAR.FLAGD_PORT]) && {
         port: Number(process.env[ENV_VAR.FLAGD_PORT]),
@@ -47,6 +50,8 @@ const getEnvVarConfig = () => {
         selector: process.env[ENV_VAR.FLAGD_SOURCE_SELECTOR],
     })), ((process.env[ENV_VAR.FLAGD_RESOLVER] === 'rpc' || process.env[ENV_VAR.FLAGD_RESOLVER] === 'in-process') && {
         resolverType: process.env[ENV_VAR.FLAGD_RESOLVER],
+    })), (process.env[ENV_VAR.FLAGD_OFFLINE_FLAG_SOURCE_PATH] && {
+        offlineFlagSourcePath: process.env[ENV_VAR.FLAGD_OFFLINE_FLAG_SOURCE_PATH],
     })));
 };
 function getConfig(options = {}) {
@@ -5938,13 +5943,15 @@ class GRPCService {
             if (data && typeof data === 'object' && 'flags' in data && (data === null || data === void 0 ? void 0 : data['flags'])) {
                 const flagChangeMessage = data;
                 const flagsChanged = Object.keys(flagChangeMessage.flags || []);
-                // remove each changed key from cache
-                flagsChanged.forEach((key) => {
-                    var _a, _b;
-                    if ((_a = this._cache) === null || _a === void 0 ? void 0 : _a.delete(key)) {
-                        (_b = this.logger) === null || _b === void 0 ? void 0 : _b.debug(`${FlagdProvider.name}: evicted key: ${key} from cache.`);
-                    }
-                });
+                if (this._cacheEnabled) {
+                    // remove each changed key from cache
+                    flagsChanged.forEach((key) => {
+                        var _a, _b;
+                        if ((_a = this._cache) === null || _a === void 0 ? void 0 : _a.delete(key)) {
+                            (_b = this.logger) === null || _b === void 0 ? void 0 : _b.debug(`${FlagdProvider.name}: evicted key: ${key} from cache.`);
+                        }
+                    });
+                }
                 changedCallback(flagsChanged);
             }
         }
@@ -5957,7 +5964,7 @@ class GRPCService {
     }
     handleError(reconnectCallback, changedCallback, disconnectCallback) {
         var _a, _b;
-        disconnectCallback();
+        disconnectCallback('streaming connection error, will attempt reconnect...');
         (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`${FlagdProvider.name}: streaming connection error, will attempt reconnect...`);
         (_b = this._cache) === null || _b === void 0 ? void 0 : _b.clear();
         this.reconnect(reconnectCallback, changedCallback, disconnectCallback);
@@ -6352,6 +6359,18 @@ function isSet(value) {
  */
 class GrpcFetch {
     constructor(config, syncServiceClient, logger) {
+        /**
+         * Initialized will be set to true once the initial connection is successful
+         * and the first payload has been received. Subsequent reconnects will not
+         * change the initialized value.
+         */
+        this._initialized = false;
+        /**
+         * Is connected represents the current known connection state. It will be
+         * set to true once the first payload has been received.but will be set to
+         * false if the connection is lost.
+         */
+        this._isConnected = false;
         const { host, port, tls, socketPath, selector } = config;
         this._syncClient = syncServiceClient
             ? syncServiceClient
@@ -6359,55 +6378,131 @@ class GrpcFetch {
         this._logger = logger;
         this._request = { providerId: '', selector: selector ? selector : '' };
     }
-    connect(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback) {
-        return new Promise((resolve, reject) => this.listen(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback, resolve, reject));
+    connect(dataCallback, reconnectCallback, changedCallback, disconnectCallback) {
+        return new Promise((resolve, reject) => this.listen(dataCallback, reconnectCallback, changedCallback, disconnectCallback, resolve, reject)).then(() => {
+            this._initialized = true;
+        });
     }
     disconnect() {
         var _a;
-        (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Disconnecting gRPC sync connection');
-        closeStreamIfDefined(this._syncStream);
-        this._syncClient.close();
+        return __awaiter(this, void 0, void 0, function* () {
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Disconnecting gRPC sync connection');
+            closeStreamIfDefined(this._syncStream);
+            this._syncClient.close();
+        });
     }
-    listen(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback, resolveConnect, rejectConnect) {
+    listen(dataCallback, reconnectCallback, changedCallback, disconnectCallback, resolveConnect, rejectConnect) {
+        var _a;
+        (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Starting gRPC sync connection');
         closeStreamIfDefined(this._syncStream);
         this._syncStream = this._syncClient.syncFlags(this._request);
         this._syncStream.on('data', (data) => {
-            var _a;
-            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Received sync payload');
-            dataFillCallback(data.flagConfiguration);
-            changedCallback([]); // flags changed list not supported
-            // if resolveConnect is undefined, this is a reconnection; we only want to fire the reconnect callback in that case
+            var _a, _b, _c, _d;
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug(`Received sync payload`);
+            try {
+                const changes = dataCallback(data.flagConfiguration);
+                if (this._initialized && changes.length > 0) {
+                    changedCallback(changes);
+                }
+            }
+            catch (err) {
+                (_b = this._logger) === null || _b === void 0 ? void 0 : _b.debug('Error processing sync payload: ', (_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : 'unknown error');
+            }
             if (resolveConnect) {
                 resolveConnect();
             }
-            else {
+            else if (!this._isConnected) {
+                // Not the first connection and there's no active connection.
+                (_d = this._logger) === null || _d === void 0 ? void 0 : _d.debug('Reconnected to gRPC sync');
                 reconnectCallback();
             }
+            this._isConnected = true;
         });
         this._syncStream.on('error', (err) => {
-            var _a;
-            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.error('Connection error, attempting to reconnect', err);
-            disconnectCallback();
-            rejectConnect === null || rejectConnect === void 0 ? void 0 : rejectConnect(new GeneralError('Failed to connect stream'));
-            this.reconnect(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback);
+            var _a, _b, _c;
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.error('Connection error, attempting to reconnect');
+            (_b = this._logger) === null || _b === void 0 ? void 0 : _b.debug(err);
+            this._isConnected = false;
+            const errorMessage = (_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : 'Failed to connect to syncFlags stream';
+            disconnectCallback(errorMessage);
+            rejectConnect === null || rejectConnect === void 0 ? void 0 : rejectConnect(new GeneralError(errorMessage));
+            this.reconnect(dataCallback, reconnectCallback, changedCallback, disconnectCallback);
         });
     }
-    reconnect(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback) {
+    reconnect(dataCallback, reconnectCallback, changedCallback, disconnectCallback) {
         const channel = this._syncClient.getChannel();
         channel.watchConnectivityState(channel.getConnectivityState(true), Infinity, () => {
-            this.listen(dataFillCallback, reconnectCallback, changedCallback, disconnectCallback);
+            this.listen(dataCallback, reconnectCallback, changedCallback, disconnectCallback);
+        });
+    }
+}
+
+const encoding = 'utf8';
+class FileFetch {
+    constructor(filename, logger) {
+        this._filename = filename;
+        this._logger = logger;
+    }
+    connect(dataFillCallback, _, changedCallback) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug('Starting file sync connection');
+            try {
+                const output = yield promises.readFile(this._filename, encoding);
+                // Don't emit the change event for the initial read
+                dataFillCallback(output);
+                // Using watchFile instead of watch to support virtualized host file systems.
+                watchFile(this._filename, () => __awaiter(this, void 0, void 0, function* () {
+                    var _c;
+                    try {
+                        const data = yield promises.readFile(this._filename, encoding);
+                        const changes = dataFillCallback(data);
+                        if (changes.length > 0) {
+                            changedCallback(changes);
+                        }
+                    }
+                    catch (err) {
+                        (_c = this._logger) === null || _c === void 0 ? void 0 : _c.error(`Error reading file: ${err}`);
+                    }
+                }));
+            }
+            catch (err) {
+                if (err instanceof OpenFeatureError) {
+                    throw err;
+                }
+                else {
+                    switch (err === null || err === void 0 ? void 0 : err.code) {
+                        case 'ENOENT':
+                            throw new GeneralError$1(`File not found: ${this._filename}`);
+                        case 'EACCES':
+                            throw new GeneralError$1(`File not accessible: ${this._filename}`);
+                        default:
+                            (_b = this._logger) === null || _b === void 0 ? void 0 : _b.debug(`Error reading file: ${err}`);
+                            throw new GeneralError$1();
+                    }
+                }
+            }
+        });
+    }
+    disconnect() {
+        return __awaiter(this, void 0, void 0, function* () {
+            unwatchFile(this._filename);
         });
     }
 }
 
 class InProcessService {
     constructor(config, dataFetcher, logger) {
-        this.logger = logger;
+        this.config = config;
         this._flagdCore = new FlagdCore(undefined, logger);
-        this._dataFetcher = dataFetcher ? dataFetcher : new GrpcFetch(config, undefined, logger);
+        this._dataFetcher = dataFetcher
+            ? dataFetcher
+            : config.offlineFlagSourcePath
+                ? new FileFetch(config.offlineFlagSourcePath, logger)
+                : new GrpcFetch(config, undefined, logger);
     }
     connect(reconnectCallback, changedCallback, disconnectCallback) {
-        return this._dataFetcher.connect(this.fill.bind(this), reconnectCallback, changedCallback, disconnectCallback);
+        return this._dataFetcher.connect(this.setFlagConfiguration.bind(this), reconnectCallback, changedCallback, disconnectCallback);
     }
     disconnect() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -6415,25 +6510,43 @@ class InProcessService {
         });
     }
     resolveBoolean(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveBooleanEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('boolean', flagKey, defaultValue, context, logger);
+        });
     }
     resolveNumber(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveNumberEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('number', flagKey, defaultValue, context, logger);
+        });
     }
     resolveString(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveStringEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('string', flagKey, defaultValue, context, logger);
+        });
     }
     resolveObject(flagKey, defaultValue, context, logger) {
-        return Promise.resolve(this._flagdCore.resolveObjectEvaluation(flagKey, defaultValue, context, logger));
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.evaluate('object', flagKey, defaultValue, context, logger);
+        });
     }
-    fill(flags) {
-        var _a;
-        try {
-            this._flagdCore.setConfigurations(flags);
-        }
-        catch (err) {
-            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(err);
-        }
+    evaluate(type, flagKey, defaultValue, context, logger) {
+        const details = this._flagdCore.resolve(type, flagKey, defaultValue, context, logger);
+        return Object.assign(Object.assign({}, details), { flagMetadata: this.addFlagMetadata() });
+    }
+    /**
+     * Adds the flag metadata to the resolution details
+     */
+    addFlagMetadata() {
+        return Object.assign({}, (this.config.selector ? { scope: this.config.selector } : {}));
+    }
+    /**
+     * Sets the flag configuration
+     * @param flags The flags to set as stringified JSON
+     * @returns {string[]} The flags that have changed
+     * @throws — {Error} If the configuration string is invalid.
+     */
+    setFlagConfiguration(flags) {
+        return this._flagdCore.setConfigurations(flags);
     }
 }
 
@@ -6480,9 +6593,10 @@ class FlagdProvider {
             this._status = ProviderStatus.READY;
         })
             .catch((err) => {
-            var _a;
+            var _a, _b;
             this._status = ProviderStatus.ERROR;
-            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`${this.metadata.name}: error during initialization: ${err.message}, ${err.stack}`);
+            (_a = this.logger) === null || _a === void 0 ? void 0 : _a.error(`${this.metadata.name}: error during initialization: ${err.message}`);
+            (_b = this.logger) === null || _b === void 0 ? void 0 : _b.debug(err);
             throw err;
         });
     }
@@ -6515,9 +6629,9 @@ class FlagdProvider {
         this._status = ProviderStatus.READY;
         this._events.emit(ProviderEvents.Ready);
     }
-    handleError() {
+    handleError(message) {
         this._status = ProviderStatus.ERROR;
-        this._events.emit(ProviderEvents.Error);
+        this._events.emit(ProviderEvents.Error, { message });
     }
     handleChanged(flagsChanged) {
         this._events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged });

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@openfeature/flagd-provider",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "scripts": {
     "publish-if-not-exists": "cp $NPM_CONFIG_USERCONFIG .npmrc && if [ \"$(npm show $npm_package_name@$npm_package_version version)\" = \"$(npm run current-version -s)\" ]; then echo 'already published, skipping'; else npm publish --access public; fi",
     "current-version": "echo $npm_package_version"
   },
   "dependencies": {
-    "@openfeature/flagd-core": "~0.1.4",
+    "@openfeature/flagd-core": "~0.1.10",
     "@protobuf-ts/runtime-rpc": "2.9.0",
     "lru-cache": "10.0.1",
     "util": "0.12.5"
   },
   "peerDependencies": {
     "@grpc/grpc-js": "~1.8.0 || ~1.9.0",
-    "@openfeature/server-sdk": ">=1.6.0"
+    "@openfeature/server-sdk": ">=1.8.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/configuration.d.ts

@@ -36,6 +36,11 @@ export interface Config {
      * @default 'rpc'
      */
     resolverType?: ResolverType;
+    /**
+     * File source of flags to be used by offline mode.
+     * Setting this enables the offline mode of the in-process provider.
+     */
+    offlineFlagSourcePath?: string;
     /**
      * Selector to be used with flag sync gRPC contract.
      */
@@ -60,6 +65,7 @@ export declare function getConfig(options?: FlagdProviderOptions): {
     tls: boolean;
     socketPath?: string | undefined;
     resolverType?: ResolverType | undefined;
+    offlineFlagSourcePath?: string | undefined;
     selector?: string | undefined;
     cache?: CacheOption | undefined;
     maxCacheSize?: number | undefined;

package/src/lib/service/grpc/grpc-service.d.ts

@@ -26,7 +26,7 @@ export declare class GRPCService implements Service {
     private _eventStream;
     private get _cacheActive();
     constructor(config: Config, client?: ServiceClient, logger?: Logger | undefined);
-    connect(reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: () => void): Promise<void>;
+    connect(reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: (message: string) => void): Promise<void>;
     disconnect(): Promise<void>;
     resolveBoolean(flagKey: string, _: boolean, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
     resolveString(flagKey: string, _: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<string>>;

package/src/lib/service/in-process/data-fetch.d.ts

@@ -2,6 +2,32 @@
  * Contract of in-process resolver's data fetcher
  */
 export interface DataFetch {
-    connect(dataFillCallback: (flags: string) => void, reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: () => void): Promise<void>;
-    disconnect(): void;
+    /**
+     * Connects the data fetcher
+     */
+    connect(
+    /**
+     * Callback that runs when data is received from the source
+     * @param flags The flags from the source
+     * @returns The flags that have changed
+     */
+    dataCallback: (flags: string) => string[], 
+    /**
+     * Callback that runs when the connection is re-established
+     */
+    reconnectCallback: () => void, 
+    /**
+     * Callback that runs when flags have changed
+     * @param flagsChanged The flags that have changed
+     */
+    changedCallback: (flagsChanged: string[]) => void, 
+    /**
+     * Callback that runs when the connection is disconnected
+     * @param message The reason for the disconnection
+     */
+    disconnectCallback: (message: string) => void): Promise<void>;
+    /**
+     * Disconnects the data fetcher
+     */
+    disconnect(): Promise<void>;
 }

package/src/lib/service/in-process/file/file-fetch.d.ts

@@ -0,0 +1,9 @@
+import { Logger } from '@openfeature/core';
+import { DataFetch } from '../data-fetch';
+export declare class FileFetch implements DataFetch {
+    private _filename;
+    private _logger;
+    constructor(filename: string, logger?: Logger);
+    connect(dataFillCallback: (flags: string) => string[], _: () => void, changedCallback: (flagsChanged: string[]) => void): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/src/lib/service/in-process/grpc/grpc-fetch.d.ts

@@ -6,13 +6,25 @@ import { DataFetch } from '../data-fetch';
  * Implements the gRPC sync contract to fetch flag data.
  */
 export declare class GrpcFetch implements DataFetch {
-    private _syncClient;
-    private _syncStream;
+    private readonly _syncClient;
     private readonly _request;
+    private _syncStream;
     private _logger;
+    /**
+     * Initialized will be set to true once the initial connection is successful
+     * and the first payload has been received. Subsequent reconnects will not
+     * change the initialized value.
+     */
+    private _initialized;
+    /**
+     * Is connected represents the current known connection state. It will be
+     * set to true once the first payload has been received.but will be set to
+     * false if the connection is lost.
+     */
+    private _isConnected;
     constructor(config: Config, syncServiceClient?: FlagSyncServiceClient, logger?: Logger);
-    connect(dataFillCallback: (flags: string) => void, reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: () => void): Promise<void>;
-    disconnect(): void;
+    connect(dataCallback: (flags: string) => string[], reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: (message: string) => void): Promise<void>;
+    disconnect(): Promise<void>;
     private listen;
     private reconnect;
 }

package/src/lib/service/in-process/in-process-service.d.ts

@@ -3,15 +3,26 @@ import { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfe
 import { Config } from '../../configuration';
 import { DataFetch } from './data-fetch';
 export declare class InProcessService implements Service {
-    private logger?;
+    private readonly config;
     private _flagdCore;
     private _dataFetcher;
-    constructor(config: Config, dataFetcher?: DataFetch, logger?: Logger | undefined);
-    connect(reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: () => void): Promise<void>;
+    constructor(config: Config, dataFetcher?: DataFetch, logger?: Logger);
+    connect(reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: (message: string) => void): Promise<void>;
     disconnect(): Promise<void>;
     resolveBoolean(flagKey: string, defaultValue: boolean, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
     resolveNumber(flagKey: string, defaultValue: number, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<number>>;
     resolveString(flagKey: string, defaultValue: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<string>>;
     resolveObject<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<T>>;
-    private fill;
+    private evaluate;
+    /**
+     * Adds the flag metadata to the resolution details
+     */
+    private addFlagMetadata;
+    /**
+     * Sets the flag configuration
+     * @param flags The flags to set as stringified JSON
+     * @returns {string[]} The flags that have changed
+     * @throws — {Error} If the configuration string is invalid.
+     */
+    private setFlagConfiguration;
 }

package/src/lib/service/service.d.ts

@@ -1,6 +1,6 @@
 import { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfeature/server-sdk';
 export interface Service {
-    connect(reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: () => void): Promise<void>;
+    connect(reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: (message: string) => void): Promise<void>;
     disconnect(): Promise<void>;
     resolveBoolean(flagKey: string, defaultValue: boolean, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
     resolveString(flagKey: string, defaultValue: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<string>>;