entity

package
v0.0.0-...-e521638 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 5, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// TotalBucketNum represents how many buckets we can use to determine the consistent hashing
	// distribution and rollout
	TotalBucketNum uint = 1000

	// PercentMultiplier implies that the multiplier between percentage (100) and TotalBucketNum
	PercentMultiplier uint = TotalBucketNum / uint(100)
)
View Source
const SegmentDefaultRank = uint(999)

SegmentDefaultRank is the default rank when we create the segment

Variables

View Source
var AutoMigrateTables = []any{
	Flag{},
	Constraint{},
	Distribution{},
	FlagSnapshot{},
	Segment{},
	User{},
	Variant{},
	Tag{},
	FlagEntityType{},
	HourlyEvent{},
}

AutoMigrateTables stores the entity tables that we can auto migrate in gorm

OperatorToExprMap maps from the swagger model operator to condition operator

Functions

func AppendTagValueToFlag

func AppendTagValueToFlag(tx *gorm.DB, flagID uint, value string) error

AppendTagValueToFlag finds or creates a tag by value and associates it with the flag.

func ApplyFlagTemplate

func ApplyFlagTemplate(tx *gorm.DB, flagID uint, template Flag) error

ApplyFlagTemplate persists a template's variants, segments, constraints, distributions, and tags onto flagID. Used for create templates (e.g. simple_boolean_flag) and for duplicating an existing flag's graph.

func CreateFlagEntityType

func CreateFlagEntityType(db *gorm.DB, key string) error

CreateFlagEntityType creates the FlagEntityType if not exists

func CreateFlagKey

func CreateFlagKey(key string) (string, error)

CreateFlagKey creates the key based on the given key

func GetDB

func GetDB() *gorm.DB

GetDB gets the db singleton

func NewSQLiteDB

func NewSQLiteDB(filePath string) *gorm.DB

NewSQLiteDB creates a new sqlite db useful for backup exports and unit tests

func NewTestDB

func NewTestDB() *gorm.DB

NewTestDB creates a new test db

func PopulateTestDB

func PopulateTestDB(flag Flag) *gorm.DB

PopulateTestDB seeds the test db

func PreloadConstraintsDistribution

func PreloadConstraintsDistribution(db *gorm.DB) *gorm.DB

PreloadConstraintsDistribution preloads constraints and distributions for segment

func PreloadFlagTags

func PreloadFlagTags(db *gorm.DB) *gorm.DB

Preloads just the tags

func PreloadSegmentsVariantsTags

func PreloadSegmentsVariantsTags(db *gorm.DB) *gorm.DB

PreloadSegmentsVariantsTags preloads segments, variants and tags for flag

func SaveFlagSnapshot

func SaveFlagSnapshot(db *gorm.DB, flagID uint, updatedBy string, operation notification.Operation, componentType notification.ComponentType, componentID uint, componentKey string)

SaveFlagSnapshot saves the Flag Snapshot and sends a notification in its own transaction.

func TestApplyFlagTemplate_CopiesDistributionBitmap

func TestApplyFlagTemplate_CopiesDistributionBitmap(t *testing.T)

Types

type Attachment

type Attachment map[string]any

Attachment supports dynamic configuration in variant

func (Attachment) Get

func (a Attachment) Get(key string) any

Get returns the value of the key

func (Attachment) GetBool

func (a Attachment) GetBool(key string) bool

GetBool returns the bool value of the key

func (Attachment) GetFloat64

func (a Attachment) GetFloat64(key string) float64

GetFloat64 returns the float64 value of the key

func (Attachment) GetInt

func (a Attachment) GetInt(key string) int

GetInt returns the int value of the key

func (Attachment) GetString

func (a Attachment) GetString(key string) string

GetString returns the string value of the key

func (*Attachment) Scan

func (a *Attachment) Scan(value any) error

Scan implements scanner interface

func (Attachment) Value

func (a Attachment) Value() (driver.Value, error)

Value implements valuer interface

type Constraint

type Constraint struct {
	gorm.Model

	SegmentID uint `gorm:"index:idx_constraint_segmentid"`
	Property  string
	Operator  string
	Value     string `gorm:"type:text"`
}

Constraint is the unit of constraints

func (*Constraint) ToExpr

func (c *Constraint) ToExpr() (conditions.Expr, error)

ToExpr transfer the constraint to conditions.Expr for evaluation

func (*Constraint) Validate

func (c *Constraint) Validate() error

Validate validates Constraint

type ConstraintArray

type ConstraintArray []Constraint

ConstraintArray is an array of Constraint

func (ConstraintArray) ToExpr

func (cs ConstraintArray) ToExpr() (conditions.Expr, error)

ToExpr maps ConstraintArray to expr by joining 'AND'

type Distribution

type Distribution struct {
	gorm.Model
	SegmentID  uint `gorm:"index:idx_distribution_segmentid"`
	VariantID  uint `gorm:"index:idx_distribution_variantid"`
	VariantKey string

	Percent uint   // Percent is an uint from 0 to 100, percent is always derived from Bitmap
	Bitmap  string `gorm:"type:text" json:"-"`
}

Distribution is the struct represents distribution under segment and links to variant

type DistributionArray

type DistributionArray struct {
	VariantIDs          []uint
	PercentsAccumulated []int // useful for binary search to find the rollout variant
}

DistributionArray is useful for faster evaluation

func (DistributionArray) Rollout

func (d DistributionArray) Rollout(entityID string, salt string, rolloutPercent uint, withDebug bool) (variantID *uint, msg string)

Rollout rolls out the entity based on rolloutPercent. When withDebug is false, the returned message is empty and debug formatting is skipped (hot eval path).

type DistributionDebugLog

type DistributionDebugLog struct {
	BucketNum         uint
	DistributionArray DistributionArray
	VariantID         uint
	RolloutPercent    uint
}

DistributionDebugLog is useful for making debug logs

type Flag

type Flag struct {
	gorm.Model

	Key         string `gorm:"type:varchar(64);uniqueIndex:idx_flag_key"`
	Description string `gorm:"type:text"`
	CreatedBy   string
	UpdatedBy   string
	Enabled     bool
	Segments    []Segment
	Variants    []Variant
	Tags        []Tag `gorm:"many2many:flags_tags;"`
	SnapshotID  uint
	Notes       string `gorm:"type:text"`

	DataRecordsEnabled bool
	EntityType         string

	FlagEvaluation FlagEvaluation `gorm:"-" json:"-"`
}

Flag is the unit of flags

func GenFixtureFlag

func GenFixtureFlag() Flag

GenFixtureFlag is a fixture

func SimpleBooleanFlagTemplate

func SimpleBooleanFlagTemplate() Flag

SimpleBooleanFlagTemplate is the built-in starter template (variant "on", 100% rollout). Only nested Variants/Segments are set; ApplyFlagTemplate ignores flag-level scalars and IDs.

func SourceFlagTemplate

func SourceFlagTemplate(source *Flag) Flag

SourceFlagTemplate builds a template from an existing flag for cloning onto another flag. Variant keys and distribution variant keys are preserved; entity IDs and flag scalars are omitted.

func (*Flag) Preload

func (f *Flag) Preload(db *gorm.DB) error

Preload preloads the segments, variants and tags into flags

func (*Flag) PreloadTags

func (f *Flag) PreloadTags(db *gorm.DB) error

PreloadTags preloads the tags into flags

func (*Flag) PrepareEvaluation

func (f *Flag) PrepareEvaluation() error

PrepareEvaluation prepares the information for evaluation

type FlagEntityType

type FlagEntityType struct {
	gorm.Model
	Key string `gorm:"type:varchar(64);uniqueIndex:flag_entity_type_key"`
}

FlagEntityType is the entity_type that will overwrite into evaluation logs.

type FlagEvaluation

type FlagEvaluation struct {
	VariantsMap map[uint]*Variant
	TagValues   []string // denormalized tag values for eval results
}

FlagEvaluation is a struct that holds the necessary info for evaluation

type FlagSnapshot

type FlagSnapshot struct {
	gorm.Model
	FlagID    uint `gorm:"index:idx_flagsnapshot_flagid"`
	UpdatedBy string
	Flag      []byte `gorm:"type:text"`
}

FlagSnapshot is the snapshot of a flag Any change of the flag will create a new snapshot

type HourlyEvent

type HourlyEvent struct {
	ID         uint      `gorm:"primaryKey;autoIncrement"`
	FlagID     int64     `gorm:"not null;uniqueIndex:idx_datar_hourly,priority:1"`
	BucketHour time.Time `gorm:"not null;uniqueIndex:idx_datar_hourly,priority:2"`
	VariantID  int64     `gorm:"not null;default:0;uniqueIndex:idx_datar_hourly,priority:3"`
	SegmentID  int64     `gorm:"not null;default:0;uniqueIndex:idx_datar_hourly,priority:4"`
	EvalCount  int32     `gorm:"not null;default:0"`
	UpdatedAt  time.Time `gorm:"autoUpdateTime"`
}

HourlyEvent represents one aggregate row of evaluation counts per hour. The natural key is (flag_id, variant_id, segment_id, bucket_hour). A surrogate auto-increment PK allows adding columns later without table rebuild.

func (HourlyEvent) TableName

func (HourlyEvent) TableName() string

TableName specifies the table name for GORM.

type Logger

type Logger struct {
	LogLevel                  gorm_logger.LogLevel
	SlowThreshold             time.Duration
	IgnoreRecordNotFoundError bool
}

func (*Logger) Error

func (l *Logger) Error(ctx context.Context, s string, args ...any)

func (*Logger) Info

func (l *Logger) Info(ctx context.Context, s string, args ...any)

func (*Logger) LogMode

func (l *Logger) LogMode(level gorm_logger.LogLevel) gorm_logger.Interface

func (*Logger) Trace

func (l *Logger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error)

func (*Logger) Warn

func (l *Logger) Warn(ctx context.Context, s string, args ...any)

type Segment

type Segment struct {
	gorm.Model
	FlagID         uint   `gorm:"index:idx_segment_flagid"`
	Description    string `gorm:"type:text"`
	Rank           uint
	RolloutPercent uint
	Constraints    ConstraintArray
	Distributions  []Distribution

	// Purely for evaluation
	SegmentEvaluation SegmentEvaluation `gorm:"-" json:"-"`
}

Segment is the unit of segmentation

func GenFixtureSegment

func GenFixtureSegment() Segment

GenFixtureSegment is a fixture

func (*Segment) Preload

func (s *Segment) Preload(db *gorm.DB) error

Preload preloads the segment

func (*Segment) PrepareEvaluation

func (s *Segment) PrepareEvaluation() error

PrepareEvaluation prepares the segment for evaluation by parsing constraints and denormalize distributions

type SegmentEvaluation

type SegmentEvaluation struct {
	ConditionsExpr    conditions.Expr
	DistributionArray DistributionArray
	FlagIDStr         string // pre-formatted flagID string used as salt in rollout
}

SegmentEvaluation is a struct that holds the necessary info for evaluation

type SnapshotNotification

type SnapshotNotification struct {
	// contains filtered or unexported fields
}

SnapshotNotification is an opaque handle returned from WriteFlagSnapshotTx. Call NotifyAfterCommit after the outer transaction commits; do not inspect or construct it outside entity.

func WriteFlagSnapshotTx

func WriteFlagSnapshotTx(
	tx *gorm.DB,
	flagID uint,
	updatedBy string,
) (SnapshotNotification, error)

WriteFlagSnapshotTx records a flag snapshot using tx. The caller must Commit or Rollback.

func (SnapshotNotification) NotifyAfterCommit

func (n SnapshotNotification) NotifyAfterCommit(
	flagID uint,
	updatedBy string,
	operation notification.Operation,
	componentType notification.ComponentType,
	componentID uint,
	componentKey string,
)

NotifyAfterCommit sends webhook/metrics after the outer transaction committed.

type Tag

type Tag struct {
	gorm.Model

	Value string  `gorm:"type:varchar(64);uniqueIndex:idx_tag_value"`
	Flags []*Flag `gorm:"many2many:flags_tags;"`
}

Tag is a descriptive identifier given to ease searchability

type User

type User struct {
	gorm.Model
	Email string `gorm:"type:text"`
}

User represents the User struct

type Variant

type Variant struct {
	gorm.Model
	FlagID     uint `gorm:"index:idx_variant_flagid"`
	Key        string
	Attachment Attachment `gorm:"type:text"`
}

Variant is the struct that represent the experience/variant of the evaluation entity

func (*Variant) Validate

func (v *Variant) Validate() error

Validate validates the Variant

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL