π Open source, privacy-first web analytics β a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
CE support
Blue Mouse365392d6eb8d
diff --git a/backend/apps/community/src/app.module.ts b/backend/apps/community/src/app.module.tsindex c08f836e4..af68678bd 100644--- a/backend/apps/community/src/app.module.ts+++ b/backend/apps/community/src/app.module.ts@@ -11,6 +11,7 @@ import { ProjectModule } from './project/project.module'import { TaskManagerModule } from './task-manager/task-manager.module'import { PingModule } from './ping/ping.module'import { GoalModule } from './goal/goal.module'+import { FeatureFlagModule } from './feature-flag/feature-flag.module'import { getI18nConfig } from './configs'import { AuthModule } from './auth/auth.module'import { AppController } from './app.controller'@@ -66,6 +67,7 @@ const modules = [AnalyticsModule,PingModule,GoalModule,+ FeatureFlagModule,AuthModule,]diff --git a/backend/apps/community/src/feature-flag/dto/feature-flag.dto.ts b/backend/apps/community/src/feature-flag/dto/feature-flag.dto.tsnew file mode 100644index 000000000..15152a641--- /dev/null+++ b/backend/apps/community/src/feature-flag/dto/feature-flag.dto.ts@@ -0,0 +1,245 @@+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger'+import {+ IsString,+ IsOptional,+ IsEnum,+ IsNumber,+ IsBoolean,+ IsArray,+ ValidateNested,+ Min,+ Max,+ MaxLength,+ Matches,+} from 'class-validator'+import { Type } from 'class-transformer'+import { FeatureFlagType, TargetingRule } from '../entity/feature-flag.entity'++export class TargetingRuleDto implements TargetingRule {+ @ApiProperty({+ description: 'Column/attribute to filter on (cc, dv, br, os, pg, etc.)',+ })+ @IsString()+ column: string++ @ApiProperty({ description: 'Value to match against' })+ @IsString()+ filter: string++ @ApiProperty({+ description: 'If true, excludes matches; if false, includes matches',+ })+ @IsBoolean()+ isExclusive: boolean+}++export class CreateFeatureFlagDto {+ @ApiProperty({ description: 'Project ID the flag belongs to' })+ @IsString()+ pid: string++ @ApiProperty({+ description: 'Unique key for the feature flag (kebab-case recommended)',+ })+ @IsString()+ @MaxLength(100)+ @Matches(/^[a-zA-Z0-9_-]+$/, {+ message:+ 'Key must contain only alphanumeric characters, underscores, and hyphens',+ })+ key: string++ @ApiPropertyOptional({+ description: 'Optional description of what this flag controls',+ })+ @IsOptional()+ @IsString()+ @MaxLength(500)+ description?: string++ @ApiPropertyOptional({+ enum: FeatureFlagType,+ description: 'Type of feature flag',+ default: FeatureFlagType.BOOLEAN,+ })+ @IsOptional()+ @IsEnum(FeatureFlagType)+ flagType?: FeatureFlagType++ @ApiPropertyOptional({+ description:+ 'Percentage of users to enable for (0-100), used when flagType is rollout',+ default: 100,+ })+ @IsOptional()+ @IsNumber()+ @Min(0)+ @Max(100)+ rolloutPercentage?: number++ @ApiPropertyOptional({+ type: [TargetingRuleDto],+ description:+ 'Array of targeting rules to filter which visitors see this flag',+ })+ @IsOptional()+ @IsArray()+ @ValidateNested({ each: true })+ @Type(() => TargetingRuleDto)+ targetingRules?: TargetingRuleDto[]++ @ApiPropertyOptional({+ description: 'Whether the flag is enabled',+ default: true,+ })+ @IsOptional()+ @IsBoolean()+ enabled?: boolean+}++export class UpdateFeatureFlagDto {+ @ApiPropertyOptional({ description: 'Unique key for the feature flag' })+ @IsOptional()+ @IsString()+ @MaxLength(100)+ @Matches(/^[a-zA-Z0-9_-]+$/, {+ message:+ 'Key must contain only alphanumeric characters, underscores, and hyphens',+ })+ key?: string++ @ApiPropertyOptional({+ description: 'Description of what this flag controls',+ })+ @IsOptional()+ @IsString()+ @MaxLength(500)+ description?: string | null++ @ApiPropertyOptional({+ enum: FeatureFlagType,+ description: 'Type of feature flag',+ })+ @IsOptional()+ @IsEnum(FeatureFlagType)+ flagType?: FeatureFlagType++ @ApiPropertyOptional({+ description: 'Percentage of users to enable for (0-100)',+ })+ @IsOptional()+ @IsNumber()+ @Min(0)+ @Max(100)+ rolloutPercentage?: number++ @ApiPropertyOptional({+ type: [TargetingRuleDto],+ description: 'Array of targeting rules',+ })+ @IsOptional()+ @IsArray()+ @ValidateNested({ each: true })+ @Type(() => TargetingRuleDto)+ targetingRules?: TargetingRuleDto[] | null++ @ApiPropertyOptional({ description: 'Whether the flag is enabled' })+ @IsOptional()+ @IsBoolean()+ enabled?: boolean+}++export class EvaluateFeatureFlagsDto {+ @ApiProperty({ description: 'Project ID to evaluate flags for' })+ @IsString()+ pid: string++ @ApiPropertyOptional({+ description:+ 'Optional profile ID for long-term user tracking. If not provided, an anonymous profile ID will be generated based on IP and user agent.',+ })+ @IsOptional()+ @IsString()+ profileId?: string+}++export class FeatureFlagDto {+ @ApiProperty()+ id: string++ @ApiProperty()+ key: string++ @ApiProperty()+ description: string | null++ @ApiProperty({ enum: FeatureFlagType })+ flagType: FeatureFlagType++ @ApiProperty()+ rolloutPercentage: number++ @ApiProperty({ type: [TargetingRuleDto] })+ targetingRules: TargetingRuleDto[] | null++ @ApiProperty()+ enabled: boolean++ @ApiProperty()+ pid: string++ @ApiProperty()+ created: Date+}++export class FeatureFlagStatsDto {+ @ApiProperty({ description: 'Total number of evaluations' })+ evaluations: number++ @ApiProperty({ description: 'Number of unique profiles' })+ profileCount: number++ @ApiProperty({ description: 'Number of times flag returned true' })+ trueCount: number++ @ApiProperty({ description: 'Number of times flag returned false' })+ falseCount: number++ @ApiProperty({ description: 'Percentage of true evaluations' })+ truePercentage: number+}++export class EvaluatedFlagsResponseDto {+ @ApiProperty({+ description: 'Map of flag keys to their evaluated boolean values',+ example: { 'new-checkout': true, 'dark-mode': false },+ })+ flags: Record<string, boolean>+}++export class FeatureFlagProfileDto {+ @ApiProperty({ description: 'Profile ID' })+ profileId: string++ @ApiProperty({+ description: 'Whether profile is identified (has user-provided ID)',+ })+ isIdentified: boolean++ @ApiProperty({ description: 'Last evaluation result' })+ lastResult: boolean++ @ApiProperty({ description: 'Total number of evaluations for this profile' })+ evaluationCount: number++ @ApiProperty({ description: 'Most recent evaluation timestamp' })+ lastEvaluated: string+}++export class FeatureFlagProfilesResponseDto {+ @ApiProperty({ type: [FeatureFlagProfileDto] })+ profiles: FeatureFlagProfileDto[]++ @ApiProperty({ description: 'Total number of profiles' })+ total: number+}diff --git a/backend/apps/community/src/feature-flag/entity/feature-flag.entity.ts b/backend/apps/community/src/feature-flag/entity/feature-flag.entity.tsnew file mode 100644index 000000000..19c40a9a5--- /dev/null+++ b/backend/apps/community/src/feature-flag/entity/feature-flag.entity.ts@@ -0,0 +1,34 @@+export enum FeatureFlagType {+ BOOLEAN = 'boolean',+ ROLLOUT = 'rollout',+}++export interface TargetingRule {+ column: string // cc, dv, br, os, pg, etc.+ filter: string // value to match+ isExclusive: boolean // true = exclude, false = include+}++export interface FeatureFlag {+ id: string+ key: string+ description: string | null+ flagType: FeatureFlagType+ rolloutPercentage: number+ targetingRules: TargetingRule[] | null+ enabled: boolean+ projectId: string+ created: string+}++export interface ClickhouseFeatureFlag {+ id: string+ key: string+ description: string | null+ flagType: string+ rolloutPercentage: number+ targetingRules: string | null // JSON string in ClickHouse+ enabled: number // Int8 in ClickHouse+ projectId: string+ created: string+}diff --git a/backend/apps/community/src/feature-flag/feature-flag.controller.ts b/backend/apps/community/src/feature-flag/feature-flag.controller.tsnew file mode 100644index 000000000..a8956ae75--- /dev/null+++ b/backend/apps/community/src/feature-flag/feature-flag.controller.ts@@ -0,0 +1,639 @@+import {+ Controller,+ Get,+ Put,+ Delete,+ Query,+ Param,+ Body,+ NotFoundException,+ Post,+ BadRequestException,+ ParseIntPipe,+ Headers,+ Ip,+} from '@nestjs/common'+import {+ ApiTags,+ ApiResponse,+ ApiBearerAuth,+ ApiOperation,+} from '@nestjs/swagger'+import _isEmpty from 'lodash/isEmpty'+import _map from 'lodash/map'+import _pick from 'lodash/pick'+import _round from 'lodash/round'++import { ProjectService } from '../project/project.service'+import { AppLoggerService } from '../logger/logger.service'+import {+ AnalyticsService,+ getLowestPossibleTimeBucket,+} from '../analytics/analytics.service'+import { Auth } from '../auth/decorators'+import { CurrentUserId } from '../auth/decorators/current-user-id.decorator'+import { FeatureFlag } from './entity/feature-flag.entity'+import {+ CreateFeatureFlagDto,+ UpdateFeatureFlagDto,+ EvaluateFeatureFlagsDto,+ FeatureFlagDto,+ FeatureFlagStatsDto,+ EvaluatedFlagsResponseDto,+ FeatureFlagProfilesResponseDto,+} from './dto/feature-flag.dto'+import { FeatureFlagService } from './feature-flag.service'+import { clickhouse } from '../common/integrations/clickhouse'+import { getIPFromHeaders, getGeoDetails } from '../common/utils'++const FEATURE_FLAGS_MAXIMUM = 50 // Maximum feature flags per project++@ApiTags('Feature Flag')+@Controller(['feature-flag', 'v1/feature-flag'])+export class FeatureFlagController {+ constructor(+ private readonly featureFlagService: FeatureFlagService,+ private readonly projectService: ProjectService,+ private readonly logger: AppLoggerService,+ private readonly analyticsService: AnalyticsService,+ ) {}++ // NOTE: More specific routes must come before generic parameter routes+ // e.g., /project/:projectId must be before /:flagId++ @ApiBearerAuth()+ @Get('/project/:projectId')+ @Auth()+ @ApiResponse({ status: 200, type: [FeatureFlagDto] })+ @ApiOperation({ summary: 'Get all feature flags for a project' })+ async getProjectFeatureFlags(+ @CurrentUserId() userId: string,+ @Param('projectId') projectId: string,+ @Query('take', new ParseIntPipe({ optional: true })) take?: number,+ @Query('skip', new ParseIntPipe({ optional: true })) skip?: number,+ ) {+ this.logger.log(+ { userId, projectId, take, skip },+ 'GET /feature-flag/project/:projectId',+ )++ const project = await this.projectService.getFullProject(projectId)++ if (_isEmpty(project)) {+ throw new NotFoundException('Project not found')+ }++ this.projectService.allowedToView(project, userId)++ const result = await this.featureFlagService.paginate(+ { take, skip },+ projectId,+ )++ result.results = _map(result.results, flag => ({+ ...flag,+ pid: flag.projectId,+ })) as any++ return result+ }++ @ApiBearerAuth()+ @Get('/:flagId')+ @Auth()+ @ApiResponse({ status: 200, type: FeatureFlagDto })+ @ApiOperation({ summary: 'Get a feature flag by ID' })+ async getFeatureFlag(+ @CurrentUserId() userId: string,+ @Param('flagId') flagId: string,+ ) {+ this.logger.log({ userId, flagId }, 'GET /feature-flag/:flagId')++ const flag = await this.featureFlagService.findOne(flagId)++ if (_isEmpty(flag)) {+ throw new NotFoundException('Feature flag not found')+ }++ const project = await this.projectService.getFullProject(flag.projectId)++ this.projectService.allowedToView(project, userId)++ return {+ ...flag,+ pid: flag.projectId,+ }+ }++ @ApiBearerAuth()+ @Post('/')+ @Auth()+ @ApiResponse({ status: 201, type: FeatureFlagDto })+ @ApiOperation({ summary: 'Create a new feature flag' })+ async createFeatureFlag(+ @Body() flagDto: CreateFeatureFlagDto,+ @CurrentUserId() uid: string,+ ) {+ this.logger.log({ uid, pid: flagDto.pid }, 'POST /feature-flag')++ const project = await this.projectService.getFullProject(flagDto.pid)++ if (_isEmpty(project)) {+ throw new NotFoundException('Project not found')+ }++ this.projectService.allowedToManage(+ project,+ uid,+ 'You are not allowed to add feature flags to this project',+ )++ const flagsCount = await this.featureFlagService.count(flagDto.pid)++ if (flagsCount >= FEATURE_FLAGS_MAXIMUM) {+ throw new BadRequestException(+ `You cannot create more than ${FEATURE_FLAGS_MAXIMUM} feature flags per project.`,+ )+ }++ // Check for duplicate key+ const existingFlag = await this.featureFlagService.findByKey(+ flagDto.pid,+ flagDto.key,+ )++ if (existingFlag) {+ throw new BadRequestException(+ `A feature flag with key "${flagDto.key}" already exists in this project`,+ )+ }++ try {+ const newFlag = await this.featureFlagService.create({+ key: flagDto.key,+ description: flagDto.description || null,+ flagType: flagDto.flagType,+ rolloutPercentage: flagDto.rolloutPercentage ?? 100,+ targetingRules: flagDto.targetingRules || null,+ enabled: flagDto.enabled ?? true,+ projectId: flagDto.pid,+ })++ return {+ ...newFlag,+ pid: flagDto.pid,+ }+ } catch (reason) {+ this.logger.error({ reason }, 'Error while creating feature flag')+ throw new BadRequestException(+ 'Error occurred while creating feature flag',+ )+ }+ }++ @Post('/evaluate')+ @ApiResponse({ status: 200, type: EvaluatedFlagsResponseDto })+ @ApiOperation({+ summary: 'Evaluate feature flags for a visitor (public endpoint)',+ description:+ 'Evaluates all enabled feature flags for a project based on visitor attributes derived from the request. Does not require authentication.',+ })+ async evaluateFlags(+ @Body() evaluateDto: EvaluateFeatureFlagsDto,+ @Headers() headers: Record<string, string>,+ @Ip() reqIP: string,+ ) {+ this.logger.log({ pid: evaluateDto.pid }, 'POST /feature-flag/evaluate')++ const project = await this.projectService.getRedisProject(evaluateDto.pid)++ if (_isEmpty(project)) {+ throw new NotFoundException('Project not found')+ }++ if (!project.active) {+ throw new BadRequestException('Project is not active')+ }++ const flags = await this.featureFlagService.findEnabledByProject(+ evaluateDto.pid,+ )++ // Derive attributes from request headers (like analytics does)+ const ip = getIPFromHeaders(headers) || reqIP || ''+ const userAgent = headers['user-agent'] || ''+ const { country, city, region } = getGeoDetails(ip)+ const { deviceType, browserName, osName } =+ await this.analyticsService.getRequestInformation(headers)++ // Generate profileId using the same method as analytics:+ // - If user provides profileId, use it (with usr_ prefix)+ // - Otherwise, generate anonymous profileId from monthly salt + ip + useragent (with anon_ prefix)+ const profileId = await this.analyticsService.generateProfileId(+ evaluateDto.pid,+ userAgent,+ ip,+ evaluateDto.profileId,+ )++ // Build attributes from derived values+ const derivedAttributes: Record<string, string> = {}++ if (country) {+ derivedAttributes.cc = country+ }+ if (city) {+ derivedAttributes.ct = city+ }+ if (region) {+ derivedAttributes.rg = region+ }+ if (deviceType) {+ derivedAttributes.dv = deviceType+ }+ if (browserName) {+ derivedAttributes.br = browserName+ }+ if (osName) {+ derivedAttributes.os = osName+ }++ const evaluatedFlags = this.featureFlagService.evaluateFlags(+ flags,+ profileId,+ derivedAttributes,+ )++ // Track evaluations in ClickHouse (async, don't wait)+ this.trackEvaluations(+ evaluateDto.pid,+ flags,+ evaluatedFlags,+ profileId,+ ).catch(err => {+ this.logger.error({ err }, 'Failed to track flag evaluations')+ })++ return { flags: evaluatedFlags }+ }++ private async trackEvaluations(+ pid: string,+ flags: FeatureFlag[],+ evaluatedFlags: Record<string, boolean>,+ profileId: string,+ ) {+ if (flags.length === 0) return++ const now = new Date().toISOString().slice(0, 19).replace('T', ' ')++ const values = flags.map(flag => ({+ pid,+ flagId: flag.id,+ flagKey: flag.key,+ result: evaluatedFlags[flag.key] ? 1 : 0,+ profileId,+ created: now,+ }))++ try {+ await clickhouse.insert({+ table: 'feature_flag_evaluations',+ values,+ format: 'JSONEachRow',+ })+ } catch (err) {+ // Log error but don't fail the request+ this.logger.error({ err }, 'Failed to insert flag evaluations')+ }+ }++ @ApiBearerAuth()+ @Put('/:id')+ @Auth()+ @ApiResponse({ status: 200, type: FeatureFlagDto })+ @ApiOperation({ summary: 'Update a feature flag' })+ async updateFeatureFlag(+ @Param('id') id: string,+ @Body() flagDto: UpdateFeatureFlagDto,+ @CurrentUserId() uid: string,+ ) {+ this.logger.log({ id, uid }, 'PUT /feature-flag/:id')++ const flag = await this.featureFlagService.findOne(id)++ if (_isEmpty(flag)) {+ throw new NotFoundException()+ }++ const project = await this.projectService.getFullProject(flag.projectId)++ this.projectService.allowedToManage(+ project,+ uid,+ 'You are not allowed to manage this feature flag',+ )++ // Check for duplicate key if key is being changed+ if (flagDto.key && flagDto.key !== flag.key) {+ const existingFlag = await this.featureFlagService.findByKey(+ flag.projectId,+ flagDto.key,+ )++ if (existingFlag) {+ throw new BadRequestException(+ `A feature flag with key "${flagDto.key}" already exists in this project`,+ )+ }+ }++ const updatePayload: Partial<FeatureFlag> = {+ ..._pick(flagDto, [+ 'key',+ 'description',+ 'flagType',+ 'rolloutPercentage',+ 'targetingRules',+ 'enabled',+ ]),+ }++ const updatedFlag = await this.featureFlagService.update(id, updatePayload)++ if (!updatedFlag) {+ throw new NotFoundException('Feature flag not found after update')+ }++ return {+ ...updatedFlag,+ pid: flag.projectId,+ }+ }++ @ApiBearerAuth()+ @Delete('/:id')+ @Auth()+ @ApiResponse({ status: 204, description: 'Empty body' })+ @ApiOperation({ summary: 'Delete a feature flag' })+ async deleteFeatureFlag(+ @Param('id') id: string,+ @CurrentUserId() uid: string,+ ) {+ this.logger.log({ id, uid }, 'DELETE /feature-flag/:id')++ const flag = await this.featureFlagService.findOne(id)++ if (_isEmpty(flag)) {+ throw new NotFoundException()+ }++ const project = await this.projectService.getFullProject(flag.projectId)++ this.projectService.allowedToManage(+ project,+ uid,+ 'You are not allowed to manage this feature flag',+ )++ await this.featureFlagService.delete(id)+ }++ @ApiBearerAuth()+ @Get('/:id/stats')+ @Auth()+ @ApiResponse({ status: 200, type: FeatureFlagStatsDto })+ @ApiOperation({ summary: 'Get statistics for a feature flag' })+ async getFeatureFlagStats(+ @CurrentUserId() userId: string,+ @Param('id') id: string,+ @Query('period') period: string,+ @Query('from') from?: string,+ @Query('to') to?: string,+ @Query('timezone') timezone?: string,+ ) {+ this.logger.log(+ { userId, id, period, from, to },+ 'GET /feature-flag/:id/stats',+ )++ const flag = await this.featureFlagService.findOne(id)++ if (_isEmpty(flag)) {+ throw new NotFoundException('Feature flag not found')+ }++ const project = await this.projectService.getFullProject(flag.projectId)+ this.projectService.allowedToView(project, userId)++ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)+ const timeBucket = getLowestPossibleTimeBucket(period, from, to)++ const { groupFromUTC, groupToUTC } = this.analyticsService.getGroupFromTo(+ from,+ to,+ timeBucket,+ period,+ safeTimezone,+ )++ const statsQuery = `+ SELECT+ count(*) as evaluations,+ uniqExact(profileId) as profileCount,+ countIf(result = 1) as trueCount,+ countIf(result = 0) as falseCount+ FROM feature_flag_evaluations+ WHERE+ pid = {pid:FixedString(12)}+ AND flagId = {flagId:String}+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}+ `++ const queryParams = {+ pid: flag.projectId,+ flagId: flag.id,+ groupFrom: groupFromUTC,+ groupTo: groupToUTC,+ }++ try {+ const { data } = await clickhouse+ .query({ query: statsQuery, query_params: queryParams })+ .then(resultSet =>+ resultSet.json<{+ evaluations: number+ profileCount: number+ trueCount: number+ falseCount: number+ }>(),+ )++ const stats = data[0] || {+ evaluations: 0,+ profileCount: 0,+ trueCount: 0,+ falseCount: 0,+ }++ const truePercentage =+ stats.evaluations > 0+ ? _round((stats.trueCount / stats.evaluations) * 100, 2)+ : 0++ return {+ evaluations: stats.evaluations,+ profileCount: stats.profileCount,+ trueCount: stats.trueCount,+ falseCount: stats.falseCount,+ truePercentage,+ }+ } catch (err) {+ // If table doesn't exist yet, return empty stats+ this.logger.warn({ err }, 'Failed to get flag stats')+ return {+ evaluations: 0,+ profileCount: 0,+ trueCount: 0,+ falseCount: 0,+ truePercentage: 0,+ }+ }+ }++ @ApiBearerAuth()+ @Get('/:id/profiles')+ @Auth()+ @ApiResponse({ status: 200, type: FeatureFlagProfilesResponseDto })+ @ApiOperation({+ summary: 'Get profiles who have evaluated a feature flag',+ description:+ 'Returns a list of profiles ordered by most recent evaluation time',+ })+ async getFeatureFlagProfiles(+ @CurrentUserId() userId: string,+ @Param('id') id: string,+ @Query('period') period: string,+ @Query('from') from?: string,+ @Query('to') to?: string,+ @Query('timezone') timezone?: string,+ @Query('take', new ParseIntPipe({ optional: true })) take?: number,+ @Query('skip', new ParseIntPipe({ optional: true })) skip?: number,+ @Query('result') result?: 'true' | 'false',+ ) {+ this.logger.log(+ { userId, id, period, from, to, take, skip, result },+ 'GET /feature-flag/:id/profiles',+ )++ const flag = await this.featureFlagService.findOne(id)++ if (_isEmpty(flag)) {+ throw new NotFoundException('Feature flag not found')+ }++ const project = await this.projectService.getFullProject(flag.projectId)+ this.projectService.allowedToView(project, userId)++ const safeTimezone = this.analyticsService.getSafeTimezone(timezone)+ const timeBucket = getLowestPossibleTimeBucket(period, from, to)++ const { groupFromUTC, groupToUTC } = this.analyticsService.getGroupFromTo(+ from,+ to,+ timeBucket,+ period,+ safeTimezone,+ )++ const safeTake = Math.min(take || 15, 50)+ const safeSkip = skip || 0++ // Build HAVING clause for result filter+ let resultHavingClause = ''+ if (result === 'true') {+ resultHavingClause = 'HAVING lastResult = 1'+ } else if (result === 'false') {+ resultHavingClause = 'HAVING lastResult = 0'+ }++ // Query to get profiles with their most recent evaluation+ const profilesQuery = `+ SELECT+ profileId,+ max(created) as lastEvaluated,+ argMax(result, created) as lastResult,+ count(*) as evaluationCount+ FROM feature_flag_evaluations+ WHERE+ pid = {pid:FixedString(12)}+ AND flagId = {flagId:String}+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}+ GROUP BY profileId+ ${resultHavingClause}+ ORDER BY lastEvaluated DESC+ LIMIT {take:UInt32} OFFSET {skip:UInt32}+ `++ const countQuery = `+ SELECT count() as total FROM (+ SELECT+ profileId,+ argMax(result, created) as lastResult+ FROM feature_flag_evaluations+ WHERE+ pid = {pid:FixedString(12)}+ AND flagId = {flagId:String}+ AND created BETWEEN {groupFrom:String} AND {groupTo:String}+ GROUP BY profileId+ ${resultHavingClause}+ )+ `++ const queryParams = {+ pid: flag.projectId,+ flagId: flag.id,+ groupFrom: groupFromUTC,+ groupTo: groupToUTC,+ take: safeTake,+ skip: safeSkip,+ }++ try {+ const [profilesResult, countResult] = await Promise.all([+ clickhouse+ .query({ query: profilesQuery, query_params: queryParams })+ .then(resultSet =>+ resultSet.json<{+ profileId: string+ lastEvaluated: string+ lastResult: number+ evaluationCount: number+ }>(),+ ),+ clickhouse+ .query({ query: countQuery, query_params: queryParams })+ .then(resultSet => resultSet.json<{ total: number }>()),+ ])++ const profiles = profilesResult.data.map(row => ({+ profileId: row.profileId,+ isIdentified: row.profileId.startsWith('usr_'),+ lastResult: row.lastResult === 1,+ evaluationCount: Number(row.evaluationCount),+ lastEvaluated: row.lastEvaluated,+ }))++ return {+ profiles,+ total: Number(countResult.data[0]?.total || 0),+ }+ } catch (err) {+ this.logger.warn({ err }, 'Failed to get flag profiles')+ return {+ profiles: [],+ total: 0,+ }+ }+ }+}diff --git a/backend/apps/community/src/feature-flag/feature-flag.module.ts b/backend/apps/community/src/feature-flag/feature-flag.module.tsnew file mode 100644index 000000000..c4e56db40--- /dev/null+++ b/backend/apps/community/src/feature-flag/feature-flag.module.ts@@ -0,0 +1,15 @@+import { Module } from '@nestjs/common'++import { ProjectModule } from '../project/project.module'+import { AppLoggerModule } from '../logger/logger.module'+import { AnalyticsModule } from '../analytics/analytics.module'+import { FeatureFlagService } from './feature-flag.service'+import { FeatureFlagController } from './feature-flag.controller'++@Module({+ imports: [ProjectModule, AppLoggerModule, AnalyticsModule],+ providers: [FeatureFlagService],+ exports: [FeatureFlagService],+ controllers: [FeatureFlagController],+})+export class FeatureFlagModule {}diff --git a/backend/apps/community/src/feature-flag/feature-flag.service.ts b/backend/apps/community/src/feature-flag/feature-flag.service.tsnew file mode 100644index 000000000..99950dc23--- /dev/null+++ b/backend/apps/community/src/feature-flag/feature-flag.service.ts@@ -0,0 +1,468 @@+import { Injectable } from '@nestjs/common'+import { randomUUID } from 'crypto'+import * as crypto from 'crypto'+import dayjs from 'dayjs'+import utc from 'dayjs/plugin/utc'+import _isEmpty from 'lodash/isEmpty'+import _head from 'lodash/head'+import _map from 'lodash/map'+import _filter from 'lodash/filter'+import _keys from 'lodash/keys'+import _reduce from 'lodash/reduce'++import { clickhouse } from '../common/integrations/clickhouse'+import {+ FeatureFlag,+ ClickhouseFeatureFlag,+ FeatureFlagType,+ TargetingRule,+} from './entity/feature-flag.entity'+import { Pagination } from '../common/pagination/pagination'+import { PaginationOptionsInterface } from '../common/pagination/pagination.results.interface'++dayjs.extend(utc)++const ALLOWED_FLAG_KEYS = [+ 'key',+ 'description',+ 'flagType',+ 'rolloutPercentage',+ 'targetingRules',+ 'enabled',+]++@Injectable()+export class FeatureFlagService {+ formatFlagFromClickhouse(flag: ClickhouseFeatureFlag): FeatureFlag {+ if (!flag) {+ return null+ }++ let targetingRules: TargetingRule[] | null = null+ if (flag.targetingRules) {+ try {+ targetingRules = JSON.parse(flag.targetingRules)+ } catch {+ targetingRules = null+ }+ }++ return {+ id: flag.id,+ key: flag.key,+ description: flag.description,+ flagType: flag.flagType as FeatureFlagType,+ rolloutPercentage: flag.rolloutPercentage,+ targetingRules,+ enabled: Boolean(flag.enabled),+ projectId: flag.projectId,+ created: flag.created,+ }+ }++ formatFlagToClickhouse(+ flag: Partial<FeatureFlag>,+ ): Partial<ClickhouseFeatureFlag> {+ const result: Partial<ClickhouseFeatureFlag> = { ...flag } as any++ if (flag.targetingRules !== undefined) {+ result.targetingRules = flag.targetingRules+ ? JSON.stringify(flag.targetingRules)+ : null+ }++ if (flag.enabled !== undefined) {+ result.enabled = flag.enabled ? 1 : 0+ }++ return result+ }++ async findOne(id: string): Promise<FeatureFlag | null> {+ const query = `SELECT * FROM feature_flag WHERE id = {id:String}`++ const { data } = await clickhouse+ .query({+ query,+ query_params: { id },+ })+ .then(resultSet => resultSet.json<ClickhouseFeatureFlag>())++ if (_isEmpty(data)) {+ return null+ }++ return this.formatFlagFromClickhouse(_head(data))+ }++ async findByKey(projectId: string, key: string): Promise<FeatureFlag | null> {+ const query = `+ SELECT * FROM feature_flag+ WHERE projectId = {projectId:FixedString(12)}+ AND key = {key:String}+ `++ const { data } = await clickhouse+ .query({+ query,+ query_params: { projectId, key },+ })+ .then(resultSet => resultSet.json<ClickhouseFeatureFlag>())++ if (_isEmpty(data)) {+ return null+ }++ return this.formatFlagFromClickhouse(_head(data))+ }++ async findByProject(projectId: string): Promise<FeatureFlag[]> {+ const query = `+ SELECT * FROM feature_flag+ WHERE projectId = {projectId:FixedString(12)}+ ORDER BY key ASC+ `++ const { data } = await clickhouse+ .query({+ query,+ query_params: { projectId },+ })+ .then(resultSet => resultSet.json<ClickhouseFeatureFlag>())++ return _map(data, flag => this.formatFlagFromClickhouse(flag))+ }++ async findEnabledByProject(projectId: string): Promise<FeatureFlag[]> {+ const query = `+ SELECT * FROM feature_flag+ WHERE projectId = {projectId:FixedString(12)}+ AND enabled = 1+ ORDER BY key ASC+ `++ const { data } = await clickhouse+ .query({+ query,+ query_params: { projectId },+ })+ .then(resultSet => resultSet.json<ClickhouseFeatureFlag>())++ return _map(data, flag => this.formatFlagFromClickhouse(flag))+ }++ async paginate(+ options: PaginationOptionsInterface,+ projectId: string,+ ): Promise<Pagination<FeatureFlag>> {+ const take = options.take || 100+ const skip = options.skip || 0++ const countQuery = `+ SELECT count() as total+ FROM feature_flag+ WHERE projectId = {projectId:FixedString(12)}+ `++ const dataQuery = `+ SELECT * FROM feature_flag+ WHERE projectId = {projectId:FixedString(12)}+ ORDER BY key ASC+ LIMIT {take:UInt32} OFFSET {skip:UInt32}+ `++ const [countResult, dataResult] = await Promise.all([+ clickhouse+ .query({+ query: countQuery,+ query_params: { projectId },+ })+ .then(resultSet => resultSet.json<{ total: number }>()),+ clickhouse+ .query({+ query: dataQuery,+ query_params: { projectId, take, skip },+ })+ .then(resultSet => resultSet.json<ClickhouseFeatureFlag>()),+ ])++ const total = countResult.data[0]?.total || 0+ const results = _map(dataResult.data, flag =>+ this.formatFlagFromClickhouse(flag),+ )++ return new Pagination<FeatureFlag>({+ results,+ total,+ })+ }++ async count(projectId: string): Promise<number> {+ const query = `+ SELECT count() as total+ FROM feature_flag+ WHERE projectId = {projectId:FixedString(12)}+ `++ const { data } = await clickhouse+ .query({+ query,+ query_params: { projectId },+ })+ .then(resultSet => resultSet.json<{ total: number }>())++ return data[0]?.total || 0+ }++ async create(flagData: Partial<FeatureFlag>): Promise<FeatureFlag> {+ const id = randomUUID()+ const created = dayjs.utc().format('YYYY-MM-DD HH:mm:ss')++ const formattedFlag = this.formatFlagToClickhouse({+ ...flagData,+ enabled: flagData.enabled ?? true,+ })++ await clickhouse.insert({+ table: 'feature_flag',+ format: 'JSONEachRow',+ values: [+ {+ id,+ key: formattedFlag.key,+ description: formattedFlag.description || null,+ flagType: formattedFlag.flagType || FeatureFlagType.BOOLEAN,+ rolloutPercentage: formattedFlag.rolloutPercentage ?? 100,+ targetingRules: formattedFlag.targetingRules || null,+ enabled: formattedFlag.enabled ?? 1,+ projectId: flagData.projectId,+ created,+ },+ ],+ })++ return this.findOne(id)+ }++ async update(+ id: string,+ flagData: Partial<FeatureFlag>,+ ): Promise<FeatureFlag> {+ const filtered = _reduce(+ _filter(+ _keys(flagData),+ key =>+ ALLOWED_FLAG_KEYS.includes(key) &&+ flagData[key as keyof FeatureFlag] !== undefined,+ ),+ (obj, key) => {+ obj[key] = flagData[key as keyof FeatureFlag]+ return obj+ },+ {} as Record<string, any>,+ )++ const columns = _keys(filtered)++ if (_isEmpty(columns)) {+ return this.findOne(id)+ }++ const formattedData = this.formatFlagToClickhouse(+ filtered as Partial<FeatureFlag>,+ )++ const params: Record<string, any> = { id }++ const assignments = _map(columns, col => {+ const value = formattedData[col as keyof ClickhouseFeatureFlag]+ params[col] = value++ if (col === 'enabled') {+ return `${col}={${col}:Int8}`+ }++ if (col === 'rolloutPercentage') {+ return `${col}={${col}:UInt8}`+ }++ // Handle nullable string columns+ if (+ value === null &&+ (col === 'description' || col === 'targetingRules')+ ) {+ return `${col}=NULL`+ }++ return `${col}={${col}:String}`+ }).join(', ')++ const query = `ALTER TABLE feature_flag UPDATE ${assignments} WHERE id={id:String}`++ await clickhouse.command({+ query,+ query_params: params,+ })++ return this.findOne(id)+ }++ async delete(id: string): Promise<void> {+ const query = `ALTER TABLE feature_flag DELETE WHERE id = {id:String}`++ await clickhouse.command({+ query,+ query_params: { id },+ })+ }++ async deleteByProject(projectId: string): Promise<void> {+ const query = `ALTER TABLE feature_flag DELETE WHERE projectId = {projectId:FixedString(12)}`++ await clickhouse.command({+ query,+ query_params: { projectId },+ })+ }++ /**+ * Evaluates all feature flags for a project given visitor attributes+ */+ evaluateFlags(+ flags: FeatureFlag[],+ profileId: string,+ attributes?: Record<string, string>,+ ): Record<string, boolean> {+ const result: Record<string, boolean> = {}++ for (const flag of flags) {+ result[flag.key] = this.evaluateFlag(flag, profileId, attributes)+ }++ return result+ }++ /**+ * Evaluates a single feature flag for a visitor+ */+ evaluateFlag(+ flag: FeatureFlag,+ profileId: string,+ attributes?: Record<string, string>,+ ): boolean {+ // If flag is disabled, always return false+ if (!flag.enabled) {+ return false+ }++ // Check targeting rules if any exist+ if (flag.targetingRules && flag.targetingRules.length > 0) {+ const matchesTargeting = this.matchesTargetingRules(+ flag.targetingRules,+ attributes,+ )+ if (!matchesTargeting) {+ return false+ }+ }++ // For boolean flags, return true if enabled and targeting matches+ if (flag.flagType === FeatureFlagType.BOOLEAN) {+ return true+ }++ // For rollout flags, use percentage-based rollout+ if (flag.flagType === FeatureFlagType.ROLLOUT) {+ return this.isInRolloutPercentage(+ flag.key,+ flag.rolloutPercentage,+ profileId,+ )+ }++ return false+ }++ /**+ * Checks if visitor attributes match the targeting rules+ * Rules are evaluated as AND (all rules must match)+ */+ private matchesTargetingRules(+ rules: TargetingRule[],+ attributes?: Record<string, string>,+ ): boolean {+ if (!attributes) {+ // If no attributes provided, we can't match any rules+ // Return true to be permissive (flag will be shown)+ return true+ }++ for (const rule of rules) {+ const attributeValue = attributes[rule.column]++ // Check if we have the attribute+ if (attributeValue === undefined) {+ // If attribute not provided, skip this rule (be permissive)+ continue+ }++ const matches = this.matchesRule(attributeValue, rule.filter)++ // If isExclusive (exclude), we want the rule to NOT match+ // If not isExclusive (include), we want the rule to match+ if (rule.isExclusive) {+ // Exclude: if it matches, targeting fails+ if (matches) {+ return false+ }+ } else {+ // Include: if it doesn't match, targeting fails+ if (!matches) {+ return false+ }+ }+ }++ return true+ }++ /**+ * Checks if an attribute value matches a filter value+ * Supports case-insensitive matching+ */+ private matchesRule(attributeValue: string, filterValue: string): boolean {+ // Case-insensitive exact match+ return attributeValue.toLowerCase() === filterValue.toLowerCase()+ }++ /**+ * Determines if a visitor is within the rollout percentage+ * Uses consistent hashing based on flag key and profile ID+ */+ private isInRolloutPercentage(+ flagKey: string,+ percentage: number,+ profileId: string,+ ): boolean {+ if (percentage >= 100) {+ return true+ }+ if (percentage <= 0) {+ return false+ }++ // Create a consistent hash based on flag key and profile ID+ const hash = crypto+ .createHash('md5')+ .update(`${flagKey}:${profileId}`)+ .digest('hex')++ // Convert first 8 hex characters to a number (0 to 2^32-1)+ const hashValue = parseInt(hash.substring(0, 8), 16)++ // Normalize to 0-100 range+ const normalizedValue = (hashValue / 0xffffffff) * 100++ return normalizedValue < percentage+ }+}diff --git a/backend/migrations/clickhouse/selfhosted_2025_12_10_feature_flags.js b/backend/migrations/clickhouse/selfhosted_2025_12_10_feature_flags.jsnew file mode 100644index 000000000..78600636a--- /dev/null+++ b/backend/migrations/clickhouse/selfhosted_2025_12_10_feature_flags.js@@ -0,0 +1,38 @@+// This migration adds feature flags support for self-hosted instances+const { queriesRunner, dbName } = require('./setup')++const queries = [+ // Create feature_flag table for storing feature flag definitions+ `CREATE TABLE IF NOT EXISTS ${dbName}.feature_flag+ (+ id String,+ key String,+ description Nullable(String),+ flagType Enum8('boolean' = 1, 'rollout' = 2) DEFAULT 'boolean',+ rolloutPercentage UInt8 DEFAULT 100,+ targetingRules Nullable(String),+ enabled Int8 DEFAULT 1,+ projectId FixedString(12),+ created DateTime('UTC')+ )+ ENGINE = ReplacingMergeTree(created)+ ORDER BY (projectId, id)+ PARTITION BY toYYYYMM(created);`,++ // Create feature_flag_evaluations table for tracking flag evaluations+ `CREATE TABLE IF NOT EXISTS ${dbName}.feature_flag_evaluations+ (+ pid FixedString(12),+ flagId String,+ flagKey String,+ result UInt8,+ profileId String,+ created DateTime('UTC')+ )+ ENGINE = MergeTree()+ PARTITION BY toYYYYMM(created)+ ORDER BY (pid, flagId, created)+ TTL created + INTERVAL 1 YEAR;`,+]++queriesRunner(queries)