Help us shape the future of Go! Take the 2026 Go Developer Survey

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.