region

Documentation

Overview

Package region implements multi-region awareness for nSelf deployments (B49).

All code paths in this package are gated by the feature flag "multi_region_enabled". When the flag is off (default), all traffic continues to route to the primary region as before — zero user impact.

Status: PLANNED — deferred. Requires UD-12 minor release approval. Dependencies: B46 (multi-tenant controller), B47/B48 (blue-green deploy).

Index

• Constants
• type Config
  • func Load() (*Config, error)
  • func (c *Config) Add(r Region) error
  • func (c *Config) EnvVars() map[string]string
  • func (c *Config) Primary() *Region
  • func (c *Config) Promote(id string) error
  • func (c *Config) ReplicaIDs() string
  • func (c *Config) Save() error
• type Region
• type RoutingStrategy

Constants

const FeatureFlag = "multi_region_enabled"

FeatureFlag is the flag key that gates all multi-region behavior.

Types

type Config

type Config struct {
	Regions         []Region        `json:"regions"`
	RoutingStrategy RoutingStrategy `json:"routing_strategy"`
}

Config holds the persisted multi-region configuration.

func Load

func Load() (*Config, error)

Load reads the region configuration from disk. Returns an empty Config with primary-only routing if the file does not exist.

func (*Config) Add

func (c *Config) Add(r Region) error

Add appends a new region. Returns an error if a region with the same ID already exists.

func (*Config) EnvVars

func (c *Config) EnvVars() map[string]string

EnvVars returns the environment variables that should be set for region-aware routing. Used by nself build to inject into docker-compose.

func (*Config) Primary

func (c *Config) Primary() *Region

Primary returns the primary region. Returns nil if none is marked primary.

func (*Config) Promote

func (c *Config) Promote(id string) error

Promote makes the named region the new primary. The previous primary is demoted to a replica. Returns an error if the region is not found.

func (*Config) ReplicaIDs

func (c *Config) ReplicaIDs() string

ReplicaIDs returns a comma-separated list of non-primary region IDs, matching the NSELF_REPLICA_REGIONS env var format.

func (*Config) Save

func (c *Config) Save() error

Save writes the region configuration to disk (mode 0600).

type Region

type Region struct {
	ID       string    `json:"id"`
	Primary  bool      `json:"primary"`
	PgURL    string    `json:"pg_url"`
	RedisURL string    `json:"redis_url,omitempty"`
	AddedAt  time.Time `json:"added_at"`
}

Region describes a single nSelf deployment region.

type RoutingStrategy

type RoutingStrategy string

RoutingStrategy controls how reads are distributed across regions.

const (
	// RoutingLatency routes reads to the nearest region based on latency.
	RoutingLatency RoutingStrategy = "latency"
	// RoutingRoundRobin distributes reads evenly across regions.
	RoutingRoundRobin RoutingStrategy = "round-robin"
	// RoutingPrimaryOnly forces all traffic to the primary region.
	RoutingPrimaryOnly RoutingStrategy = "primary-only"
)