federation

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 (
	PeerStatusPending  = "pending"
	PeerStatusActive   = "active"
	PeerStatusDisabled = "disabled"
)

Variables

This section is empty.

Functions

func ApplyExport 

func ApplyExport(ctx context.Context, repo Repository, target ApplyTarget, exp *RegionExport) error

ApplyExport upserts region topology + memberships/overlays and stores the embedded snapshot.

func BumpRevision 

func BumpRevision(ctx context.Context, repo Repository) (int64, error)

BumpRevision advances the hub federation revision (call after membership/overlay/publish).

func ValidatePeerStatus 

func ValidatePeerStatus(status string) error

ValidatePeerStatus checks peer status.

Types

type ApplyTarget 

type ApplyTarget interface {
	EnsureRegion(ctx context.Context, id, slug, name string) error
	ReplaceMemberships(ctx context.Context, regionID string, mems []regions.OrgRegionMembership) error
	ReplaceOverlays(ctx context.Context, regionID string, overlays []regions.RegionConfigOverlay) error
	PutSnapshot(ctx context.Context, snap *snapshot.Snapshot) (int64, error)
}

ApplyTarget applies a pulled export onto a regional control plane.

type ControlPlanePeer 

type ControlPlanePeer struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	RegionID      string `json:"region_id"`
	BaseURL       string `json:"base_url,omitempty"`
	Status        string `json:"status"`
	JoinTokenHash string `json:"-"`
	// JoinTokenEnc is the hub-sealed join token for on-demand regional pulls (never exported).
	JoinTokenEnc   []byte     `json:"-"`
	LastSyncAt     *time.Time `json:"last_sync_at,omitempty"`
	LastSyncCursor int64      `json:"last_sync_cursor"`
	LastSyncError  string     `json:"last_sync_error,omitempty"`
	CreatedAt      time.Time  `json:"created_at"`
	UpdatedAt      time.Time  `json:"updated_at"`
}

ControlPlanePeer is a registered regional control plane trusted by the hub.

func AuthenticatePeerToken 

func AuthenticatePeerToken(ctx context.Context, repo Repository, rawToken string) (*ControlPlanePeer, error)

AuthenticatePeerToken resolves a peer by raw join token and marks it active on first use.

func Join 

func Join(ctx context.Context, repo Repository, rawToken string) (*ControlPlanePeer, error)

Join exchanges a join token for peer identity (activates pending peers).

func NewControlPlanePeer 

func NewControlPlanePeer(id, name, regionID, baseURL, joinTokenHash string, now time.Time) (*ControlPlanePeer, error)

NewControlPlanePeer builds a validated peer.

func UpdatePeer 

func UpdatePeer(ctx context.Context, repo Repository, peerID, name, baseURL, status string) (*ControlPlanePeer, error)

UpdatePeer patches name, base URL, and/or status.

type ExportSource 

type ExportSource interface {
	GetRegionBySlug(ctx context.Context, slug string) (*regions.Region, error)
	ListMembershipsByRegion(ctx context.Context, regionID string) ([]regions.OrgRegionMembership, error)
	ListOverlaysByRegion(ctx context.Context, regionID string) ([]regions.RegionConfigOverlay, error)
	LatestRegionalSnapshot(ctx context.Context, regionSlug string) (*snapshot.Snapshot, error)
}

ExportSource loads region-scoped data for a federation export.

type PeerWithToken 

type PeerWithToken struct {
	Peer      ControlPlanePeer `json:"peer"`
	JoinToken string           `json:"join_token"`
}

PeerWithToken is returned once when a join token is minted.

func RegisterPeer 

func RegisterPeer(ctx context.Context, repo Repository, lookup RegionLookup, id, name, regionID, baseURL string) (*PeerWithToken, error)

RegisterPeer creates a regional CP peer and returns the join token once.

func RotatePeerJoinToken 

func RotatePeerJoinToken(ctx context.Context, repo Repository, peerID string) (*PeerWithToken, error)

RotatePeerJoinToken issues a new join token.

type RegionExport 

type RegionExport struct {
	Revision     int64                         `json:"revision"`
	RegionSlug   string                        `json:"region_slug"`
	RegionID     string                        `json:"region_id"`
	Memberships  []regions.OrgRegionMembership `json:"memberships"`
	Overlays     []regions.RegionConfigOverlay `json:"overlays"`
	SnapshotMeta SnapshotMeta                  `json:"snapshot_meta"`
	// Snapshot is the compiled regional snapshot when available (hub embed for regional put).
	Snapshot *snapshot.Snapshot `json:"snapshot,omitempty"`
}

RegionExport is the pull-sync document for one region.

func BuildRegionExport 

func BuildRegionExport(ctx context.Context, repo Repository, src ExportSource, regionSlug string, since int64, objectPrefix string) (*RegionExport, error)

BuildRegionExport assembles a pull document for the given region slug. When since >= current revision (and since > 0), memberships/overlays/snapshot are omitted.

type RegionLookup 

type RegionLookup interface {
	GetRegion(ctx context.Context, regionID string) (*regions.Region, error)
	GetRegionBySlug(ctx context.Context, slug string) (*regions.Region, error)
}

RegionLookup resolves regions for peer registration and export.

type Repository 

type Repository interface {
	CreatePeer(ctx context.Context, p ControlPlanePeer) error
	GetPeer(ctx context.Context, peerID string) (*ControlPlanePeer, error)
	GetPeerByJoinTokenHash(ctx context.Context, hash string) (*ControlPlanePeer, error)
	ListPeers(ctx context.Context) ([]ControlPlanePeer, error)
	UpdatePeer(ctx context.Context, peerID, name, baseURL, status string) (*ControlPlanePeer, error)
	UpdatePeerJoinTokenHash(ctx context.Context, peerID, hash string) error
	// UpdatePeerJoinTokenEnc stores the hub-sealed join token used for usage report pulls.
	UpdatePeerJoinTokenEnc(ctx context.Context, peerID string, enc []byte) error
	RecordPeerSync(ctx context.Context, peerID string, cursor int64, at time.Time, syncErr string) error

	GetRevision(ctx context.Context) (int64, error)
	BumpRevision(ctx context.Context) (int64, error)

	GetSyncState(ctx context.Context, regionSlug string) (*SyncState, error)
	UpsertSyncState(ctx context.Context, st SyncState) error
}

Repository persists federation peers and sync metadata on the hub (and regional sync state).

type SnapshotMeta 

type SnapshotMeta struct {
	Version      int64  `json:"version"`
	ObjectPrefix string `json:"object_prefix,omitempty"`
}

SnapshotMeta locates the compiled regional snapshot on the hub.

type SyncState 

type SyncState struct {
	RegionSlug    string     `json:"region_slug"`
	Cursor        int64      `json:"cursor"`
	LastSyncAt    *time.Time `json:"last_sync_at,omitempty"`
	LastSyncError string     `json:"last_sync_error,omitempty"`
	UpdatedAt     time.Time  `json:"updated_at"`
}

SyncState is the regional CP's last applied hub revision.

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.