Skip to content

πŸ“ˆ 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!

CE support

Blue Mouse365392d6eb8d
diff --git a/backend/apps/community/src/app.module.ts b/backend/apps/community/src/app.module.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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)