@openfeature/flagd-provider 0.7.4 → 0.7.6

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@openfeature/flagd-provider",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "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": {
-    "@openfeature/js-sdk": "^1.0.0"
+    "@openfeature/js-sdk": "^1.1.0"
   },
   "module": "./index.js",
   "main": "./index.cjs",
@@ -20,8 +20,10 @@
     }
   },
   "dependencies": {
-    "@protobuf-ts/grpc-transport": "2.8.2",
-    "@protobuf-ts/runtime-rpc": "2.8.2",
-    "@grpc/grpc-js": "1.8.0"
+    "@grpc/grpc-js": "1.8.13",
+    "@protobuf-ts/grpc-transport": "2.8.3",
+    "@protobuf-ts/runtime": "2.8.3",
+    "@protobuf-ts/runtime-rpc": "2.8.3",
+    "lru-cache": "8.0.5"
   }
 }

package/src/lib/configuration.d.ts

@@ -1,3 +1,4 @@
+export type CacheOption = 'lru' | 'disabled';
 export interface Config {
     /**
      * The domain name or IP address of flagd.
@@ -23,6 +24,24 @@ export interface Config {
      * @example "/tmp/flagd.socks"
      */
     socketPath?: string;
+    /**
+     * Cache implementation to use (or disabled).
+     *
+     * @default 'lru'
+     */
+    cache?: CacheOption;
+    /**
+     * Max cache size (items).
+     *
+     * @default 1000
+     */
+    maxCacheSize?: number;
+    /**
+     * Amount of times to attempt to reconnect to the event stream.
+     *
+     * @default 5
+     */
+    maxEventStreamRetries?: number;
 }
 export type FlagdProviderOptions = Partial<Config>;
 export declare function getConfig(options?: FlagdProviderOptions): {
@@ -30,4 +49,7 @@ export declare function getConfig(options?: FlagdProviderOptions): {
     port: number;
     tls: boolean;
     socketPath?: string | undefined;
+    cache?: CacheOption | undefined;
+    maxCacheSize?: number | undefined;
+    maxEventStreamRetries?: number | undefined;
 };

package/src/lib/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const BASE_EVENT_STREAM_RETRY_BACKOFF_MS = 1000;
+export declare const DEFAULT_MAX_EVENT_STREAM_RETRIES = 5;
+export declare const EVENT_CONFIGURATION_CHANGE = "configuration_change";
+export declare const EVENT_PROVIDER_READY = "provider_ready";
+export declare const DEFAULT_MAX_CACHE_SIZE = 1000;

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

@@ -2,11 +2,21 @@ import { EvaluationContext, JsonValue, Logger, Provider, ResolutionDetails } fro
 import { FlagdProviderOptions } from './configuration';
 import { Service } from './service/service';
 export declare class FlagdProvider implements Provider {
+    private logger?;
     metadata: {
         name: string;
     };
     private readonly _service;
-    constructor(options?: FlagdProviderOptions, service?: Service);
+    /**
+     * Promise indicating the gRPC stream is connected.
+     *
+     * Can be used in instances where the provider being connected to the event stream is a prerequisite
+     * to execution (e.g. testing). Not necessary for standard usage.
+     *
+     * @returns true if stream connected successfully, false if connection not enabled.
+     */
+    get streamConnection(): Promise<boolean>;
+    constructor(options?: FlagdProviderOptions, service?: Service, logger?: Logger | undefined);
     resolveBooleanEvaluation(flagKey: string, _: boolean, transformedContext: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
     resolveStringEvaluation(flagKey: string, _: string, transformedContext: EvaluationContext, logger: Logger): Promise<ResolutionDetails<string>>;
     resolveNumberEvaluation(flagKey: string, _: number, transformedContext: EvaluationContext, logger: Logger): Promise<ResolutionDetails<number>>;

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

@@ -2,6 +2,16 @@ import { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfe
 import { ServiceClient } from '../../../proto/ts/schema/v1/schema.client';
 import { Config } from '../../configuration';
 import { Service } from '../service';
+interface FlagChange {
+    type: 'delete' | 'write' | 'update';
+    source: string;
+    flagKey: string;
+}
+export interface FlagChangeMessage {
+    flags?: {
+        [key: string]: FlagChange;
+    };
+}
 export declare const Codes: {
     readonly InvalidArgument: "INVALID_ARGUMENT";
     readonly NotFound: "NOT_FOUND";
@@ -9,13 +19,32 @@ export declare const Codes: {
     readonly Unavailable: "UNAVAILABLE";
 };
 export declare class GRPCService implements Service {
-    client: ServiceClient;
-    constructor(config: Config, client?: ServiceClient);
+    private logger?;
+    private _client;
+    private _cache;
+    private _cacheEnabled;
+    private _streamAlive;
+    private _streamConnectAttempt;
+    private _streamConnectBackoff;
+    private _maxEventStreamRetries;
+    private get _cacheActive();
+    readonly streamConnection: Promise<boolean>;
+    constructor(config: Config, client?: ServiceClient, logger?: Logger | undefined);
     resolveBoolean(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
     resolveString(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<string>>;
     resolveNumber(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<number>>;
     resolveObject<T extends JsonValue>(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<T>>;
+    private connectStream;
+    private handleProviderReady;
+    private handleFlagsChanged;
+    private handleError;
+    private handleComplete;
+    private objectParser;
+    private booleanParser;
+    private stringParser;
+    private numberParser;
+    private resolve;
     private convertContext;
-    private onFulfilled;
     private onRejected;
 }
+export {};

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

@@ -1,5 +1,6 @@
 import { EvaluationContext, JsonValue, Logger, ResolutionDetails } from '@openfeature/js-sdk';
 export interface Service {
+    readonly streamConnection: Promise<boolean>;
     resolveBoolean(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<boolean>>;
     resolveString(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<string>>;
     resolveNumber(flagKey: string, context: EvaluationContext, logger: Logger): Promise<ResolutionDetails<number>>;

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

@@ -0,0 +1,46 @@
+import type { RpcTransport } from "@protobuf-ts/runtime-rpc";
+import type { ServiceInfo } from "@protobuf-ts/runtime-rpc";
+import type { FetchAllFlagsResponse } from "./sync_service";
+import type { FetchAllFlagsRequest } from "./sync_service";
+import type { UnaryCall } from "@protobuf-ts/runtime-rpc";
+import type { SyncFlagsResponse } from "./sync_service";
+import type { SyncFlagsRequest } from "./sync_service";
+import type { ServerStreamingCall } from "@protobuf-ts/runtime-rpc";
+import type { RpcOptions } from "@protobuf-ts/runtime-rpc";
+/**
+ * FlagService implements a server streaming to provide realtime flag configurations
+ *
+ * @generated from protobuf service sync.v1.FlagSyncService
+ */
+export interface IFlagSyncServiceClient {
+    /**
+     * @generated from protobuf rpc: SyncFlags(sync.v1.SyncFlagsRequest) returns (stream sync.v1.SyncFlagsResponse);
+     */
+    syncFlags(input: SyncFlagsRequest, options?: RpcOptions): ServerStreamingCall<SyncFlagsRequest, SyncFlagsResponse>;
+    /**
+     * @generated from protobuf rpc: FetchAllFlags(sync.v1.FetchAllFlagsRequest) returns (sync.v1.FetchAllFlagsResponse);
+     */
+    fetchAllFlags(input: FetchAllFlagsRequest, options?: RpcOptions): UnaryCall<FetchAllFlagsRequest, FetchAllFlagsResponse>;
+}
+/**
+ * FlagService implements a server streaming to provide realtime flag configurations
+ *
+ * @generated from protobuf service sync.v1.FlagSyncService
+ */
+export declare class FlagSyncServiceClient implements IFlagSyncServiceClient, ServiceInfo {
+    private readonly _transport;
+    typeName: string;
+    methods: import("@protobuf-ts/runtime-rpc").MethodInfo<any, any>[];
+    options: {
+        [extensionName: string]: import("@protobuf-ts/runtime").JsonValue;
+    };
+    constructor(_transport: RpcTransport);
+    /**
+     * @generated from protobuf rpc: SyncFlags(sync.v1.SyncFlagsRequest) returns (stream sync.v1.SyncFlagsResponse);
+     */
+    syncFlags(input: SyncFlagsRequest, options?: RpcOptions): ServerStreamingCall<SyncFlagsRequest, SyncFlagsResponse>;
+    /**
+     * @generated from protobuf rpc: FetchAllFlags(sync.v1.FetchAllFlagsRequest) returns (sync.v1.FetchAllFlagsResponse);
+     */
+    fetchAllFlags(input: FetchAllFlagsRequest, options?: RpcOptions): UnaryCall<FetchAllFlagsRequest, FetchAllFlagsResponse>;
+}

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

@@ -0,0 +1,183 @@
+import { ServiceType } from "@protobuf-ts/runtime-rpc";
+import type { BinaryWriteOptions } from "@protobuf-ts/runtime";
+import type { IBinaryWriter } from "@protobuf-ts/runtime";
+import type { BinaryReadOptions } from "@protobuf-ts/runtime";
+import type { IBinaryReader } from "@protobuf-ts/runtime";
+import type { PartialMessage } from "@protobuf-ts/runtime";
+import { MessageType } from "@protobuf-ts/runtime";
+/**
+ * SyncFlagsRequest is the request initiating the sever-streaming rpc. Flagd sends this request, acting as the client
+ *
+ * @generated from protobuf message sync.v1.SyncFlagsRequest
+ */
+export interface SyncFlagsRequest {
+    /**
+     * Optional: A unique identifier for flagd(grpc client) initiating the request. The server implementations may
+     * utilize this identifier to uniquely identify, validate(ex:- enforce authentication/authorization) and filter
+     * flag configurations that it can expose to this request. This field is intended to be optional. However server
+     * implementations may enforce it.
+     *    ex:- provider_id: flagd-weatherapp-sidecar
+     *
+     * @generated from protobuf field: string provider_id = 1;
+     */
+    providerId: string;
+    /**
+     * Optional: A selector for the flag configuration request. The server implementation may utilize this to select
+     * flag configurations from a collection, select the source of the flag or combine this to any desired underlying
+     * filtering mechanism.
+     *    ex:- selector: 'source=database,app=weatherapp'
+     *
+     * @generated from protobuf field: string selector = 2;
+     */
+    selector: string;
+}
+/**
+ * SyncFlagsResponse is the server response containing feature flag configurations and the state
+ *
+ * @generated from protobuf message sync.v1.SyncFlagsResponse
+ */
+export interface SyncFlagsResponse {
+    /**
+     * flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json
+     *
+     * @generated from protobuf field: string flag_configuration = 1;
+     */
+    flagConfiguration: string;
+    /**
+     * State conveying the operation to be performed by flagd. See the descriptions of SyncState for an explanation of
+     * supported values
+     *
+     * @generated from protobuf field: sync.v1.SyncState state = 2;
+     */
+    state: SyncState;
+}
+/**
+ * FetchAllFlagsRequest is the request to fetch all flags. Flagd sends this request as the client in order to resync its internal state
+ *
+ * @generated from protobuf message sync.v1.FetchAllFlagsRequest
+ */
+export interface FetchAllFlagsRequest {
+    /**
+     * Optional: A unique identifier for flagd(grpc client) initiating the request. The server implementations may
+     * utilize this identifier to uniquely identify, validate(ex:- enforce authentication/authorization) and filter
+     * flag configurations that it can expose to this request. This field is intended to be optional. However server
+     * implementations may enforce it.
+     *    ex:- provider_id: flagd-weatherapp-sidecar
+     *
+     * @generated from protobuf field: string provider_id = 1;
+     */
+    providerId: string;
+    /**
+     * Optional: A selector for the flag configuration request. The server implementation may utilize this to select
+     * flag configurations from a collection, select the source of the flag or combine this to any desired underlying
+     * filtering mechanism.
+     *    ex:- selector: 'source=database,app=weatherapp'
+     *
+     * @generated from protobuf field: string selector = 2;
+     */
+    selector: string;
+}
+/**
+ *  FetchAllFlagsResponse is the server response containing feature flag configurations
+ *
+ * @generated from protobuf message sync.v1.FetchAllFlagsResponse
+ */
+export interface FetchAllFlagsResponse {
+    /**
+     * flagd feature flag configuration. Must be validated to schema - https://raw.githubusercontent.com/open-feature/schemas/main/json/flagd-definitions.json
+     *
+     * @generated from protobuf field: string flag_configuration = 1;
+     */
+    flagConfiguration: string;
+}
+/**
+ * SyncState conveys the state of the payload. These states are related to flagd isync.go type definitions but
+ * contains extras to optimize grpc use case. Refer - https://github.com/open-feature/flagd/blob/main/pkg/sync/isync.go
+ *
+ * @generated from protobuf enum sync.v1.SyncState
+ */
+export declare enum SyncState {
+    /**
+     * Value is ignored by the listening flagd
+     *
+     * @generated from protobuf enum value: SYNC_STATE_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * All the flags matching the request. This is the default response and other states can be ignored
+     * by the implementation. Flagd internally replaces all existing flags for this response state.
+     *
+     * @generated from protobuf enum value: SYNC_STATE_ALL = 1;
+     */
+    ALL = 1,
+    /**
+     * Convey an addition of a flag. Flagd internally handles this by combining new flags with existing ones
+     *
+     * @generated from protobuf enum value: SYNC_STATE_ADD = 2;
+     */
+    ADD = 2,
+    /**
+     * Convey an update of a flag. Flagd internally attempts to update if the updated flag already exist OR if it does not,
+     * it will get added
+     *
+     * @generated from protobuf enum value: SYNC_STATE_UPDATE = 3;
+     */
+    UPDATE = 3,
+    /**
+     * Convey a deletion of a flag. Flagd internally removes the flag
+     *
+     * @generated from protobuf enum value: SYNC_STATE_DELETE = 4;
+     */
+    DELETE = 4,
+    /**
+     * Optional server ping to check client connectivity. Handling is ignored by flagd and is to merely support live check
+     *
+     * @generated from protobuf enum value: SYNC_STATE_PING = 5;
+     */
+    PING = 5
+}
+declare class SyncFlagsRequest$Type extends MessageType<SyncFlagsRequest> {
+    constructor();
+    create(value?: PartialMessage<SyncFlagsRequest>): SyncFlagsRequest;
+    internalBinaryRead(reader: IBinaryReader, length: number, options: BinaryReadOptions, target?: SyncFlagsRequest): SyncFlagsRequest;
+    internalBinaryWrite(message: SyncFlagsRequest, writer: IBinaryWriter, options: BinaryWriteOptions): IBinaryWriter;
+}
+/**
+ * @generated MessageType for protobuf message sync.v1.SyncFlagsRequest
+ */
+export declare const SyncFlagsRequest: SyncFlagsRequest$Type;
+declare class SyncFlagsResponse$Type extends MessageType<SyncFlagsResponse> {
+    constructor();
+    create(value?: PartialMessage<SyncFlagsResponse>): SyncFlagsResponse;
+    internalBinaryRead(reader: IBinaryReader, length: number, options: BinaryReadOptions, target?: SyncFlagsResponse): SyncFlagsResponse;
+    internalBinaryWrite(message: SyncFlagsResponse, writer: IBinaryWriter, options: BinaryWriteOptions): IBinaryWriter;
+}
+/**
+ * @generated MessageType for protobuf message sync.v1.SyncFlagsResponse
+ */
+export declare const SyncFlagsResponse: SyncFlagsResponse$Type;
+declare class FetchAllFlagsRequest$Type extends MessageType<FetchAllFlagsRequest> {
+    constructor();
+    create(value?: PartialMessage<FetchAllFlagsRequest>): FetchAllFlagsRequest;
+    internalBinaryRead(reader: IBinaryReader, length: number, options: BinaryReadOptions, target?: FetchAllFlagsRequest): FetchAllFlagsRequest;
+    internalBinaryWrite(message: FetchAllFlagsRequest, writer: IBinaryWriter, options: BinaryWriteOptions): IBinaryWriter;
+}
+/**
+ * @generated MessageType for protobuf message sync.v1.FetchAllFlagsRequest
+ */
+export declare const FetchAllFlagsRequest: FetchAllFlagsRequest$Type;
+declare class FetchAllFlagsResponse$Type extends MessageType<FetchAllFlagsResponse> {
+    constructor();
+    create(value?: PartialMessage<FetchAllFlagsResponse>): FetchAllFlagsResponse;
+    internalBinaryRead(reader: IBinaryReader, length: number, options: BinaryReadOptions, target?: FetchAllFlagsResponse): FetchAllFlagsResponse;
+    internalBinaryWrite(message: FetchAllFlagsResponse, writer: IBinaryWriter, options: BinaryWriteOptions): IBinaryWriter;
+}
+/**
+ * @generated MessageType for protobuf message sync.v1.FetchAllFlagsResponse
+ */
+export declare const FetchAllFlagsResponse: FetchAllFlagsResponse$Type;
+/**
+ * @generated ServiceType for protobuf service sync.v1.FlagSyncService
+ */
+export declare const FlagSyncService: ServiceType;
+export {};