chore: unknown flags

Author: nunogois

src/lib/db/index.ts

@@ -65,6 +65,7 @@ import { UserUnsubscribeStore } from '../features/user-subscriptions/user-unsubs
 import { UserSubscriptionsReadModel } from '../features/user-subscriptions/user-subscriptions-read-model';
 import { UniqueConnectionStore } from '../features/unique-connection/unique-connection-store';
 import { UniqueConnectionReadModel } from '../features/unique-connection/unique-connection-read-model';
+import { UnknownFlagsStore } from '../features/metrics/unknown-flags/unknown-flags-store';
 
 export const createStores = (
     config: IUnleashConfig,
@@ -201,6 +202,7 @@ export const createStores = (
         releasePlanMilestoneStore: new ReleasePlanMilestoneStore(db, config),
         releasePlanMilestoneStrategyStore:
             new ReleasePlanMilestoneStrategyStore(db, config),
+        unknownFlagsStore: new UnknownFlagsStore(db),
     };
 };
 

src/lib/features/metrics/client-metrics/metrics-service-v2.test.ts

@@ -11,6 +11,7 @@ import type {
 } from '../../../../lib/types';
 import { endOfDay, startOfHour, subDays, subHours } from 'date-fns';
 import type { IClientMetricsEnv } from './client-metrics-store-v2-type';
+import { UnknownFlagsService } from '../unknown-flags/unknown-flags-service';
 
 function initClientMetrics(flagEnabled = true) {
     const stores = createStores();
@@ -35,8 +36,19 @@ function initClientMetrics(flagEnabled = true) {
         config,
     );
     lastSeenService.updateLastSeen = jest.fn();
+    const unknownFlagsService = new UnknownFlagsService(
+        {
+            unknownFlagsStore: stores.unknownFlagsStore,
+        },
+        config,
+    );
 
-    const service = new ClientMetricsServiceV2(stores, config, lastSeenService);
+    const service = new ClientMetricsServiceV2(
+        stores,
+        config,
+        lastSeenService,
+        unknownFlagsService,
+    );
     return { clientMetricsService: service, eventBus, lastSeenService };
 }
 
@@ -161,10 +173,12 @@ test('get daily client metrics for a toggle', async () => {
         getLogger() {},
     } as unknown as IUnleashConfig;
     const lastSeenService = {} as LastSeenService;
+    const unknownFlagsService = {} as UnknownFlagsService;
     const service = new ClientMetricsServiceV2(
         { clientMetricsStoreV2 },
         config,
         lastSeenService,
+        unknownFlagsService,
     );
 
     const metrics = await service.getClientMetricsForToggle('feature', 3 * 24);
@@ -217,10 +231,12 @@ test('get hourly client metrics for a toggle', async () => {
         getLogger() {},
     } as unknown as IUnleashConfig;
     const lastSeenService = {} as LastSeenService;
+    const unknownFlagsService = {} as UnknownFlagsService;
     const service = new ClientMetricsServiceV2(
         { clientMetricsStoreV2 },
         config,
         lastSeenService,
+        unknownFlagsService,
     );
 
     const metrics = await service.getClientMetricsForToggle('feature', 2);
@@ -287,10 +303,12 @@ const setupMetricsService = ({
         },
     } as unknown as IUnleashConfig;
     const lastSeenService = {} as LastSeenService;
+    const unknownFlagsService = {} as UnknownFlagsService;
     const service = new ClientMetricsServiceV2(
         { clientMetricsStoreV2 },
         config,
         lastSeenService,
+        unknownFlagsService,
     );
     return {
         service,

src/lib/features/metrics/client-metrics/metrics-service-v2.ts

@@ -26,6 +26,10 @@ import {
 import type { ClientMetricsSchema } from '../../../../lib/openapi';
 import { nameSchema } from '../../../schema/feature-schema';
 import memoizee from 'memoizee';
+import {
+    MAX_UNKNOWN_FLAGS,
+    type UnknownFlagsService,
+} from '../unknown-flags/unknown-flags-service';
 
 export default class ClientMetricsServiceV2 {
     private config: IUnleashConfig;
@@ -36,6 +40,8 @@ export default class ClientMetricsServiceV2 {
 
     private lastSeenService: LastSeenService;
 
+    private unknownFlagsService: UnknownFlagsService;
+
     private flagResolver: Pick<IFlagResolver, 'isEnabled' | 'getVariant'>;
 
     private logger: Logger;
@@ -46,9 +52,11 @@ export default class ClientMetricsServiceV2 {
         { clientMetricsStoreV2 }: Pick<IUnleashStores, 'clientMetricsStoreV2'>,
         config: IUnleashConfig,
         lastSeenService: LastSeenService,
+        unknownFlagsService: UnknownFlagsService,
     ) {
         this.clientMetricsStoreV2 = clientMetricsStoreV2;
         this.lastSeenService = lastSeenService;
+        this.unknownFlagsService = unknownFlagsService;
         this.config = config;
         this.logger = config.getLogger(
             '/services/client-metrics/client-metrics-service-v2.ts',
@@ -113,25 +121,43 @@ export default class ClientMetricsServiceV2 {
         }
     }
 
-    async filterExistingToggleNames(toggleNames: string[]): Promise<string[]> {
+    async filterExistingToggleNames(toggleNames: string[]): Promise<{
+        validatedToggleNames: string[];
+        unknownToggleNames: string[];
+    }> {
+        let unknownToggleNames: string[] = [];
+
         if (this.flagResolver.isEnabled('filterExistingFlagNames')) {
             try {
                 const validNames = await this.cachedFeatureNames();
 
                 const existingNames = toggleNames.filter((name) =>
                     validNames.includes(name),
                 );
+                if (this.flagResolver.isEnabled('reportUnknownFlags')) {
+                    unknownToggleNames = toggleNames
+                        .filter((name) => !existingNames.includes(name))
+                        .slice(0, MAX_UNKNOWN_FLAGS);
+                }
                 if (existingNames.length !== toggleNames.length) {
                     this.logger.info(
                         `Filtered out ${toggleNames.length - existingNames.length} toggles with non-existing names`,
                     );
                 }
-                return this.filterValidToggleNames(existingNames);
+
+                const validatedToggleNames =
+                    await this.filterValidToggleNames(existingNames);
+
+                return { validatedToggleNames, unknownToggleNames };
             } catch (e) {
                 this.logger.error(e);
             }
         }
-        return this.filterValidToggleNames(toggleNames);
+
+        const validatedToggleNames =
+            await this.filterValidToggleNames(toggleNames);
+
+        return { validatedToggleNames, unknownToggleNames };
     }
 
     async filterValidToggleNames(toggleNames: string[]): Promise<string[]> {
@@ -181,7 +207,7 @@ export default class ClientMetricsServiceV2 {
                 ),
         );
 
-        const validatedToggleNames =
+        const { validatedToggleNames, unknownToggleNames } =
             await this.filterExistingToggleNames(toggleNames);
 
         this.logger.debug(
@@ -204,6 +230,15 @@ export default class ClientMetricsServiceV2 {
             this.config.eventBus.emit(CLIENT_REGISTER, heartbeatEvent);
         }
 
+        if (unknownToggleNames.length > 0) {
+            const unknownFlags = unknownToggleNames.map((name) => ({
+                name,
+                appName: value.appName,
+                seenAt: value.bucket.stop,
+            }));
+            this.unknownFlagsService.register(unknownFlags);
+        }
+
         if (validatedToggleNames.length > 0) {
             const clientMetrics: IClientMetricsEnv[] = validatedToggleNames.map(
                 (name) => ({

src/lib/features/metrics/unknown-flags/fake-unknown-flags-store.ts

@@ -0,0 +1,32 @@
+import type { IUnknownFlagsStore, UnknownFlag } from './unknown-flags-store';
+
+export class FakeUnknownFlagsStore implements IUnknownFlagsStore {
+    private unknownFlagRecord: Record<string, UnknownFlag> = {};
+
+    async replaceAll(flags: UnknownFlag[]): Promise<void> {
+        this.unknownFlagRecord = {};
+        for (const flag of flags) {
+            this.unknownFlagRecord[flag.name] = flag;
+        }
+    }
+
+    async getAll(): Promise<UnknownFlag[]> {
+        return Object.values(this.unknownFlagRecord);
+    }
+
+    async clear(hoursAgo: number): Promise<void> {
+        const now = new Date();
+        for (const flag of Object.values(this.unknownFlagRecord)) {
+            if (
+                flag.seenAt.getTime() <
+                now.getTime() - hoursAgo * 60 * 60 * 1000
+            ) {
+                delete this.unknownFlagRecord[flag.name];
+            }
+        }
+    }
+
+    async deleteAll(): Promise<void> {
+        this.unknownFlagRecord = {};
+    }
+}

src/lib/features/metrics/unknown-flags/unknown-flags-controller.ts

@@ -0,0 +1,70 @@
+import type { Response } from 'express';
+import {
+    unknownFlagsResponseSchema,
+    type UnknownFlagsResponseSchema,
+} from '../../../openapi';
+import { createResponseSchema } from '../../../openapi/util/create-response-schema';
+import Controller from '../../../routes/controller';
+import type { IAuthRequest } from '../../../routes/unleash-types';
+import type { OpenApiService } from '../../../services/openapi-service';
+import type { IFlagResolver } from '../../../types/experimental';
+import type { IUnleashConfig } from '../../../types/option';
+import { NONE } from '../../../types/permissions';
+import { serializeDates } from '../../../types/serialize-dates';
+import type { IUnleashServices } from '../../../types/services';
+import type { UnknownFlagsService } from './unknown-flags-service';
+
+export default class UnknownFlagsController extends Controller {
+    private unknownFlagsService: UnknownFlagsService;
+
+    private flagResolver: IFlagResolver;
+
+    private openApiService: OpenApiService;
+
+    constructor(
+        config: IUnleashConfig,
+        {
+            unknownFlagsService,
+            openApiService,
+        }: Pick<IUnleashServices, 'unknownFlagsService' | 'openApiService'>,
+    ) {
+        super(config);
+        this.unknownFlagsService = unknownFlagsService;
+        this.flagResolver = config.flagResolver;
+        this.openApiService = openApiService;
+
+        this.route({
+            method: 'get',
+            path: '',
+            handler: this.getUnknownFlags,
+            permission: NONE,
+            middleware: [
+                openApiService.validPath({
+                    operationId: 'getUnknownFlags',
+                    tags: ['Unstable'],
+                    summary: 'Get latest reported unknown flag names',
+                    description:
+                        'Returns a list of unknown flag names reported in the last 24 hours, if any. Maximum of 10.',
+                    responses: {
+                        200: createResponseSchema('unknownFlagsResponseSchema'),
+                    },
+                }),
+            ],
+        });
+    }
+
+    async getUnknownFlags(
+        req: IAuthRequest,
+        res: Response<UnknownFlagsResponseSchema>,
+    ): Promise<void> {
+        const unknownFlags =
+            await this.unknownFlagsService.getGroupedUnknownFlags();
+
+        this.openApiService.respondWithValidation(
+            200,
+            res,
+            unknownFlagsResponseSchema.$id,
+            serializeDates({ unknownFlags }),
+        );
+    }
+}

src/lib/features/metrics/unknown-flags/unknown-flags-service.ts

@@ -0,0 +1,101 @@
+import type { Logger } from '../../../logger';
+import type { IUnknownFlagsStore, IUnleashConfig } from '../../../types';
+import type { IUnleashStores } from '../../../types';
+import type { UnknownFlag } from './unknown-flags-store';
+
+export const MAX_UNKNOWN_FLAGS = 10;
+
+export class UnknownFlagsService {
+    private config: IUnleashConfig;
+
+    private logger: Logger;
+
+    private unknownFlagsStore: IUnknownFlagsStore;
+
+    private unknownFlagsCache: Map<string, UnknownFlag>;
+
+    constructor(
+        { unknownFlagsStore }: Pick<IUnleashStores, 'unknownFlagsStore'>,
+        config: IUnleashConfig,
+    ) {
+        this.unknownFlagsStore = unknownFlagsStore;
+        this.config = config;
+        this.logger = config.getLogger(
+            '/features/metrics/unknown-flags/unknown-flags-service.ts',
+        );
+        this.unknownFlagsCache = new Map<string, UnknownFlag>();
+    }
+
+    private getKey(flag: UnknownFlag) {
+        return `${flag.name}:${flag.appName}`;
+    }
+
+    register(unknownFlags: UnknownFlag[]) {
+        for (const flag of unknownFlags) {
+            const key = this.getKey(flag);
+
+            if (this.unknownFlagsCache.has(key)) {
+                this.unknownFlagsCache.set(key, flag);
+                continue;
+            }
+
+            if (this.unknownFlagsCache.size >= MAX_UNKNOWN_FLAGS) {
+                const oldestKey = [...this.unknownFlagsCache.entries()].sort(
+                    (a, b) => a[1].seenAt.getTime() - b[1].seenAt.getTime(),
+                )[0][0];
+                this.unknownFlagsCache.delete(oldestKey);
+            }
+
+            this.unknownFlagsCache.set(key, flag);
+        }
+    }
+
+    async flush(): Promise<void> {
+        if (this.unknownFlagsCache.size === 0) return;
+
+        const existing = await this.unknownFlagsStore.getAll();
+        const cached = Array.from(this.unknownFlagsCache.values());
+
+        const merged = [...existing, ...cached];
+        const mergedMap = new Map<string, UnknownFlag>();
+
+        for (const flag of merged) {
+            const key = this.getKey(flag);
+            const existing = mergedMap.get(key);
+            if (!existing || flag.seenAt > existing.seenAt) {
+                mergedMap.set(key, flag);
+            }
+        }
+
+        const latest = Array.from(mergedMap.values())
+            .sort((a, b) => b.seenAt.getTime() - a.seenAt.getTime())
+            .slice(0, MAX_UNKNOWN_FLAGS);
+
+        await this.unknownFlagsStore.replaceAll(latest);
+        this.unknownFlagsCache.clear();
+    }
+
+    async getGroupedUnknownFlags(): Promise<
+        { name: string; reportedBy: { appName: string; seenAt: Date }[] }[]
+    > {
+        const unknownFlags = await this.unknownFlagsStore.getAll();
+
+        const grouped = new Map<string, { appName: string; seenAt: Date }[]>();
+
+        for (const { name, appName, seenAt } of unknownFlags) {
+            if (!grouped.has(name)) {
+                grouped.set(name, []);
+            }
+            grouped.get(name)!.push({ appName, seenAt });
+        }
+
+        return Array.from(grouped.entries()).map(([name, reportedBy]) => ({
+            name,
+            reportedBy,
+        }));
+    }
+
+    async clear(hoursAgo: number) {
+        return this.unknownFlagsStore.clear(hoursAgo);
+    }
+}