Files
zeekayandHanzo Dev 635fbb7c0c Hanzo Cloud — OSS core (Apache-2.0)
The single Go binary that runs the compute/backend control plane: KMS secrets,
object storage, DNS/provisioning, PaaS, code + exec, zero-trust sharing, audit,
gateway edge, feature flags, security, and the plugin runtime — every subsystem
mounted from one composition root.

Open-core by construction, not by deletion. The proprietary planes — identity,
commerce, AI inference, observability, the message bus, billing — are injected
through the cloud/types extension interfaces, so this binary links only public
infrastructure libraries and a missing plane mounts fail-closed and says so
rather than pretending to work.

Published from a fresh root rather than a filtered history: the extraction it
came from began life without git, and a squashed root is the only way to be sure
no earlier blob travels with it.

Runs on a laptop with no Kubernetes, no cluster and no external services —
`CLOUD_DEV_UNENCRYPTED=1 cloud -data-dir /tmp/cloud` boots ~32 subsystems on
HTTP and ZAP. Encryption at rest stays fatal-by-default on a capable build; the
dev flag relaxes only the no-key case, loudly.

Co-authored-by: Hanzo Dev <[email protected]>
2026-08-04 22:20:29 -07:00

482 lines
16 KiB
Go

// Package flags is cloud's NATIVE feature-flag engine: definitions live in
// per-(org, project) SQLite (cloud.OrgDB — {DataDir}/orgs/{org}/projects/{project}/
// flags.db, encrypted at rest via cek) and evaluation runs in-process through the
// embedded hanzo-flags Rust evaluator (native/flags, FFI) with PostHog-compatible
// semantics: rollout hash, full property-operator set, variants, payloads. Stateless
// and scalable by construction — no KV, no network hop, every pod evaluates from its
// own hot in-memory copy of the definitions.
//
// TWO surfaces, ONE engine:
//
// - /v1/flags — the product API (org-scoped via the gateway principal): evaluate
// flags for a distinct_id + properties, manage definitions, read the activity
// log. PostHog-shaped responses so existing SDK consumers port 1:1.
//
// - the PLATFORM switches — the launch/ops knobs the SuperAdmin flips from
// admin.hanzo.ai (registry below). They evaluate from the reserved
// platform/platform store through the same engine. A switch with no stored
// definition falls back env -> literal default — exactly the pre-engine
// behavior, zero regression; the first cockpit write creates the definition
// and takes effect within one cache TTL (default 15s), no redeploy.
//
// FAIL-SAFE. When the native engine is absent (!cgo) or a store read fails,
// evaluation degrades to env fallback -> literal default and the HTTP surface says
// so honestly — never fail-wrong.
//
// ── THE POLICY PRIMITIVE ─────────────────────────────────────────────────────────
//
// This engine IS Hanzo's runtime decision primitive: (Principal, context) -> verdict,
// evaluated in-process, stateless, hot. It knows ONLY flags — definitions, evaluation,
// and the platform-switch registry. It has ZERO knowledge of any specific policy that
// rides on it: no host→service map, no waitlist, no service registry. Those COMPOSE
// this engine from the OUTSIDE, one-way (they import flags; flags imports none of them):
//
// - the launch waitlist gate (clients/admission) — a service's mode IS the switch
// waitlist.<svc>; admission owns the host→service registry + Enforce and reads the
// mode through flags.Bool. It USED to live in this package; extracting it is the
// PROOF the engine composes its tenants rather than absorbing them.
// - authz (access policy) — (Principal, resource+action) -> allow/deny
// - entitlements (product-access policy) — (Principal, feature/plan) -> granted/denied
//
// Every one is (Principal, context) -> verdict. Folding them onto this evaluator makes
// Policy ONE composable primitive with one audit log and one hot-apply path. authz and
// entitlements are NOT built on it yet — this note only names the target so the seam
// stays visible; the launch waitlist (now external) is the first, proven composition.
package flags
import (
"context"
"encoding/json"
"fmt"
"os"
"strconv"
"strings"
"sync"
"time"
"github.com/hanzoai/cloud"
"github.com/zap-proto/zip"
)
// Type is the switch kind the cockpit renders (and how the value is decoded).
type Type string
const (
TypeBool Type = "bool"
TypeInt Type = "int"
TypeString Type = "string"
)
// The reserved store the platform switches evaluate from.
const (
platformOrg = "platform"
platformProject = "platform"
)
// Def is ONE platform switch: a flag key qualified by the metadata the cockpit shows
// and the env var that provides the fallback default. This table is the ONE place the
// platform switches are named; the embedded engine evaluates them.
type Def struct {
Key string // the flag key (snake_case)
Category string // Launch | Signup | Subsystems | Gateway | Network
Label string
Desc string
Type Type
Env string // env var supplying the fallback default (may be "")
Default string // literal fallback when neither the store nor env has a value
ReadOnly bool // surfaced read-only (boot-time activation, network ids)
}
// ── registry (open + extensible) ────────────────────────────────────────────────
var (
regMu sync.RWMutex
defs []Def
index = map[string]int{}
)
// Register adds a switch to the platform-flag registry. Any subsystem may call it (in
// its init) to surface its own flag in the cockpit — the registry is open, not
// hardcoded. A duplicate key REPLACES the prior def (last registration wins).
func Register(d Def) {
regMu.Lock()
defer regMu.Unlock()
if i, ok := index[d.Key]; ok {
defs[i] = d
return
}
index[d.Key] = len(defs)
defs = append(defs, d)
}
// Defs returns a snapshot of the registered switches in registration order.
func Defs() []Def {
regMu.RLock()
defer regMu.RUnlock()
out := make([]Def, len(defs))
copy(out, defs)
return out
}
func lookupDef(key string) (Def, bool) {
regMu.RLock()
defer regMu.RUnlock()
if i, ok := index[key]; ok {
return defs[i], true
}
return Def{}, false
}
// ── evaluation client ──────────────────────────────────────────────────────────
// snapshot is one cached evaluation of the platform project's flags.
type snapshot struct {
flags map[string]json.RawMessage // featureFlags[key] (bool | variant string)
payloads map[string]json.RawMessage // featureFlagPayloads[key] (arbitrary JSON)
at time.Time
ok bool
}
// Client is the in-process evaluation seam: per-(org, project) SQLite definition
// stores + the embedded native evaluator, with the platform project's evaluation
// cached for one TTL (the hot-apply bound).
type Client struct {
stores *cloud.OrgStore[*Store]
distinctID string
ttl time.Duration
mu sync.RWMutex
snap snapshot
}
var mounted *Client
func (c *Client) configured() bool { return c != nil && c.stores != nil && engineAvailable }
// evaluateProject runs the native engine over one (org, project) store for one
// evaluation context. The definitions read is a local SQLite scan; the evaluation
// is a pure in-memory FFI call.
func (c *Client) evaluateProject(org, project string, ctx []byte) (json.RawMessage, error) {
if !c.configured() {
return nil, fmt.Errorf("flags: engine not configured")
}
st, err := c.stores.For(org, project)
if err != nil {
return nil, err
}
defsJSON, n, err := st.DefsJSON()
if err != nil {
return nil, err
}
if n == 0 {
return json.RawMessage(`{"featureFlags":{},"featureFlagPayloads":{},"errorsWhileComputingFlags":false}`), nil
}
return engineEvaluate(defsJSON, ctx)
}
// resolve returns a switch's live string value and its source. A stored platform flag
// wins when it has a value; else the env fallback; else the literal default. Nil-safe.
func (c *Client) resolve(def Def) (value string, source string) {
if c.configured() {
fv, pv, present := c.lookup(def.Key)
if present {
switch def.Type {
case TypeBool:
if b, ok := asBool(fv); ok {
return strconv.FormatBool(b), "flags"
}
case TypeInt:
if n, ok := asInt(pv); ok {
return strconv.Itoa(n), "flags"
}
if n, ok := asInt(fv); ok {
return strconv.Itoa(n), "flags"
}
case TypeString:
if s, ok := asString(pv); ok && s != "" {
return s, "flags"
}
if s, ok := asString(fv); ok && s != "" {
return s, "flags"
}
}
}
}
if def.Env != "" {
if ev := strings.TrimSpace(os.Getenv(def.Env)); ev != "" {
return ev, "env"
}
}
return def.Default, "default"
}
func (c *Client) lookup(key string) (fv, pv json.RawMessage, present bool) {
c.ensureFresh()
c.mu.RLock()
defer c.mu.RUnlock()
var inFlags, inPayloads bool
fv, inFlags = c.snap.flags[key]
pv, inPayloads = c.snap.payloads[key]
return fv, pv, inFlags || inPayloads
}
// ensureFresh re-evaluates the platform project when the snapshot is older than the
// TTL. On an evaluation error the previous snapshot is kept (graceful degradation)
// and the clock is stamped so a persistent failure is retried at most once per TTL.
func (c *Client) ensureFresh() {
c.mu.RLock()
fresh := c.snap.ok && time.Since(c.snap.at) < c.ttl
c.mu.RUnlock()
if fresh {
return
}
c.mu.Lock()
defer c.mu.Unlock()
if c.snap.ok && time.Since(c.snap.at) < c.ttl {
return
}
ctx, _ := json.Marshal(map[string]string{"distinct_id": c.distinctID})
res, err := c.evaluateProject(platformOrg, platformProject, ctx)
if err != nil {
c.snap.at = time.Now() // keep last values; bound retry to one per TTL
return
}
var out struct {
FeatureFlags map[string]json.RawMessage `json:"featureFlags"`
FeatureFlagPayloads map[string]json.RawMessage `json:"featureFlagPayloads"`
}
if err := json.Unmarshal(res, &out); err != nil {
c.snap.at = time.Now()
return
}
if out.FeatureFlags == nil {
out.FeatureFlags = map[string]json.RawMessage{}
}
if out.FeatureFlagPayloads == nil {
out.FeatureFlagPayloads = map[string]json.RawMessage{}
}
c.snap = snapshot{flags: out.FeatureFlags, payloads: out.FeatureFlagPayloads, at: time.Now(), ok: true}
}
// invalidate drops the cached platform snapshot so the next read re-evaluates
// (a cockpit write applies immediately in this pod; peers converge within TTL).
func (c *Client) invalidate() {
c.mu.Lock()
c.snap = snapshot{}
c.mu.Unlock()
}
// SetPlatformSwitch stores/overwrites a platform switch's definition (the admin
// cockpit's ONE write path) and applies it immediately in this pod.
func SetPlatformSwitch(key string, definition json.RawMessage, actor string) error {
c := mounted
if c == nil || c.stores == nil {
return fmt.Errorf("flags: not mounted")
}
st, err := c.stores.For(platformOrg, platformProject)
if err != nil {
return err
}
if err := st.Upsert(key, definition, actor); err != nil {
return err
}
c.invalidate()
return nil
}
// ── value parsers (tolerant of PostHog bool/variant/payload shapes) ─────────────
func asBool(raw json.RawMessage) (bool, bool) {
t := strings.TrimSpace(string(raw))
if t == "true" {
return true, true
}
if t == "false" {
return false, true
}
if t == "" || t == "null" {
return false, false
}
var s string
if json.Unmarshal(raw, &s) == nil {
switch strings.ToLower(strings.TrimSpace(s)) {
case "true", "1", "on", "yes":
return true, true
case "false", "0", "off", "no":
return false, true
case "":
return false, false
default:
return true, true // enabled with a variant
}
}
return false, false
}
func asInt(raw json.RawMessage) (int, bool) {
t := strings.TrimSpace(string(raw))
if t == "" || t == "null" {
return 0, false
}
var n json.Number
if json.Unmarshal(raw, &n) == nil {
if i, err := n.Int64(); err == nil {
return int(i), true
}
if f, err := n.Float64(); err == nil {
return int(f), true
}
}
var s string
if json.Unmarshal(raw, &s) == nil {
if i, err := strconv.Atoi(strings.TrimSpace(s)); err == nil {
return i, true
}
}
return 0, false
}
func asString(raw json.RawMessage) (string, bool) {
t := strings.TrimSpace(string(raw))
if t == "" || t == "null" {
return "", false
}
var s string
if json.Unmarshal(raw, &s) == nil {
return s, true
}
return t, true
}
// ── typed live accessors (the in-process evaluation seam) ───────────────────────
// Bool returns the live boolean value of a registered switch (flags -> env -> default).
func Bool(key string) bool {
def, ok := lookupDef(key)
if !ok {
return false
}
v, _ := mounted.resolve(def)
b, _ := strconv.ParseBool(strings.TrimSpace(v))
return b
}
// Int returns the live integer value of a registered switch.
func Int(key string) int {
def, ok := lookupDef(key)
if !ok {
return 0
}
v, _ := mounted.resolve(def)
n, _ := strconv.Atoi(strings.TrimSpace(v))
return n
}
// String returns the live string value of a registered switch.
func String(key string) string {
def, ok := lookupDef(key)
if !ok {
return ""
}
v, _ := mounted.resolve(def)
return v
}
// ── admin control-plane board ──────────────────────────────────────────────────
// SwitchView is one platform switch as the admin cockpit renders it: the live value +
// where it came from (flags | env | default).
type SwitchView struct {
Key string `json:"key"`
Category string `json:"category"`
Label string `json:"label"`
Description string `json:"description"`
Type string `json:"type"`
Value string `json:"value"`
Source string `json:"source"`
Env string `json:"env,omitempty"`
ReadOnly bool `json:"readOnly"`
}
// BoardView is the full control-plane read board: the engine status plus every
// switch's live value. Definitions are edited in place over /v1/flags (the cockpit
// writes through SetPlatformSwitch); the activity log is the native change audit.
type BoardView struct {
Engine string `json:"engine"`
Configured bool `json:"configured"`
ManageURL string `json:"manageUrl"`
AuditURL string `json:"auditUrl"`
Switches []SwitchView `json:"switches"`
}
// Board evaluates every registered switch live and returns the cockpit read board.
func Board() BoardView {
list := Defs()
sw := make([]SwitchView, 0, len(list))
for _, d := range list {
val, src := mounted.resolve(d)
sw = append(sw, SwitchView{
Key: d.Key, Category: d.Category, Label: d.Label, Description: d.Desc,
Type: string(d.Type), Value: val, Source: src, Env: d.Env, ReadOnly: d.ReadOnly,
})
}
return BoardView{Engine: "hanzo-flags", Configured: mounted.configured(), ManageURL: "/v1/flags/defs", AuditURL: "/v1/flags/activity", Switches: sw}
}
// ── lifecycle ────────────────────────────────────────────────────────────────
type state struct {
client *Client
}
// Mount opens the per-org definition stores, installs the process-wide evaluation
// seam, and registers the /v1/flags surface. The native engine being absent (!cgo)
// degrades every switch to env/default and the HTTP surface reports it — never an
// error at boot.
func Mount(app *zip.App, deps cloud.Deps) error {
if deps.Logger == nil {
return fmt.Errorf("flags.Mount: nil deps.Logger")
}
if deps.DataDir == "" {
return fmt.Errorf("flags.Mount: empty deps.DataDir")
}
log := deps.Logger.New("subsystem", "flags")
c := &Client{
stores: cloud.NewOrgStore[*Store](deps.DataDir, "flags", openStore),
distinctID: firstNonEmpty(os.Getenv("FLAGS_PLATFORM_DISTINCT_ID"), "hanzo-platform:"+firstNonEmpty(deps.Brand, "hanzo")),
ttl: ttlFromEnv(),
}
mounted = c
b := cloud.NewBase(deps, "flags")
svc := &cloud.Service[state]{Base: b, State: state{client: c}}
routes(app, svc)
log.Info("flags engine ready", "engine", "hanzo-flags", "native", engineAvailable, "ttlSeconds", int(c.ttl.Seconds()), "switches", len(Defs()))
return nil
}
// Shutdown closes every open per-org definitions store.
func Shutdown(_ context.Context) error {
if mounted == nil || mounted.stores == nil {
return nil
}
return mounted.stores.CloseAll()
}
func ttlFromEnv() time.Duration {
if v := strings.TrimSpace(os.Getenv("FLAGS_TTL_SECONDS")); v != "" {
if n, err := strconv.Atoi(v); err == nil && n > 0 {
return time.Duration(n) * time.Second
}
}
return 15 * time.Second
}
func firstNonEmpty(vals ...string) string {
for _, v := range vals {
if strings.TrimSpace(v) != "" {
return v
}
}
return ""
}