flagura

command module
v1.4.0 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 11 Imported by: 0

README ΒΆ

⚑ Flagura β€” Sub-Microsecond Feature Flagging & Release Engine

Flagura Banner Go Report Card Go Version Evaluation Latency OpenFeature License

Feature flags that disappear from your critical path.
In-process deterministic in-memory evaluation (~100ns), OpenFeature native providers, gradual rollouts, authenticated webhook kill-switches, and 4-Eyes change governance.

Live Demo & Console β€’ Architecture β€’ OpenFeature β€’ API Reference β€’ SDK Integration β€’ Deployment β€’ Runbooks


πŸ“– Overview

Flagura is a modern, high-performance feature flag and experimentation engine engineered for in-process flag evaluation. Traditional SaaS feature flagging services introduce remote HTTP network hops (~20–80ms) that slow down user interactions and degrade Core Web Vitals.

Flagura evaluates rules and percentage rollouts locally in-memory using deterministic 64-bit FNV-1a hashing and cached targeting rule matchers, executing in sub-microsecond time (~90ns – 220ns) with zero database I/O on evaluation hot paths.


⚑ Key Highlights

  • 🏒 Multi-Tenant Organization & Project Hierarchy: Group flags, API keys, change requests, and experiments into isolated Organizations and Projects.
  • ⚑ Sub-Microsecond Local Evaluation: In-memory deterministic rule engine resolving flags in ~90ns – 250ns with zero remote network I/O.
  • 🌐 Native OpenFeature Provider: Drop-in vendor-neutral open-feature/go-sdk integrationβ€”switch or adopt Flagura with zero code lock-in.
  • πŸ›‘οΈ 4-Eyes Change Governance & RBAC: Protected API endpoints, non-self-assignable roles, and multi-approver pull requests for production flag mutations.
  • 🎯 Deterministic Sticky Percentage Bucketing: Mathematical FNV-1a 64-bit hashing ensures users consistently land in the exact same rollout bucket across sessions and platforms.
  • 🚨 Authenticated Webhook Kill-Switch: Secure circuit breaker (X-Webhook-Secret or Bearer token) to immediately shut down broken flags in production.
  • πŸ“Š A/B Testing & Statistical Engine: Ingestion API (/api/v1/events) computing two-tailed pooled Z-scores, p-values, confidence intervals, and variant lift in sub-35Β΅s.
  • πŸ’Ž Clean Developer Console: Built with Go, Templ, and Tailwind CSS featuring an interactive switchboard, live evaluator sandbox, and append-only audit trail.

βš–οΈ How Flagura Compares

Feature / Capability ⚑ Flagura (v1.7.0) LaunchDarkly Unleash Flagsmith GrowthBook
Core Architecture Go (Native Binary) Cloud SaaS / Daemon Node.js / TypeScript Python (Django) TypeScript / Next.js
P50 Local Evaluation Latency ~13 ns – 220 ns ~25 Β΅s (In-Process SDK) ~25 Β΅s (Proxy SDK) ~50 Β΅s ~30 Β΅s
Data Sovereignty & Privacy βœ… 100% Private (Your DB/VPC) ❌ 3rd-Party Cloud βœ… Yes βœ… Yes βœ… Yes
Zero Vendor Lock-in βœ… Native OpenFeature Provider ⚠️ Proprietary SDKs ⚠️ Proprietary SDKs ⚠️ Proprietary SDKs ⚠️ Proprietary SDKs
4-Eyes Change Governance βœ… Included (100% Free) πŸ”’ Enterprise ($$$) πŸ”’ Enterprise ($$$) πŸ”’ Enterprise ($$$) πŸ”’ Enterprise ($$$)
Built-in Statistical A/B βœ… Native ($Z$, $P$-Value, Lift) πŸ”’ Experimentation Addon ❌ Basic Variants Only ❌ Basic Variants Only βœ… Python / SQL Engine
Automated Canary + Guardrails βœ… Native Stage Ramp πŸ”’ Enterprise Guardrails ❌ Manual Ramp ❌ Manual Ramp ❌ Manual Ramp
Prometheus Metrics (/metrics) βœ… Native Exporter ⚠️ Requires Sidecar ⚠️ Requires Addon ⚠️ Requires Plugin ⚠️ Requires Addon
Stale Flag Codebase Auditor βœ… flagura audit CLI πŸ”’ Code References Addon ❌ Manual ❌ Manual ❌ Manual
Memory Footprint ~25 MB – 40 MB High (Relay Daemon) ~450 MB – 800 MB ~400 MB – 1 GB ~350 MB – 600 MB
Pricing Model 100% Free & Open Source $500 – $5,000+/mo Freemium ($80+/mo) Freemium ($45+/mo) Freemium ($20+/mo)
Zero DB I/O on Evaluation βœ… Yes (atomic.Pointer CoW) ⚠️ Requires Proxy ⚠️ Requires Redis/Proxy ❌ Queries DB/Cache ⚠️ Requires Cache
Deployment Model Single Binary / Docker / Vercel Cloud SaaS Only Multi-tier (Node + Redis + DB) Multi-tier (Django + DB) Multi-tier (Next + DB)

Benchmark Methodology: Evaluated on Apple M3 Pro using standard Go benchmarks (go test -bench=. -benchmem ./pkg/engine/...): Percentage Rollout ~111 ns (32 B/op), Rule Match ~91 ns (16 B/op), Bare FNV-1a Hash ~13 ns (0 B/op), Regex Match (Cached) ~221 ns (32 B/op). Competitor metrics reflect typical client SDK in-memory evaluation / relay daemon documentation.

πŸ‘‰ Read full architectural comparison in documentation


πŸ—οΈ Architecture

Flagura is engineered for maximum execution speed, zero runtime overhead, and simple deployment:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                              FLAGURA ENGINE                            β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  β€’ Go 1.26+ Core          ── High-concurrency engine & FNV-1a hashing   β”‚
β”‚  β€’ Direct SQL Store       ── Pure database/sql + lib/pq for Supabase   β”‚
β”‚  β€’ API-First Design       ── Ultra-fast batch & single evaluation API  β”‚
β”‚  β€’ Compiled Views         ── Type-safe compiled HTML views & CSS      β”‚
β”‚  β€’ Reactive UI Components ── Fast, zero-page-reload console components β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                     β”‚ Client Application / SDK β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                   β”‚ (In-Memory / HTTP)
                                   β–Ό
        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β”‚               Flagura Evaluation Engine             β”‚
        β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
        β”‚  1. Check Environment Master Kill-Switch            β”‚
        β”‚  2. Evaluate Specific Attribute Rules (Email/Tier)  β”‚
        β”‚  3. Compute FNV-1a 64-bit Sticky Hash Bucket (0-99) β”‚
        β”‚  4. Resolve Treatment vs Control Group              β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                   β”‚ (< 80ns execution)
                                   β–Ό
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                     β”‚  Boolean / Variant Value β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸš€ Quickstart

1. Run Locally (In-Memory Edge Mode)

No database installation required to get started. Flagura includes a built-in in-memory edge store pre-seeded with sample flags:

# Clone the repository
git clone https://github.com/dhawalhost/flagura.git
cd flagura

# Run with Make (auto-generates templates & starts server)
make dev

# Or build both server and developer CLI binaries into bin/
make build

Tip: Run make help to see all available local workflows (testing, benchmarks, docker, code coverage).

Open your browser to:


2. Connect to Supabase PostgreSQL
  1. Open your Supabase Dashboard -> SQL Editor.

  2. Run the migration script in supabase/schema.sql:

    CREATE TABLE IF NOT EXISTS feature_flags (
        id TEXT PRIMARY KEY,
        key TEXT UNIQUE NOT NULL,
        name TEXT NOT NULL,
        description TEXT,
        type TEXT NOT NULL DEFAULT 'boolean',
        tags TEXT[] DEFAULT '{}',
        variants JSONB DEFAULT '[]'::jsonb,
        environments JSONB NOT NULL DEFAULT '{}'::jsonb,
        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
    );
    
    CREATE TABLE IF NOT EXISTS audit_logs (
        id TEXT PRIMARY KEY,
        flag_key TEXT NOT NULL,
        action TEXT NOT NULL,
        environment TEXT NOT NULL,
        actor TEXT NOT NULL,
        details TEXT,
        timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW()
    );
    
  3. Set your connection string and launch:

    export DATABASE_URL="postgres://postgres.[PROJECT_REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres?sslmode=require"
    go run main.go
    

πŸ”Œ REST API Reference

1. Batch / Single Flag Evaluation

Endpoint: POST /api/v1/evaluate

Evaluates requested feature flags against a user context in sub-millisecond time.

Request:
curl -X POST http://localhost:3000/api/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "flags": ["ai-smart-search", "new-checkout-flow"],
    "context": {
      "user_id": "usr_dhawal_01",
      "email": "dhawal@flagship.dev",
      "country": "US",
      "role": "admin",
      "tier": "enterprise",
      "environment": "production"
    }
  }'
Response:
{
  "results": {
    "ai-smart-search": {
      "flag_key": "ai-smart-search",
      "enabled": true,
      "variant": "treatment",
      "value": true,
      "reason": "TARGETING_RULE_MATCH",
      "matched_rule_id": "rule_staff_whitelist",
      "bucket_val": 42,
      "evaluation_latency_ns": 4820,
      "evaluation_latency_us": 4.82
    },
    "new-checkout-flow": {
      "flag_key": "new-checkout-flow",
      "enabled": true,
      "variant": "true",
      "value": true,
      "reason": "PERCENTAGE_ROLLOUT",
      "bucket_val": 35,
      "evaluation_latency_ns": 120,
      "evaluation_latency_us": 0.12
    }
  },
  "total_flags": 2,
  "environment": "production",
  "total_duration_us": 22.4
}

2. Flag Management & API Endpoints
Method Endpoint Description
GET /healthz / /livez Kubernetes liveness health probe
GET /readyz Kubernetes readiness probe (checks storage availability)
GET /metrics Prometheus metrics exposition (flagura_evaluations_total, etc.)
GET /api/v1/organizations List all organizations (Admin only)
POST /api/v1/organizations Create new organization (Admin only)
GET /api/v1/projects List projects in active or queried organization
POST /api/v1/projects Create new project in organization
POST /api/v1/projects/active Switch active project session context
GET /api/v1/flags/stream Real-time HTTP/2 Server-Sent Events (SSE) flag synchronization stream
GET /api/v1/flags List feature flags in active project scope
GET /api/v1/flags/:key Retrieve configuration and rules for a specific flag
POST /api/v1/flags Create or update a feature flag configuration
PATCH /api/v1/flags/:key/toggle Instant 1-click toggle for master kill-switch
PATCH /api/v1/flags/:key/rollout Dynamically update percentage rollout (0–100%)
POST /api/v1/flags/:key/promote Promote flag configuration (e.g. ?from=staging&to=production)
POST /api/v1/webhooks/kill-switch/:key Automated kill-switch endpoint for APM alerts (Datadog/Sentry)
POST /api/v1/telemetry/events Ingest batched evaluation counts from client SDKs
GET /api/v1/telemetry/stats Query 24h evaluation velocity and variant distribution
DELETE /api/v1/flags/:key Permanently remove a feature flag (Requires Admin role)
POST /api/v1/evaluate Evaluate flags (?trace=true returns visual execution trace)
POST /api/v1/benchmark Execute live in-process latency stress test
GET /api/v1/audit-logs Fetch immutable audit trail history for active project

Multi-Tenancy Note: All evaluation, flag, and audit endpoints accept the X-Project-ID request header or ?project_id=... parameter to scope operations to a specific project (defaults to proj_default).


🌐 OpenFeature Polyglot Ecosystem

Flagura provides drop-in OpenFeature Providers across Go, TypeScript/JavaScript, and Python, ensuring zero vendor lock-in:

1. Go OpenFeature Provider (pkg/openfeature)
go get github.com/dhawalhost/flagura/pkg/openfeature
go get github.com/open-feature/go-sdk
package main

import (
	"context"
	"log"
	"time"

	"github.com/dhawalhost/flagura/pkg/client"
	flaguraOF "github.com/dhawalhost/flagura/pkg/openfeature"
	of "github.com/open-feature/go-sdk/openfeature"
)

func main() {
	// 1. Initialize Flagura client with Real-Time Streaming, Offline Snapshot, and Project Scoping
	flaguraClient := client.New("https://flagura.dhawalhost.com",
		client.WithProject("proj_default"),                  // Project scope (optional)
		client.WithLocalEvaluation(30*time.Second),
		client.WithStreaming(true),                          // <5ms instant updates via SSE
		client.WithSnapshotFile("/tmp/flagura-cache.json"),  // offline resilience
		client.WithCircuitBreaker(5, 10*time.Second),        // 3-state failure circuit breaker
	)
	defer flaguraClient.Close()

	// 2. Register Flagura as global OpenFeature Provider (includes live eventing)
	_ = of.SetProviderAndWait(flaguraOF.NewProvider(flaguraClient))

	// 3. Evaluate flags using standard OpenFeature APIs
	ofClient := of.NewClient("checkout-service")
	evalCtx := of.NewEvaluationContext("usr_alex_42", map[string]interface{}{
		"email": "alex@company.com",
		"tier":  "enterprise",
	})

	enabled, _ := ofClient.BooleanValue(context.Background(), "ai-smart-search", false, evalCtx)
	log.Printf("Flag Status: %v", enabled)
}
2. TypeScript / Node.js OpenFeature Provider (sdks/js)
import { OpenFeature } from "@openfeature/server-sdk";
import { FlaguraOpenFeatureProvider } from "flagura-sdk";

// 1. Initialize and register Flagura OpenFeature provider
const provider = new FlaguraOpenFeatureProvider({
  endpoint: "https://flagura.dhawalhost.com",
  apiKey: process.env.FLAGURA_API_KEY,
  enableStreaming: true, // <5ms live flag sync
});

await OpenFeature.setProviderAndWait(provider);
const client = OpenFeature.getClient();

// 2. Evaluate with OpenFeature context
const isEnabled = await client.getBooleanValue("ai-smart-search", false, {
  targetingKey: "usr_123",
  email: "dev@flagura.dev",
  tier: "enterprise",
});
3. Python OpenFeature Provider (sdks/python)
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from flagura.openfeature_provider import FlaguraOpenFeatureProvider

# 1. Register Flagura OpenFeature provider
api.set_provider(FlaguraOpenFeatureProvider(
    endpoint="https://flagura.dhawalhost.com",
    api_key="your-api-key",
    enable_streaming=True, # <5ms live flag sync
))
client = api.get_client()

# 2. Evaluate flags
ctx = EvaluationContext(targeting_key="usr_123", attributes={"email": "alice@flagura.dev"})
is_enabled = client.get_boolean_value("ai-smart-search", False, ctx)

⚑ Real-Time Streaming & Resilience

1. Sub-5ms SSE Flag Streaming (GET /api/v1/flags/stream)

Whenever a flag is toggled, rolled out, or promoted in the Flagura console or via API, the control plane broadcasts an instant Server-Sent Event (SSE) to all connected microservices worldwide. Your in-memory cache synchronizes in < 5ms without polling delays.

2. Offline Snapshot Persistence & 3-State Circuit Breaker
  • Offline Snapshot (WithSnapshotFile): Writes atomic snapshots to disk. If your database or control plane goes down, your application cold-boots in 0ms from disk cache with zero evaluation downtime.
  • 3-State Circuit Breaker (CLOSED ↔ OPEN ↔ HALF_OPEN): Automatically fast-fails remote network requests in < 20Β΅s during server interruptions, shielding your application from latency spikes.

🚨 Automated Alert Webhook Kill-Switches

Connect Flagura to your APM and monitoring infrastructure (Datadog, Sentry, Prometheus Alertmanager, PagerDuty):

# Example: Automated rollback webhook from Datadog alert or CI/CD
curl -X POST "https://flagura.dhawalhost.com/api/v1/webhooks/kill-switch/ai-smart-search?env=production" \
  -H "Content-Type: application/json"

When an alert triggers, Flagura instantly flips the master kill-switch and broadcasts the disable event to all microservices over SSE in < 5ms.


πŸ” Visual Rule Execution Trace ("Why Did I Get This Variant?")

Debug complex targeting rules and multivariate splits using the on-demand trace engine:

curl -X POST "https://flagura.dhawalhost.com/api/v1/evaluate?trace=true" \
  -H "Content-Type: application/json" \
  -d '{
    "flags": ["ai-smart-search"],
    "context": {
      "user_id": "usr_alex_42",
      "email": "alex@acme.com",
      "tier": "enterprise",
      "environment": "production"
    }
  }'

Trace Output:

{
  "traces": {
    "ai-smart-search": {
      "steps": [
        {
          "step_index": 1,
          "name": "Master Kill-Switch Check",
          "passed": true,
          "detail": "Flag is active in production."
        },
        {
          "step_index": 2,
          "name": "Targeting Rule Match: Enterprise VIP",
          "passed": true,
          "detail": "Condition matched (tier equals [enterprise]). Action: force_enabled."
        }
      ],
      "final_reason": "TARGETING_RULE_MATCH",
      "final_variant": "treatment",
      "final_enabled": true,
      "elapsed_ns": 78
    }
  }
}

πŸ”€ Environment Promotion (Staging βž” Production)

Promote verified rules and multivariate traffic allocations from Staging to Production in 1-click via the Dashboard or API:

curl -X POST "https://flagura.dhawalhost.com/api/v1/flags/ai-smart-search/promote?from=staging&to=production" \
  -H "Cookie: flagura_session=..."

πŸ’» Flagura Developer CLI (cmd/flagura)

Flagura includes a single-binary CLI tool for developers, terminal evaluation, and CI/CD automated rollouts:

# Build / install CLI
go build -o /usr/local/bin/flagura ./cmd/flagura
CLI Commands:
# List all feature flags and their current status
flagura list

# Instant master kill-switch toggle
flagura toggle ai-smart-search --env=production

# Update percentage rollout
flagura rollout ai-smart-search 25% --env=production

# Evaluate flag in terminal with visual execution trace
flagura evaluate ai-smart-search --user=usr_alex_42 --trace

# Promote staging configuration to production
flagura promote ai-smart-search --from=staging --to=production

# Generate a new programmatic API key
flagura api-key create --name="Production Kubernetes SDK" --role=admin

# List active API keys and their last used timestamp
flagura api-key list

# Revoke a compromised API key
flagura api-key revoke <key-id>

# Scan codebase technical debt and stale flags
flagura clean-up

πŸ’» Polyglot SDK Quickstart

1. Official Go Native SDK (pkg/client)

The built-in Go client supports sub-microsecond in-memory evaluations (cached in-process) and remote evaluations:

go get github.com/dhawalhost/flagura/pkg/client
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/dhawalhost/flagura/pkg/client"
)

func main() {
	// Initialize Flagura client with in-memory caching and offline snapshot
	c := client.New("https://flagura.dhawalhost.com",
		client.WithLocalEvaluation(30*time.Second),
		client.WithSnapshotFile("/tmp/flagura-cache.json"),
	)
	defer c.Close()

	// Evaluate flag locally in < 80 nanoseconds
	result, err := c.Evaluate(context.Background(), "ai-smart-search", client.Context{
		UserID:  "usr_dhawal_01",
		Email:   "dhawal@flagura.dev",
		Country: "US",
		Role:    "admin",
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Flag: %s | Enabled: %v | Variant: %s (in %d ns)\n",
		result.FlagKey, result.Enabled, result.Variant, result.EvaluationLatencyNs)
}

2. TypeScript / JavaScript (Node.js, Next.js, Browser)

Zero-dependency standard fetch helper for full-stack JavaScript:

interface FlagEvaluation {
  flag_key: string;
  enabled: boolean;
  variant: string;
  value: any;
  reason: string;
}

export async function evaluateFlag(
  flagKey: string,
  context: {
    userId: string;
    email?: string;
    country?: string;
    role?: string;
    environment?: string;
  },
  endpoint = "https://flagura.dhawalhost.com",
): Promise<FlagEvaluation> {
  const res = await fetch(`${endpoint}/api/v1/evaluate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      flags: [flagKey],
      context: {
        user_id: context.userId,
        email: context.email,
        country: context.country,
        role: context.role,
        environment: context.environment || "production",
      },
    }),
  });

  if (!res.ok) throw new Error(`Flagura API error: ${res.statusText}`);
  const data = await res.json();
  return data.results[flagKey];
}

// Example Usage
const flag = await evaluateFlag("ai-smart-search", {
  userId: "usr_123",
  email: "user@flagura.dev",
});
if (flag.enabled) {
  console.log("Feature active! Variant:", flag.variant);
}

3. Python (FastAPI, Django, AI Agents)
import requests

def evaluate_flag(flag_key: str, user_id: str, email: str = "", endpoint: str = "https://flagura.dhawalhost.com") -> bool:
    try:
        response = requests.post(f"{endpoint}/api/v1/evaluate", json={
            "flags": [flag_key],
            "context": {
                "user_id": user_id,
                "email": email,
                "environment": "production"
            }
        }, timeout=2.0)
        response.raise_for_status()
        data = response.json()
        return data.get("results", {}).get(flag_key, {}).get("enabled", False)
    except Exception as e:
        print(f"[WARN] Flag evaluation fallback to false: {e}")
        return False

# Example Usage
if evaluate_flag("ai-smart-search", user_id="usr_dhawal_01", email="dhawal@flagura.dev"):
    print("AI Smart Search is enabled!")

4. cURL / REST API
curl -X POST https://flagura.dhawalhost.com/api/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "flags": ["ai-smart-search"],
    "context": {
      "user_id": "usr_dhawal_01",
      "email": "dhawal@flagura.dev",
      "environment": "production"
    }
  }'

🚒 Deployment Options

Option A: Vercel Serverless (Zero Config)
  1. Push your code to GitHub.
  2. Import the project into Vercel.
  3. Under Settings -> Environment Variables, add:
    • DATABASE_URL: postgres://... (Your Supabase connection string)
    • SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD: (Optional SMTP credentials for password reset and invite emails)
  4. Click Deploy. Vercel compiles the serverless handler via api/index.go and vercel.json.
Option B: Docker Container / Self-Hosted
# Copy and configure environment variables
cp .env.example .env

# Build Docker image
docker build -t flagura:latest .

# Run container
docker run -p 3000:3000 --env-file .env flagura:latest

βš™οΈ Environment Variables Reference

See .env.example for a fully annotated template:

Variable Default Purpose
PORT 3000 HTTP listening port
DATABASE_URL (empty) PostgreSQL connection string (uses In-Memory Edge Store if empty)
FLAGURA_APP_URL http://localhost:3000 Base URL used for recovery links and redirects
ENABLE_LANDING_PAGE false false redirects directly to /auth, true displays public product showcase
SMTP_HOST (empty) SMTP hostname for password reset & welcome emails (uses terminal logger if empty)
SMTP_PORT 587 SMTP port (587 STARTTLS, 465 SMTPS)
SMTP_USERNAME / SMTP_PASSWORD (empty) SMTP authentication credentials
SMTP_FROM no-reply@localhost Sender address on all outbound transactional emails
FLAGURA_BRAND_NAME Flagura Custom brand title rendered in email headers & greetings
FLAGURA_SUPPORT_EMAIL (empty) Support address shown in footers (defaults to internal admin notice if empty)
FLAGURA_GOVERNANCE_EMAILS (empty) Comma-separated reviewer emails (auto-resolves DB admins if empty)

πŸ§ͺ Testing & Verification

Run the comprehensive unit and integration test suite:

# Run all Go tests
go test -v ./...

# Recompile Templ components
templ generate

# Build production binary
go build -o bin/flagura main.go

πŸ“š Operations & Runbooks

Comprehensive SRE, emergency response, and operational runbooks are available in the docs/runbooks/ directory:


πŸ“„ License

This project is licensed under the MIT License.

Documentation ΒΆ

The Go Gopher

There is no documentation for this package.

Directories ΒΆ

Path Synopsis
cmd
flagura command
pkg
api
client
Package client provides the official Go SDK for Flagura.
Package client provides the official Go SDK for Flagura.
openfeature
Package openfeature provides an official OpenFeature Go SDK provider for Flagura.
Package openfeature provides an official OpenFeature Go SDK provider for Flagura.
sdks
go module
web
views
templ: version: v0.3.1020
templ: version: v0.3.1020

Jump to

Keyboard shortcuts

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