regions

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MembershipStatusActive   = "active"
	MembershipStatusDisabled = "disabled"
)
View Source 
const (
	RegionStatusActive   = "active"
	RegionStatusDraining = "draining"
	RegionStatusDisabled = "disabled"

	DeploymentStatusPending  = "pending"
	DeploymentStatusHealthy  = "healthy"
	DeploymentStatusStale    = "stale"
	DeploymentStatusDisabled = "disabled"

	// DefaultHeartbeatTTL marks a healthy deployment stale when last_seen exceeds this.
	DefaultHeartbeatTTL = 2 * time.Minute
)

Variables

This section is empty.

Functions

func BindAllOrganizations 

func BindAllOrganizations(ctx context.Context, repo Repository, regionID string, orgIDs []string) (int, error)

BindAllOrganizations binds every org ID to the region (active). Idempotent upserts. Returns the number of organizations successfully bound.

func BuildRegionSource 

func BuildRegionSource(
	base snapshot.Source,
	memberships []OrgRegionMembership,
	overlays []RegionConfigOverlay,
) (snapshot.Source, []string)

BuildRegionSource filters base config by active memberships and applies full overlays. Returns a Source ready for snapshot.Compile and the allowlist of org IDs (always non-nil).

func DeleteOverlay 

func DeleteOverlay(ctx context.Context, repo Repository, regionID, orgID string) error

DeleteOverlay reverts the org to inherit base config in the region.

func IndexBaseByOrg 

func IndexBaseByOrg(base snapshot.Source) (map[string]OrgSlice, []snapshot.Provider)

IndexBaseByOrg splits a loaded base Source into per-org slices plus a global provider pool.

func NormalizeRegionSlug 

func NormalizeRegionSlug(slug string) string

NormalizeRegionSlug lowercases and trims a slug.

func UnbindOrgFromRegion 

func UnbindOrgFromRegion(ctx context.Context, repo Repository, regionID, orgID string) error

UnbindOrgFromRegion removes membership and any overlay.

func ValidateDeploymentStatus 

func ValidateDeploymentStatus(status string) error

ValidateDeploymentStatus checks status is a known deployment status.

func ValidateMembershipStatus 

func ValidateMembershipStatus(status string) error

ValidateMembershipStatus checks status is active or disabled.

func ValidateRegionSlug 

func ValidateRegionSlug(slug string) error

ValidateRegionSlug ensures slug is lowercase alnum with -/_ and length ≤ 64.

func ValidateRegionStatus 

func ValidateRegionStatus(status string) error

ValidateRegionStatus checks status is a known region status.

Types

type DeploymentWithToken 

type DeploymentWithToken struct {
	Deployment GatewayDeployment `json:"deployment"`
	JoinToken  string            `json:"join_token"`
}

DeploymentWithToken is returned once when a join token is minted.

func RegisterDeployment 

func RegisterDeployment(ctx context.Context, repo Repository, id, regionID, name, publicBaseURL string) (*DeploymentWithToken, error)

RegisterDeployment creates a deployment and returns the raw join token once.

func RotateJoinToken 

func RotateJoinToken(ctx context.Context, repo Repository, deploymentID string) (*DeploymentWithToken, error)

RotateJoinToken issues a new join token for a deployment.

type GatewayDeployment 

type GatewayDeployment struct {
	ID                      string     `json:"id"`
	RegionID                string     `json:"region_id"`
	Name                    string     `json:"name"`
	PublicBaseURL           string     `json:"public_base_url,omitempty"`
	JoinTokenHash           string     `json:"-"`
	Status                  string     `json:"status"`
	LastSeenAt              *time.Time `json:"last_seen_at,omitempty"`
	ReportedSnapshotVersion int64      `json:"reported_snapshot_version"`
	ReportedBuild           string     `json:"reported_build,omitempty"`
	CreatedAt               time.Time  `json:"created_at"`
	UpdatedAt               time.Time  `json:"updated_at"`
}

GatewayDeployment is a registered spoke gateway (or HA group) in a region.

func AuthenticateJoinToken 

func AuthenticateJoinToken(ctx context.Context, repo Repository, rawToken string) (*GatewayDeployment, error)

AuthenticateJoinToken resolves a deployment by raw join token.

func GetDeployment 

func GetDeployment(ctx context.Context, repo Repository, deploymentID string, ttl time.Duration) (*GatewayDeployment, error)

GetDeployment returns a deployment with EffectiveStatus applied.

func ListDeployments 

func ListDeployments(ctx context.Context, repo Repository, regionID string, ttl time.Duration) ([]GatewayDeployment, error)

ListDeployments returns deployments with EffectiveStatus applied.

func NewGatewayDeployment 

func NewGatewayDeployment(id, regionID, name, publicBaseURL, joinTokenHash string, now time.Time) (*GatewayDeployment, error)

NewGatewayDeployment builds a validated deployment entity (pending, with join token hash).

func RecordHeartbeat 

func RecordHeartbeat(ctx context.Context, repo Repository, deploymentID, joinTokenHash string, snapVersion int64, build string) (*GatewayDeployment, error)

RecordHeartbeat authenticates by join token hash and updates liveness.

func (GatewayDeployment) EffectiveStatus 

func (d GatewayDeployment) EffectiveStatus(now time.Time, ttl time.Duration) string

EffectiveStatus returns the stored status, or stale when a healthy deployment has not heartbeated within ttl.

type OrgRegionMembership 

type OrgRegionMembership struct {
	OrganizationID string    `json:"organization_id"`
	RegionID       string    `json:"region_id"`
	Status         string    `json:"status"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

OrgRegionMembership binds an organization to a region.

func BindOrgToRegion 

func BindOrgToRegion(ctx context.Context, repo Repository, regionID, orgID, status string) (*OrgRegionMembership, error)

BindOrgToRegion creates or updates membership.

func NewOrgRegionMembership 

func NewOrgRegionMembership(orgID, regionID, status string, now time.Time) (*OrgRegionMembership, error)

NewOrgRegionMembership builds a validated membership.

type OrgSlice 

type OrgSlice struct {
	APIKeys      []snapshot.APIKey
	SigningKeys  []snapshot.SigningKey
	Providers    []snapshot.Provider // may be empty; providers resolved globally after merge
	Routes       []snapshot.Route
	Quotas       []snapshot.Quota
	Policies     []snapshot.Policy
	WasmHooks    []snapshot.WasmHook
	MCPBackends  []snapshot.MCPBackend
	A2AAgents    []snapshot.A2AAgent
	Credentials  []snapshot.Credential
	Assignments  []snapshot.CredentialAssignment
	DefaultRetry *snapshot.RetryConfig
	ObjectStore  *snapshot.ObjectStoreConfig
}

OrgSlice is one organization's contribution to a snapshot.Source.

func OverlayToSlice 

func OverlayToSlice(orgID string, baseKeys OrgSlice, payload OverlayPayload) OrgSlice

OverlayToSlice converts an overlay payload into an OrgSlice (keys come from base).

type OverlayPayload 

type OverlayPayload struct {
	Providers    []snapshot.Provider             `json:"providers,omitempty"`
	Routes       []snapshot.Route                `json:"routes,omitempty"`
	Quotas       []snapshot.Quota                `json:"quotas,omitempty"`
	Policies     []snapshot.Policy               `json:"policies,omitempty"`
	WasmHooks    []snapshot.WasmHook             `json:"wasm_hooks,omitempty"`
	MCPBackends  []snapshot.MCPBackend           `json:"mcp_backends,omitempty"`
	A2AAgents    []snapshot.A2AAgent             `json:"a2a_agents,omitempty"`
	Credentials  []snapshot.Credential           `json:"credentials,omitempty"`
	Assignments  []snapshot.CredentialAssignment `json:"assignments,omitempty"`
	DefaultRetry *snapshot.RetryConfig           `json:"default_retry,omitempty"`
	ObjectStore  *snapshot.ObjectStoreConfig     `json:"object_store,omitempty"`
}

OverlayPayload holds gateway-relevant config kinds (snapshot compile shapes).

func UnmarshalOverlayPayload 

func UnmarshalOverlayPayload(raw []byte) (OverlayPayload, error)

UnmarshalOverlayPayload decodes JSON into OverlayPayload.

func (OverlayPayload) MarshalPayload 

func (p OverlayPayload) MarshalPayload() ([]byte, error)

MarshalPayload encodes overlay payload as JSON.

type Region 

type Region struct {
	ID        string    `json:"id"`
	Slug      string    `json:"slug"`
	Name      string    `json:"name"`
	Status    string    `json:"status"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Region is a logical isolation boundary for gateway deployments.

func CreateRegion 

func CreateRegion(ctx context.Context, repo Repository, id, slug, name string) (*Region, error)

CreateRegion creates a validated region.

func NewRegion 

func NewRegion(id, slug, name string, now time.Time) (*Region, error)

NewRegion builds a validated region entity.

func UpdateRegion 

func UpdateRegion(ctx context.Context, repo Repository, regionID, name, status string) (*Region, error)

UpdateRegion patches name and/or status.

type RegionConfigOverlay 

type RegionConfigOverlay struct {
	OrganizationID string         `json:"organization_id"`
	RegionID       string         `json:"region_id"`
	Payload        OverlayPayload `json:"payload"`
	CreatedAt      time.Time      `json:"created_at"`
	UpdatedAt      time.Time      `json:"updated_at"`
}

RegionConfigOverlay is a full replacement gateway config slice for one org in one region. When present, BuildRegionSource uses this instead of the org's base config.

func NewRegionConfigOverlay 

func NewRegionConfigOverlay(orgID, regionID string, payload OverlayPayload, now time.Time) (*RegionConfigOverlay, error)

NewRegionConfigOverlay builds an overlay entity; payload must be valid JSON-serializable.

func PutOverlay 

func PutOverlay(ctx context.Context, repo Repository, regionID, orgID string, payload OverlayPayload) (*RegionConfigOverlay, error)

PutOverlay upserts a full replacement overlay for a bound org.

type Repository 

type Repository interface {
	CreateRegion(ctx context.Context, r Region) error
	GetRegion(ctx context.Context, regionID string) (*Region, error)
	GetRegionBySlug(ctx context.Context, slug string) (*Region, error)
	ListRegions(ctx context.Context) ([]Region, error)
	UpdateRegion(ctx context.Context, regionID, name, status string) (*Region, error)
	CountDeployments(ctx context.Context, regionID string) (int, error)

	InsertDeployment(ctx context.Context, d GatewayDeployment) error
	GetDeployment(ctx context.Context, deploymentID string) (*GatewayDeployment, error)
	ListDeploymentsByRegion(ctx context.Context, regionID string) ([]GatewayDeployment, error)
	UpdateJoinTokenHash(ctx context.Context, deploymentID, joinTokenHash string) error
	RecordHeartbeat(ctx context.Context, deploymentID string, snapVersion int64, build string, at time.Time) error
	GetDeploymentByJoinTokenHash(ctx context.Context, tokenHash string) (*GatewayDeployment, error)
	UpdateDeploymentStatus(ctx context.Context, deploymentID, status string) error

	ListMembershipsByRegion(ctx context.Context, regionID string) ([]OrgRegionMembership, error)
	ListMembershipsByOrg(ctx context.Context, orgID string) ([]OrgRegionMembership, error)
	GetMembership(ctx context.Context, regionID, orgID string) (*OrgRegionMembership, error)
	UpsertMembership(ctx context.Context, m OrgRegionMembership) error
	DeleteMembership(ctx context.Context, regionID, orgID string) error

	GetOverlay(ctx context.Context, regionID, orgID string) (*RegionConfigOverlay, error)
	ListOverlaysByRegion(ctx context.Context, regionID string) ([]RegionConfigOverlay, error)
	UpsertOverlay(ctx context.Context, o RegionConfigOverlay) error
	DeleteOverlay(ctx context.Context, regionID, orgID string) error
}

Repository persists regions and gateway deployments.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.