@openfeature/flagd-provider 0.13.2 → 0.13.4

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@openfeature/flagd-provider",
-  "version": "0.13.2",
+  "version": "0.13.4",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-feature/js-sdk-contrib.git",
+    "directory": "libs/providers/flagd"
+  },
   "license": "Apache-2.0",
   "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"
   },
   "peerDependencies": {
-    "@grpc/grpc-js": "~1.8.0 || ~1.9.0 || ~1.10.0 || ~1.11.0 || ~1.12.0",
+    "@grpc/grpc-js": "~1.8.0 || ~1.9.0 || ~1.10.0 || ~1.11.0 || ~1.12.0 || ~1.13.0 || ~1.14.0",
     "@openfeature/server-sdk": "^1.17.0"
   },
   "dependencies": {
     "lru-cache": "^11.0.0",
-    "@openfeature/flagd-core": "^1.0.0"
+    "@openfeature/flagd-core": "^1.2.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/SyncMetadataHook.d.ts

@@ -0,0 +1,6 @@
+import type { Hook, EvaluationContext, BeforeHookContext, HookHints } from '@openfeature/server-sdk';
+export declare class SyncMetadataHook implements Hook {
+    enrichedContext: () => EvaluationContext;
+    constructor(enrichedContext: () => EvaluationContext);
+    before(hookContext: BeforeHookContext, hookHints?: HookHints): EvaluationContext;
+}

package/src/lib/configuration.d.ts

@@ -1,3 +1,4 @@
+import type { EvaluationContext } from '@openfeature/server-sdk';
 export type CacheOption = 'lru' | 'disabled';
 export type ResolverType = 'rpc' | 'in-process';
 export interface Config {
@@ -13,6 +14,12 @@ export interface Config {
      * @default 8013
      */
     port: number;
+    /**
+     * The deadline for connections.
+     *
+     * @default 500
+     */
+    deadlineMs: number;
     /**
      * Determines if TLS should be used.
      *
@@ -25,6 +32,12 @@ export interface Config {
      * @example "/tmp/flagd.socks"
      */
     socketPath?: string;
+    /**
+     * TLS certificate path to use when TLS connectivity is enabled.
+     *
+     * @example "/etc/cert/ca.crt"
+     */
+    certPath?: string;
     /**
      * Resolver type to use by the provider.
      *
@@ -57,16 +70,60 @@ export interface Config {
      * @default 1000
      */
     maxCacheSize?: number;
+    /**
+     * The target host (authority) when routing requests through a proxy (e.g. Envoy)
+     *
+     */
+    defaultAuthority?: string;
+    /**
+     * Initial retry backoff in milliseconds.
+     */
+    retryBackoffMs?: number;
+    /**
+     * Maximum retry backoff in milliseconds.
+     */
+    retryBackoffMaxMs?: number;
+    /**
+     * gRPC client KeepAlive in milliseconds. Disabled with 0.
+     * Only applies to RPC and in-process resolvers.
+     *
+     * @default 0
+     */
+    keepAliveTime?: number;
+    /**
+     * List of gRPC fatal status codes that should cause the provider to fail without retrying.
+     * @default []
+     */
+    fatalStatusCodes?: string[];
+    /**
+     * Grace period in seconds before provider moves from STALE to ERROR.
+     * When the provider disconnects, it emits STALE. If disconnected for longer
+     * than retryGracePeriod, it emits ERROR.
+     *
+     * @default 5
+     */
+    retryGracePeriod?: number;
 }
-export type FlagdProviderOptions = Partial<Config>;
-export declare function getConfig(options?: FlagdProviderOptions): {
-    host: string;
-    port: number;
-    tls: boolean;
-    socketPath?: string;
-    resolverType?: ResolverType;
-    offlineFlagSourcePath?: string;
-    selector?: string;
-    cache?: CacheOption;
-    maxCacheSize?: number;
-};
+interface FlagdConfig extends Config {
+    /**
+     * Function providing an EvaluationContext to mix into every evaluation.
+     * The syncContext from the SyncFlagsResponse
+     * (https://buf.build/open-feature/flagd/docs/main:flagd.sync.v1#flagd.sync.v1.SyncFlagsResponse),
+     * represented as a {@link dev.openfeature.sdk.Structure}, is passed as an argument.
+     *
+     * This function runs every time the provider (re)connects, and its result is cached and used in every evaluation.
+     * By default, the entire sync response (as a JSON Object) is used.
+     */
+    contextEnricher: (syncContext: EvaluationContext | null) => EvaluationContext;
+}
+export interface FlagdGrpcConfig extends Config {
+    /**
+     * The deadline for streaming connections.
+     *
+     * @default 600000
+     */
+    streamDeadlineMs: number;
+}
+export type FlagdProviderOptions = Partial<FlagdConfig & FlagdGrpcConfig>;
+export declare function getConfig(options?: FlagdProviderOptions): FlagdConfig & FlagdGrpcConfig;
+export {};

package/src/lib/constants.d.ts

@@ -3,3 +3,6 @@ export declare const DEFAULT_MAX_EVENT_STREAM_RETRIES: number;
 export declare const EVENT_CONFIGURATION_CHANGE = "configuration_change";
 export declare const EVENT_PROVIDER_READY = "provider_ready";
 export declare const DEFAULT_MAX_CACHE_SIZE = 1000;
+export declare const DEFAULT_RETRY_GRACE_PERIOD = 5;
+export declare const DEFAULT_MAX_BACKOFF_MS = 12000;
+export declare const FLAGD_SELECTOR_HEADER = "flagd-selector";

package/src/lib/flagd-provider.d.ts

@@ -1,14 +1,21 @@
-import { EvaluationContext, JsonValue, Logger, OpenFeatureEventEmitter, Provider, ResolutionDetails } from '@openfeature/server-sdk';
-import { FlagdProviderOptions } from './configuration';
-import { Service } from './service/service';
+import type { EvaluationContext, JsonValue, Logger, Provider, ResolutionDetails } from '@openfeature/server-sdk';
+import { OpenFeatureEventEmitter } from '@openfeature/server-sdk';
+import type { FlagdProviderOptions } from './configuration';
+import type { Service } from './service/service';
+import type { Hook } from '@openfeature/server-sdk';
 export declare class FlagdProvider implements Provider {
     private readonly logger?;
     metadata: {
         name: string;
     };
+    readonly hooks?: Hook[];
     readonly runsOn = "server";
     readonly events: OpenFeatureEventEmitter;
+    private syncContext;
     private readonly _service;
+    private readonly _retryGracePeriod;
+    private _errorTimer?;
+    private _isErrorState;
     /**
      * Construct a new flagd provider.
      *
@@ -17,6 +24,8 @@ export declare class FlagdProvider implements Provider {
      * @param service optional internal service implementation, should not be needed for production
      */
     constructor(options?: FlagdProviderOptions, logger?: Logger | undefined, service?: Service);
+    setSyncContext(context: EvaluationContext): void;
+    getSyncContext(): EvaluationContext | null;
     initialize(): Promise<void>;
     onClose(): Promise<void>;
     resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, transformedContext: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
@@ -26,4 +35,5 @@ export declare class FlagdProvider implements Provider {
     private handleReconnect;
     private handleError;
     private handleChanged;
+    private clearErrorTimer;
 }

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

@@ -1,2 +1,48 @@
-import { ClientReadableStream } from '@grpc/grpc-js';
+import type { ClientReadableStream, ChannelCredentials, ClientOptions } from '@grpc/grpc-js';
+import type { Config } from '../../configuration';
+import type { Logger } from '@openfeature/server-sdk';
 export declare const closeStreamIfDefined: (stream: ClientReadableStream<unknown> | undefined) => void;
+/**
+ * Creates gRPC channel credentials based on TLS and certificate path configuration.
+ * @returns Channel credentials for gRPC connection
+ */
+export declare const createChannelCredentials: (tls: boolean, certPath?: string) => ChannelCredentials;
+/**
+ * Builds gRPC client options from config.
+ */
+export declare function buildClientOptions(config: Config): ClientOptions;
+/**
+ * Builds RetryPolicy for gRPC client options.
+ * @param serviceNames Array of service names to configure retry policy for
+ * @param retryBackoffMs Initial backoff duration in milliseconds
+ * @param retryBackoffMaxMs Maximum backoff duration in milliseconds
+ * @returns gRPC client options with retry policy
+ */
+export declare const buildRetryPolicy: (serviceNames: string[], retryBackoffMs?: number, retryBackoffMaxMs?: number) => string;
+/**
+ * Converts an array of gRPC status code strings to a Set of numeric codes.
+ * @param fatalStatusCodes Array of status code strings.
+ * @param logger Optional logger for warning about unknown codes
+ * @returns Set of numeric status codes
+ */
+export declare const createFatalStatusCodesSet: (fatalStatusCodes?: string[], logger?: Logger) => Set<number>;
+/**
+ * Checks if an error is a fatal gRPC status code that should not be retried.
+ * This should only be checked on the first connection attempt.
+ *
+ * @param err The error to check
+ * @param initialized Whether the connection has been successfully initialized
+ * @param fatalStatusCodes Set of numeric status codes considered fatal
+ * @returns True if the error is fatal and should not be retried
+ */
+export declare const isFatalStatusCodeError: (err: Error, initialized: boolean, fatalStatusCodes: Set<number>) => boolean;
+/**
+ * Handles a fatal gRPC status code error by logging it.
+ * Should only be called when isFatalStatusCodeError returns true.
+ *
+ * @param err The error to handle
+ * @param logger Optional logger for error logging
+ * @param disconnectCallback Callback to invoke with the error message
+ * @param rejectConnect Optional callback to reject the connection promise
+ */
+export declare const handleFatalStatusCodeError: (err: Error, logger: Logger | undefined, disconnectCallback: (message: string) => void, rejectConnect?: (reason: Error) => void) => void;

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

@@ -1,7 +1,7 @@
-import { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfeature/server-sdk';
+import type { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfeature/server-sdk';
 import { ServiceClient } from '../../../proto/ts/flagd/evaluation/v1/evaluation';
-import { Config } from '../../configuration';
-import { Service } from '../service';
+import type { FlagdGrpcConfig } from '../../configuration';
+import type { Service } from '../service';
 interface FlagChange {
     type: 'delete' | 'write' | 'update';
     source: string;
@@ -24,8 +24,16 @@ export declare class GRPCService implements Service {
     private _cache;
     private _cacheEnabled;
     private _eventStream;
+    private _deadline;
+    private readonly _fatalStatusCodes;
+    private _initialized;
+    private _streamDeadline;
+    private _maxBackoffMs;
+    private _errorThrottled;
+    private readonly _metadata;
     private get _cacheActive();
-    constructor(config: Config, client?: ServiceClient, logger?: Logger | undefined);
+    constructor(config: FlagdGrpcConfig, client?: ServiceClient, logger?: Logger | undefined);
+    clearCache(): 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>>;

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

@@ -1,5 +1,5 @@
-import { Logger } from '@openfeature/server-sdk';
-import { DataFetch } from '../data-fetch';
+import type { Logger } from '@openfeature/server-sdk';
+import type { DataFetch } from '../data-fetch';
 export declare class FileFetch implements DataFetch {
     private _filename;
     private _logger;

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

@@ -1,15 +1,22 @@
-import { Logger } from '@openfeature/server-sdk';
+import type { EvaluationContext, Logger } from '@openfeature/server-sdk';
 import { FlagSyncServiceClient } from '../../../../proto/ts/flagd/sync/v1/sync';
-import { Config } from '../../../configuration';
-import { DataFetch } from '../data-fetch';
+import type { FlagdGrpcConfig } from '../../../configuration';
+import type { DataFetch } from '../data-fetch';
 /**
  * Implements the gRPC sync contract to fetch flag data.
  */
 export declare class GrpcFetch implements DataFetch {
     private readonly _syncClient;
     private readonly _request;
+    private readonly _deadlineMs;
+    private readonly _maxBackoffMs;
+    private readonly _streamDeadlineMs;
+    private readonly _metadata;
     private _syncStream;
+    private readonly _setSyncContext;
     private _logger;
+    private readonly _fatalStatusCodes;
+    private _errorThrottled;
     /**
      * Initialized will be set to true once the initial connection is successful
      * and the first payload has been received. Subsequent reconnects will not
@@ -22,7 +29,7 @@ export declare class GrpcFetch implements DataFetch {
      * false if the connection is lost.
      */
     private _isConnected;
-    constructor(config: Config, syncServiceClient?: FlagSyncServiceClient, logger?: Logger);
+    constructor(config: FlagdGrpcConfig, setSyncContext: (syncContext: EvaluationContext) => void, syncServiceClient?: FlagSyncServiceClient, logger?: Logger);
     connect(dataCallback: (flags: string) => string[], reconnectCallback: () => void, changedCallback: (flagsChanged: string[]) => void, disconnectCallback: (message: string) => void): Promise<void>;
     disconnect(): Promise<void>;
     private listen;

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

@@ -1,12 +1,13 @@
 import type { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfeature/server-sdk';
-import { Config } from '../../configuration';
-import { Service } from '../service';
-import { DataFetch } from './data-fetch';
+import type { FlagdGrpcConfig } from '../../configuration';
+import type { Service } from '../service';
+import type { DataFetch } from './data-fetch';
 export declare class InProcessService implements Service {
     private readonly config;
     private _flagdCore;
     private _dataFetcher;
-    constructor(config: Config, dataFetcher?: DataFetch, logger?: Logger);
+    constructor(config: FlagdGrpcConfig, setSyncContext: (syncContext: EvaluationContext) => void, dataFetcher?: DataFetch, logger?: Logger);
+    clearCache(): 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>>;

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

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

package/src/proto/ts/flagd/evaluation/v1/evaluation.d.ts

@@ -21,6 +21,10 @@ export interface ResolveAllResponse {
     flags: {
         [key: string]: AnyFlag;
     };
+    /** Metadata for the bulk evaluation */
+    metadata: {
+        [key: string]: any;
+    } | undefined;
 }
 export interface ResolveAllResponse_FlagsEntry {
     key: string;
@@ -38,7 +42,7 @@ export interface AnyFlag {
     objectValue?: {
         [key: string]: any;
     } | undefined;
-    /** Metadata about this flag, see https://openfeature.dev/specification/types/#flag-metadata */
+    /** Metadata for this evaluation */
     metadata: {
         [key: string]: any;
     } | undefined;

package/src/proto/ts/flagd/sync/v1/sync.d.ts

@@ -30,8 +30,12 @@ export interface SyncFlagsRequest {
 }
 /** SyncFlagsResponse is the server response containing feature flag configurations and the state */
 export interface SyncFlagsResponse {
-    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json */
+    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/flagd-schemas/main/json/flags.json */
     flagConfiguration: string;
+    /** Static context to be included in in-process evaluations (optional). */
+    syncContext?: {
+        [key: string]: any;
+    } | undefined;
 }
 /** FetchAllFlagsRequest is the request to fetch all flags. Clients send this request as the client in order to resync their internal state */
 export interface FetchAllFlagsRequest {
@@ -53,13 +57,22 @@ export interface FetchAllFlagsRequest {
 }
 /** FetchAllFlagsResponse is the server response containing feature flag configurations */
 export interface FetchAllFlagsResponse {
-    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json */
+    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/flagd-schemas/main/json/flags.json */
     flagConfiguration: string;
 }
-/** GetMetadataRequest is the request for retrieving metadata from the sync service */
+/**
+ * GetMetadataRequest is the request for retrieving metadata from the sync service
+ *
+ * @deprecated
+ */
 export interface GetMetadataRequest {
 }
-/** GetMetadataResponse contains metadata from the sync service */
+/**
+ * GetMetadataResponse contains metadata from the sync service
+ * DEPRECATED; use flagd.sync.v1.SyncFlagsResponse.sync_context
+ *
+ * @deprecated
+ */
 export interface GetMetadataResponse {
     metadata: {
         [key: string]: any;
@@ -134,6 +147,7 @@ export declare const FlagSyncServiceService: {
         readonly responseSerialize: (value: FetchAllFlagsResponse) => Buffer<ArrayBuffer>;
         readonly responseDeserialize: (value: Buffer) => FetchAllFlagsResponse;
     };
+    /** @deprecated */
     readonly getMetadata: {
         readonly path: "/flagd.sync.v1.FlagSyncService/GetMetadata";
         readonly requestStream: false;
@@ -147,6 +161,7 @@ export declare const FlagSyncServiceService: {
 export interface FlagSyncServiceServer extends UntypedServiceImplementation {
     syncFlags: handleServerStreamingCall<SyncFlagsRequest, SyncFlagsResponse>;
     fetchAllFlags: handleUnaryCall<FetchAllFlagsRequest, FetchAllFlagsResponse>;
+    /** @deprecated */
     getMetadata: handleUnaryCall<GetMetadataRequest, GetMetadataResponse>;
 }
 export interface FlagSyncServiceClient extends Client {
@@ -155,6 +170,7 @@ export interface FlagSyncServiceClient extends Client {
     fetchAllFlags(request: FetchAllFlagsRequest, callback: (error: ServiceError | null, response: FetchAllFlagsResponse) => void): ClientUnaryCall;
     fetchAllFlags(request: FetchAllFlagsRequest, metadata: Metadata, callback: (error: ServiceError | null, response: FetchAllFlagsResponse) => void): ClientUnaryCall;
     fetchAllFlags(request: FetchAllFlagsRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: FetchAllFlagsResponse) => void): ClientUnaryCall;
+    /** @deprecated */
     getMetadata(request: GetMetadataRequest, callback: (error: ServiceError | null, response: GetMetadataResponse) => void): ClientUnaryCall;
     getMetadata(request: GetMetadataRequest, metadata: Metadata, callback: (error: ServiceError | null, response: GetMetadataResponse) => void): ClientUnaryCall;
     getMetadata(request: GetMetadataRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: GetMetadataResponse) => void): ClientUnaryCall;

package/src/proto/ts/sync/v1/sync_service.d.ts

@@ -57,7 +57,7 @@ export interface SyncFlagsRequest {
 }
 /** SyncFlagsResponse is the server response containing feature flag configurations and the state */
 export interface SyncFlagsResponse {
-    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json */
+    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/flagd-schemas/main/json/flags.json */
     flagConfiguration: string;
     /**
      * State conveying the operation to be performed by flagd. See the descriptions of SyncState for an explanation of
@@ -85,7 +85,7 @@ export interface FetchAllFlagsRequest {
 }
 /** FetchAllFlagsResponse is the server response containing feature flag configurations */
 export interface FetchAllFlagsResponse {
-    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json */
+    /** flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/flagd-schemas/main/json/flags.json */
     flagConfiguration: string;
 }
 export declare const SyncFlagsRequest: {