feat: added flag migrations as yaml

docs/_sidebar.md

@@ -7,6 +7,7 @@
     - [Debug Console](flagr_debugging.md)
 - Server Configuration
     - [Env](flagr_env.md)
+    - [Migrations](flagr_migrations.md)
 - Client SDKs
     - [Ruby SDK 🔗](https://github.com/openflagr/rbflagr)
     - [Go SDK 🔗](https://github.com/openflagr/goflagr)

docs/api_docs/bundle.yaml

@@ -927,6 +927,21 @@ paths:
           description: generic error response
           schema:
             $ref: '#/definitions/error'
+  /migrations:
+    get:
+      tags:
+        - migration
+      operationId: runMigrations
+      description: Run migrations
+      responses:
+        '200':
+          description: OK
+          schema:
+            $ref: '#/definitions/migrationStatus'
+        default:
+          description: migration status with error code
+          schema:
+            $ref: '#/definitions/migrationStatus'
   /export/sqlite:
     get:
       tags:
@@ -1459,6 +1474,18 @@ definitions:
     properties:
       status:
         type: string
+  migrationStatus:
+    type: object
+    properties:
+      code:
+        type: integer
+      migrations:
+        type: array
+        x-omitempty: true
+        items:
+          type: string
+      message:
+        type: string
   error:
     type: object
     required:

docs/flagr_migrations.md

@@ -0,0 +1,53 @@
+# Migrations
+
+Users can create flag collections as yaml files within a migration directory and run flagr to insert/modify flags. 
+This allows for developers to create flags as deployment assets and allows for migrating flags through various environments whilst keeping keys stable.
+
+Each found flag is upserted into the database. Then the flag has all segments, variants and tags removed then replaced with the new flag properties.
+
+As an example, create a file named `migrations/202403030000.yaml` with the following content:
+```yaml
+---
+# this is a basic flag
+- key: SIMPLE-FLAG-1
+  description: a toggle for just one user
+  enabled: true
+  segments:
+    - description: flag for just for one email test@test.com
+      rank: 0
+      rolloutPercent: 100
+      constraints:
+        - property: email
+          operator: EQ
+          value: '"test@test.com"'
+      distributions:
+        - variantKey: "on"
+          percent: 100
+    - rank: 1
+      rolloutPercent: 100
+      constraints: []
+      distributions:
+        - variantKey: "off"
+          percent: 100
+  variants:
+    - key: "off"
+      attachment: {}
+    - key: "on"
+      attachment: {}
+  entityType: User
+  dataRecordsEnabled: true
+
+```
+
+```shell
+$ curl http://localhost:8000/api/v1/migrations
+{"code":200,"message":"1 new migrations completed","migrations":["202403030000.yaml"]}
+```
+Once the endpoint is executed, flagr will scan the migration files, insert them into the db and output status
+
+### Config
+Location of yaml configs is set by env var before running the server
+```
+FLAGR_MIGRATION_PATH=./migrations/
+./flagr 
+```

go.mod

@@ -147,4 +147,5 @@ require (
 	modernc.org/mathutil v1.5.0 // indirect
 	modernc.org/memory v1.5.0 // indirect
 	modernc.org/sqlite v1.23.1 // indirect
+	sigs.k8s.io/yaml v1.4.0 // indirect
 )

go.sum

@@ -714,3 +714,5 @@ modernc.org/strutil v1.1.3/go.mod h1:MEHNA7PdEnEwLvspRMtWTNnp2nnyvMfkimT1NKNAGbw
 modernc.org/tcl v1.15.0/go.mod h1:xRoGotBZ6dU+Zo2tca+2EqVEeMmOUBzHnhIwq4YrVnE=
 modernc.org/token v1.0.1/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
 modernc.org/z v1.7.0/go.mod h1:hVdgNMh8ggTuRG1rGU8x+xGRFfiQUIAw0ZqlPy8+HyQ=
+sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E=
+sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY=

migrations/.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "key": {
+        "type": "string"
+      },
+      "description": {
+        "type": "string"
+      },
+      "enabled": {
+        "type": "boolean"
+      },
+      "segments": {
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+              "description": {
+                "type": "string"
+              },
+              "rank": {
+                "type": "integer"
+              },
+              "rolloutPercent": {
+                "type": "integer"
+              },
+              "constraints": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                      "property": {
+                        "type": "string"
+                      },
+                      "operator": {
+                        "type": "string"
+                      },
+                      "value": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "property",
+                      "operator",
+                      "value"
+                    ]
+                  }
+              },
+              "distributions": {
+                "type": "array",
+                "items": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "variantKey": {
+                        "type": "string"
+                      },
+                      "percent": {
+                        "type": "integer"
+                      }
+                    },
+                    "required": [
+                      "variantKey",
+                      "percent"
+                    ]
+                  }
+                ]
+              }
+            },
+            "required": [
+              "rank",
+              "rolloutPercent",
+              "distributions"
+            ]
+          }
+      },
+      "variants": {
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+              "key": {
+                "type": "string"
+              },
+              "attachment": {
+                "type": "object"
+              }
+            },
+            "required": [
+              "key"
+            ]
+          }
+      },
+      "entityType": {
+        "type": "string"
+      },
+      "dataRecordsEnabled": {
+        "type": "boolean"
+      },
+      "tags": {
+        "type": "array",
+        "items":
+          {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value"
+            ]
+          }
+      }
+    },
+    "required": [
+      "key",
+      "description",
+      "enabled"
+    ]
+  }
+}

pkg/config/env.go

@@ -70,6 +70,9 @@ var Config = struct {
 	DBConnectionRetryAttempts uint          `env:"FLAGR_DB_DBCONNECTION_RETRY_ATTEMPTS" envDefault:"9"`
 	DBConnectionRetryDelay    time.Duration `env:"FLAGR_DB_DBCONNECTION_RETRY_DELAY" envDefault:"100ms"`
 
+	// path where migrations are loaded from
+	MigrationPath string `env:"FLAGR_MIGRATION_PATH" envDefault:"migrations"`
+
 	// CORSEnabled - enable CORS
 	CORSEnabled          bool     `env:"FLAGR_CORS_ENABLED" envDefault:"true"`
 	CORSAllowCredentials bool     `env:"FLAGR_CORS_ALLOW_CREDENTIALS" envDefault:"true"`

pkg/entity/db.go

@@ -32,6 +32,7 @@ var AutoMigrateTables = []interface{}{
 	Variant{},
 	Tag{},
 	FlagEntityType{},
+	FlagMigration{},
 }
 
 func connectDB() (db *gorm.DB, err error) {

pkg/entity/flag_migration.go

@@ -0,0 +1,9 @@
+package entity
+
+import "gorm.io/gorm"
+
+type FlagMigration struct {
+	gorm.Model
+
+	Name string `gorm:"type:varchar(64);uniqueIndex:idx_flag_migration_name"`
+}