controlstate

package
v0.1.0-rc.28 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: MIT Imports: 46 Imported by: 0

Documentation

Overview

Package controlstate stores persistent control state in PostgreSQL and changes that state in transactions. It also manages schema migrations.

Index

Constants

View Source 
const (
	MaxDatabaseDiagnosticSessions   = 64
	MaxDatabaseDiagnosticBlockers   = 8
	MaxDatabaseDiagnosticOperations = 64
	MaxDatabaseDiagnosticBytes      = 64 << 10
)

Private diagnostic limits are shared with collectors. Eight blocker PIDs per session keep a maximum-shaped snapshot within 64 KiB, leaving room for eight snapshots alongside the benchmark's periodic and failure metrics windows.

View Source 
const MaximumIngressRoutingTablePageSize = 1000

Variables

View Source 
var (
	ErrAdminInvalid               = errors.New("controlstate: invalid administration request")
	ErrMaintenanceControlNotFound = errors.New("controlstate: maintenance control not found")
)
View Source 
var (
	ErrControlAuthentication = errors.New("controlstate: invalid control credential")
	ErrControlIdentity       = errors.New("controlstate: identity is unavailable")
	ErrManagedDomainMismatch = errors.New("controlstate: configured managed deployment domain changed")
	ErrOIDCAssertionReplay   = errors.New("controlstate: OIDC assertion was already exchanged")
)
View Source 
var (
	ErrCertificateIssuanceGated       = errors.New("controlstate: certificate issuance is disabled")
	ErrCertificateIssuanceIdempotency = errors.New("controlstate: certificate issuance idempotency conflict")
	ErrCertificateIssuanceInvalid     = errors.New("controlstate: certificate issuance request is invalid")
	ErrCertificateIssuanceNotFound    = errors.New("controlstate: certificate issuance not found")
	ErrCertificateChallengeNotReady   = errors.New("controlstate: certificate challenge is not ready for acknowledgement")
)
View Source 
var (
	ErrDNSAuthorityWorkStale   = errors.New("controlstate: DNS authority work lease is stale")
	ErrDNSAuthorityIdempotency = errors.New("controlstate: DNS authority idempotency conflict")
	ErrDNSAuthorityInvalid     = errors.New("controlstate: DNS authority request is invalid")
	ErrDNSAuthorityNotFound    = errors.New("controlstate: DNS authority not found")
)
View Source 
var (
	ErrDNSRouteWorkStale = errors.New("controlstate: DNS route work lease is stale")
	ErrDNSRouteInvalid   = errors.New("controlstate: DNS route work is invalid")
)
View Source 
var (
	ErrIngressAlreadyRunning = errors.New("controlstate: ingress identity already has a live process run")
	ErrIngressLeaseStale     = errors.New("controlstate: ingress lease identity or revision is stale")
)
View Source 
var (
	ErrRelayCertificateWorkStale   = errors.New("controlstate: relay certificate work lease is stale")
	ErrRelayCertificateWorkInvalid = errors.New("controlstate: relay certificate work is invalid")
)
View Source 
var (
	ErrRelayTransportCertificateInvalid    = errors.New("controlstate: relay transport certificate is invalid")
	ErrRelayTransportCertificateNotFound   = errors.New("controlstate: relay transport certificate is not available")
	ErrRelayTransportCertificateLeaseStale = errors.New("controlstate: relay transport certificate lease is stale")
)
View Source 
var (
	ErrRelayRegistrationConflict         = errors.New("controlstate: relay identity or service configuration conflicts with live state")
	ErrRelayLeaseStale                   = errors.New("controlstate: relay lease identity or revision is stale")
	ErrRelayDraining                     = errors.New("controlstate: relay is draining")
	ErrRelayConnectionCapacity           = errors.New("controlstate: relay connection capacity is exhausted")
	ErrPublisherConnectionUnavailable    = errors.New("controlstate: publisher connection is unavailable")
	ErrPublisherConnectionCredential     = errors.New("controlstate: publisher connection credential is invalid")
	ErrConnectionAssignmentStale         = errors.New("controlstate: connection assignment identity or revision is stale")
	ErrPublisherConnectionAlreadyClaimed = errors.New("controlstate: publisher connection is already claimed")
	ErrPublisherConnectionRelayService   = errors.New("controlstate: publisher connection is assigned to another relay service")
)
View Source 
var (
	ErrRouteSessionCredential = errors.New("controlstate: route-session credential is invalid")
	ErrRouteSessionStale      = errors.New("controlstate: route session identity or version is stale")
	ErrRouteSessionNotReady   = errors.New("controlstate: route session is not ready")
	ErrRouteCertificate       = errors.New("controlstate: route certificate acknowledgement is invalid")
)
View Source 
var (
	ErrRouteNotFound             = errors.New("controlstate: route not found")
	ErrRouteNotEnabled           = errors.New("controlstate: route is not enabled")
	ErrRouteCredential           = errors.New("controlstate: route credential is invalid")
	ErrRouteAuthority            = errors.New("controlstate: route authority is stale")
	ErrRouteSessionConflict      = errors.New("controlstate: route already has a live session")
	ErrRouteSessionIdempotency   = errors.New("controlstate: route-session idempotency conflict")
	ErrRouteSessionCreationGated = errors.New("controlstate: route-session creation is disabled")
	ErrInsufficientRelayServices = errors.New("controlstate: insufficient relay-service placement capacity")
)
View Source 
var (
	ErrRouteAccess        = errors.New("controlstate: route access denied")
	ErrRouteConflict      = errors.New("controlstate: route hostname is already in use")
	ErrRouteCreationGated = errors.New("controlstate: route creation is disabled")
	ErrRouteIdempotency   = errors.New("controlstate: route idempotency conflict")
	ErrRouteInvalid       = errors.New("controlstate: route request is invalid")
	ErrRouteSessionOpen   = errors.New("controlstate: route has an open route session")
	ErrRouteMutationStale = errors.New("controlstate: authorized route state changed")
)
View Source 
var (
	ErrAuthorityAccess      = errors.New("controlstate: authority access denied")
	ErrAuthorityConflict    = errors.New("controlstate: authority state conflict")
	ErrAuthorityIdempotency = errors.New("controlstate: authority idempotency conflict")
	ErrAuthorityInvalid     = errors.New("controlstate: authority request is invalid")
	ErrMembershipNotFound   = errors.New("controlstate: membership not found")
	ErrTeamNotFound         = errors.New("controlstate: team not found")
)
View Source 
var (
	ErrIngressUsageReportInvalid   = errors.New("controlstate: ingress usage report is invalid")
	ErrIngressUsageReportStale     = errors.New("controlstate: ingress usage report revision is stale")
	ErrIngressUsageReportConflict  = errors.New("controlstate: ingress usage report conflicts with stored state")
	ErrIngressUsageRouteNotFound   = errors.New("controlstate: ingress usage route version was not found")
	ErrRouteUsageBucketFinalized   = errors.New("controlstate: route usage bucket is finalized")
	ErrRouteUsageDeliveryWorkStale = errors.New("controlstate: route usage delivery work is stale")
	ErrRouteUsageDeliveryInvalid   = errors.New("controlstate: route usage delivery work is invalid")
)
View Source 
var ErrACMEWorkStale = errors.New("controlstate: ACME work lease is stale")
View Source 
var ErrDNSChallengeNotFound = errors.New("controlstate: DNS challenge not found")
View Source 
var ErrDomainNotFound = errors.New("controlstate: domain not found")
View Source 
var ErrExternalAuthorityPrincipal = errors.New("controlstate: external authority principal is invalid")
View Source 
var ErrHostedPolicyRevocationInvalid = errors.New("controlstate: hosted policy revocation is invalid")
View Source 
var ErrInvitationNotFound = errors.New("controlstate: invitation not found")
View Source 
var ErrRouteRecoveryEpisodeStale = errors.New("controlstate: route recovery episode is stale")

Functions

func Migrate 

func Migrate(ctx context.Context, directURL string) (retErr error)

Migrate applies every embedded control-state migration through a direct PostgreSQL URL. A persistent table lock allows only one migration at a time.

Types

type ACMEAccount 

type ACMEAccount struct {
	ID            string
	DirectoryURL  string
	ContactEmail  string
	AccountKeyDER []byte
	AccountURL    string
	AcceptedTerms string
}

type ACMEAuthorizationWork 

type ACMEAuthorizationWork struct {
	ID                    string
	Identifier            string
	AuthorizationURL      string
	ChallengeType         string
	ChallengeURL          string
	ChallengeToken        string
	ChallengeDigest       [32]byte
	PresentationReference string
	State                 string
	Revision              uint64
	Attempts              uint64
	AvailableAt           time.Time
	PresentedAt           *time.Time
	ValidatedAt           *time.Time
	CleanupCompletedAt    *time.Time
	ExpiresAt             *time.Time
	LastError             string
	CreatedAt             time.Time
	UpdatedAt             time.Time
}

type ACMEOrderWork 

type ACMEOrderWork struct {
	ID                     string
	Account                ACMEAccount
	RouteSessionID         string
	RouteID                string
	RouteVersion           uint64
	CertificateCacheKey    string
	CertificateScope       string
	CertificateIdentifiers []string
	ChallengeMethod        string
	CSRDER                 []byte
	CSRDigest              [32]byte
	State                  string
	OrderRevision          uint64
	OrderURL               string
	FinalizeURL            string
	CertificateURL         string
	CertificatePEM         []byte
	NotBefore              *time.Time
	NotAfter               *time.Time
	RenewAt                *time.Time
	Attempts               uint64
	AvailableAt            time.Time
	LastError              string
	CreatedAt              time.Time
	UpdatedAt              time.Time
	WorkerID               string
	WorkEpoch              uint64
	WorkExpiresAt          time.Time
	Authorizations         []ACMEAuthorizationWork
}

type AdminRelayPage 

type AdminRelayPage struct {
	Relays     []RelayLease
	NextCursor string
}

AdminRelayPage is one stable relay-ID-ordered page of unexpired leases.

type AdminRuntimeCounts 

type AdminRuntimeCounts struct {
	EnabledRoutes         int64
	SuspendedRoutes       int64
	StartingRouteSessions int64
	ReadyRouteSessions    int64
	IngressLeases         int64
	RelayLeases           int64
}

AdminRuntimeCounts contains current stored state counts for server status.

type AuthorizedRouteDeleteRequest 

type AuthorizedRouteDeleteRequest struct {
	RouteID                  string
	TeamID                   string
	ActingIdentityID         string
	AuthorityIssuer          string
	PolicyRevision           uint64
	ExpectedMutationRevision uint64
}

type AuthorizedRouteUpdateRequest 

type AuthorizedRouteUpdateRequest struct {
	RouteID                  string
	TeamID                   string
	ActingIdentityID         string
	Target                   string
	AllowedIPPrefixes        []string
	AuthorityIssuer          string
	PolicyRevision           uint64
	ExpectedMutationRevision uint64
}

type CertificateChallenge 

type CertificateChallenge struct {
	Identifier string
	Method     string
	Token      string
	Digest     [32]byte
	ExpiresAt  time.Time
}

type CertificateIssuance 

type CertificateIssuance struct {
	ID              string
	RouteSessionID  string
	RouteID         string
	RouteVersion    uint64
	CertificatePlan CertificatePlan
	State           string
	Challenges      []CertificateChallenge
	CertificatePEM  string
	RetryAt         *time.Time
	NotBefore       *time.Time
	NotAfter        *time.Time
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type CertificatePlan 

type CertificatePlan struct {
	CacheKey        string
	Scope           string
	Identifiers     []string
	ChallengeMethod string
}

type ClaimDomainRequest 

type ClaimDomainRequest struct {
	IdentityID     string
	TeamID         string
	IdempotencyKey string
	RequestDigest  [32]byte
	Domain         string
	MakeDefault    bool
}

type ClaimedPublisherConnection 

type ClaimedPublisherConnection struct {
	ConnectionAssignmentIdentity
	RelayLeaseIdentity
	ClaimID                                string
	RelayAddress                           string
	TLSServerName                          string
	State                                  PublisherConnectionState
	PublisherConnectionCredentialExpiresAt time.Time
	ConnectedAt                            time.Time
	ReadyAt                                *time.Time
}

ClaimedPublisherConnection is the stored state of one claimed assignment.

type ConnectionAssignment 

type ConnectionAssignment struct {
	ConnectionAssignmentIdentity
	RelayAddress                           string
	TLSServerName                          string
	PublisherConnectionCredential          credentials.PublisherConnectionCredential
	PublisherConnectionCredentialExpiresAt time.Time
	State                                  PublisherConnectionState
}

ConnectionAssignment is one of the two independently assigned publisher connections returned by route-session setup and heartbeat replenishment.

type ConnectionAssignmentIdentity 

type ConnectionAssignmentIdentity struct {
	RouteSessionID               string
	RouteID                      string
	RouteVersion                 uint64
	ConnectionSlot               int
	PublisherConnectionID        string
	ConnectionAssignmentRevision uint64
	RelayServiceID               string
}

ConnectionAssignmentIdentity identifies one exact publisher connection assignment.

type ControlPrincipal 

type ControlPrincipal struct {
	SessionID        string
	IdentityID       string
	Administrator    bool
	RetrySecret      [32]byte
	RefreshExpiresAt time.Time
}

type ControlSession 

type ControlSession struct {
	SessionID        string
	AccessToken      credentials.AccessToken
	AccessExpiresAt  time.Time
	RefreshToken     credentials.RefreshToken
	RefreshExpiresAt time.Time
	Identity         IdentityContext
}

type ControlTLSCache 

type ControlTLSCache struct {
	// contains filtered or unexported fields
}

func (*ControlTLSCache) Delete 

func (c *ControlTLSCache) Delete(ctx context.Context, key string) error

func (*ControlTLSCache) Get 

func (c *ControlTLSCache) Get(ctx context.Context, key string) ([]byte, error)

func (*ControlTLSCache) Put 

func (c *ControlTLSCache) Put(ctx context.Context, key string, data []byte) error

type CreateCertificateIssuanceRequest 

type CreateCertificateIssuanceRequest struct {
	Authentication RouteSessionAuthentication
	DirectoryURL   string
	IdempotencyKey string
	RequestDigest  [32]byte
	CSRDER         []byte
}

type CreateDNSAuthorityRequest 

type CreateDNSAuthorityRequest struct {
	TeamID          string
	DomainID        string
	CanonicalDomain string
	IdempotencyKey  string
	RequestDigest   [32]byte
}

type CreateInvitationRequest 

type CreateInvitationRequest struct {
	IdentityID       string
	TeamID           string
	IdempotencyKey   string
	RequestDigest    [32]byte
	MemberSlug       string
	InitialRole      string
	ExpiresAt        time.Time
	EmailRestriction string
	RetrySecret      []byte
}

type CreateRouteRequest 

type CreateRouteRequest struct {
	TeamID                string
	DomainID              string
	MembershipID          string
	ActingIdentityID      string
	IdempotencyKey        string
	RequestDigest         [32]byte
	CanonicalHostname     string
	Target                string
	RouteScope            RouteScope
	AllowedIPPrefixes     []string
	DNSState              RouteDNSState
	DNSAuthorityReference string
	AuthorityIssuer       string
	PolicyRevision        uint64
	Ephemeral             bool
}

type CreateTeamRequest 

type CreateTeamRequest struct {
	IdentityID     string
	IdempotencyKey string
	RequestDigest  [32]byte
	DisplayName    string
	MemberSlug     string
}

type DNSAuthority 

type DNSAuthority struct {
	Reference       string
	TeamID          string
	DomainID        string
	CanonicalDomain string
	State           string
	RequiredRecords []DNSRecord
	LastError       string
	ProviderZoneID  string
	Nameservers     []string
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type DNSAuthorityWork 

type DNSAuthorityWork struct {
	DNSAuthority
	Provider       string
	ProviderZoneID string
	Nameservers    []string
	WorkRevision   uint64
	Attempts       uint64
	AvailableAt    time.Time
	WorkerID       string
	WorkEpoch      uint64
	WorkExpiresAt  time.Time
}

type DNSChallengeContext 

type DNSChallengeContext struct {
	RouteID               string
	TeamID                string
	DomainID              string
	DNSAuthorityReference string
	CanonicalDomain       string
	AuthorizationID       string
	Identifier            string
	PresentationReference string
	State                 string
	ChallengeDigest       [32]byte
	Presentations         []DNSChallengePresentation
}

type DNSChallengePresentation 

type DNSChallengePresentation struct {
	ChallengeDigest [32]byte
	Active          bool
}

type DNSRecord 

type DNSRecord struct {
	Name  string
	Type  string
	Value string
}

type DNSRouteWork 

type DNSRouteWork struct {
	RouteID               string
	DomainID              string
	DNSAuthorityReference string
	CanonicalHostname     string
	State                 RouteDNSState
	DNSRevision           uint64
	Attempts              uint64
	AvailableAt           time.Time
	LastError             string
	WorkerID              string
	WorkEpoch             uint64
	WorkExpiresAt         time.Time
}

type Database 

type Database struct {
	// contains filtered or unexported fields
}

Database is the PostgreSQL connection pool for control state. Its database details remain private to this package.

func Open 

func Open(ctx context.Context, pooledURL, currentStorageKey, previousStorageKey string) (*Database, error)

Open connects to already-migrated control state using a pooled PostgreSQL URL. Open never creates or migrates schema objects.

func (*Database) AcceptInvitation 

func (d *Database) AcceptInvitation(
	ctx context.Context,
	identityID string,
	token credentials.InvitationToken,
	now time.Time,
) (result Membership, retErr error)

func (*Database) AdminRuntimeCounts 

func (d *Database) AdminRuntimeCounts(ctx context.Context, now time.Time) (AdminRuntimeCounts, error)

AdminRuntimeCounts returns counts evaluated against one captured timestamp.

func (*Database) AdvanceIngressRoutingRetention 

func (d *Database) AdvanceIngressRoutingRetention(ctx context.Context, cutoff time.Time) (revision uint64, retErr error)

AdvanceIngressRoutingRetention advertises the oldest supported incremental cursor. Snapshot and entry-revision anchors survive subsequent pruning. Cutoff is chosen by control, never supplied by an ingress request.

func (*Database) ApplyHostedPolicyRevocation 

func (d *Database) ApplyHostedPolicyRevocation(
	ctx context.Context,
	issuer, teamID string,
	policyRevision uint64,
	allSessions bool,
	membershipIDs []string,
	domainIDs []string,
	now time.Time,
) (applied bool, closed int, retErr error)

ApplyHostedPolicyRevocation advances one hosted team revision and closes older route sessions affected by that revision. Equal and older deliveries are successful no-ops.

func (*Database) AuthenticateAccessToken 

func (d *Database) AuthenticateAccessToken(
	ctx context.Context,
	token credentials.AccessToken,
	loginSourceRevision int64,
	now time.Time,
) (ControlPrincipal, error)

func (*Database) BeginAdminRelayDrain 

func (d *Database) BeginAdminRelayDrain(
	ctx context.Context,
	identity RelayLeaseIdentity,
	actorIdentityID, requestID string,
	now, deadline time.Time,
) (result RelayLease, retErr error)

BeginAdminRelayDrain drains one matching lease and records the administrator action in the same transaction.

func (*Database) BeginIngressDrain 

func (d *Database) BeginIngressDrain(
	ctx context.Context,
	identity IngressLeaseIdentity,
	now time.Time,
	deadline time.Time,
) (result IngressLease, retErr error)

BeginIngressDrain removes one exact ingress process from readiness and keeps its lease current through the drain deadline.

func (*Database) BeginRelayDrain 

func (d *Database) BeginRelayDrain(
	ctx context.Context,
	identity RelayLeaseIdentity,
	now time.Time,
	deadline time.Time,
) (RelayLease, error)

BeginRelayDrain removes one exact relay process from placement and keeps its lease current through the deadline while established streams drain.

func (*Database) ClaimACMEOrderWork 

func (d *Database) ClaimACMEOrderWork(
	ctx context.Context,
	workerID string,
	now time.Time,
	leaseDuration time.Duration,
) (work ACMEOrderWork, found bool, retErr error)

func (*Database) ClaimDNSAuthorityWork 

func (d *Database) ClaimDNSAuthorityWork(
	ctx context.Context,
	workerID string,
	now time.Time,
	leaseDuration time.Duration,
) (DNSAuthorityWork, bool, error)

func (*Database) ClaimDNSRouteWork 

func (d *Database) ClaimDNSRouteWork(
	ctx context.Context,
	workerID string,
	now time.Time,
	leaseDuration time.Duration,
) (DNSRouteWork, bool, error)

func (*Database) ClaimPublisherConnection 

func (d *Database) ClaimPublisherConnection(
	ctx context.Context,
	request PublisherConnectionClaimRequest,
	now time.Time,
) (result ClaimedPublisherConnection, retErr error)

ClaimPublisherConnection authenticates and claims one assignment in a transaction. The winning relay can repeat its claim; all other relays are rejected.

func (*Database) ClaimRelayCertificateOrderWork 

func (d *Database) ClaimRelayCertificateOrderWork(
	ctx context.Context,
	workerID string,
	now time.Time,
	leaseDuration time.Duration,
) (work RelayCertificateOrderWork, found bool, retErr error)

func (*Database) ClaimRouteUsageDeliveries 

func (d *Database) ClaimRouteUsageDeliveries(
	ctx context.Context,
	workerID string,
	batchSize int,
	now time.Time,
	leaseDuration time.Duration,
) (result []RouteUsageDeliveryWork, retErr error)

ClaimRouteUsageDeliveries claims up to batchSize finalized buckets.

func (*Database) ClaimTeamDomain 

func (d *Database) ClaimTeamDomain(
	ctx context.Context,
	request ClaimDomainRequest,
	now time.Time,
) (result Domain, retErr error)

func (*Database) Close 

func (d *Database) Close()

Close closes all runtime database connections. It is safe to call more than once.

func (*Database) CloseRouteSession 

func (d *Database) CloseRouteSession(ctx context.Context, routeSessionID string, token credentials.RouteSessionToken, now time.Time) (retErr error)

func (*Database) CompleteRouteUsageDelivery 

func (d *Database) CompleteRouteUsageDelivery(
	ctx context.Context,
	work RouteUsageDeliveryWork,
	now time.Time,
) error

func (*Database) CompleteStorageKeyRotation 

func (d *Database) CompleteStorageKeyRotation(ctx context.Context) error

CompleteStorageKeyRotation re-encrypts all currently claimable secrets. New writes always use the current key, so a successful pass cannot create more work for the configured previous key.

func (*Database) ControlTLSCache 

func (d *Database) ControlTLSCache(directoryURL string) (*ControlTLSCache, error)

func (*Database) CreateBuiltinControlSession 

func (d *Database) CreateBuiltinControlSession(
	ctx context.Context,
	managedDomain string,
	authenticationSourceRevision int64,
	accessLifetime time.Duration,
	refreshLifetime time.Duration,
	now time.Time,
) (result ControlSession, retErr error)

func (*Database) CreateCertificateIssuance 

func (d *Database) CreateCertificateIssuance(
	ctx context.Context,
	request CreateCertificateIssuanceRequest,
	now time.Time,
) (result CertificateIssuance, retErr error)

func (*Database) CreateDNSAuthority 

func (d *Database) CreateDNSAuthority(
	ctx context.Context,
	request CreateDNSAuthorityRequest,
	now time.Time,
) (DNSAuthority, error)

func (*Database) CreateOIDCControlSession 

func (d *Database) CreateOIDCControlSession(
	ctx context.Context,
	managedDomain string,
	identity OIDCIdentity,
	accessLifetime time.Duration,
	refreshLifetime time.Duration,
	now time.Time,
) (result ControlSession, retErr error)

CreateOIDCControlSession consumes one verified assertion and creates or updates its non-administrator local identity before issuing a local control session.

func (*Database) CreateRoute 

func (d *Database) CreateRoute(ctx context.Context, request CreateRouteRequest, now time.Time) (result Route, retErr error)

func (*Database) CreateRouteSession 

func (d *Database) CreateRouteSession(
	ctx context.Context,
	request RouteSessionRequest,
	now time.Time,
	publisherLeaseDuration time.Duration,
	connectionCredentialDuration time.Duration,
) (result RouteSessionSetup, retErr error)

CreateRouteSession creates one route version and exactly two connection assignments on distinct relay services. An authenticated retry returns the same session and assignment credentials.

func (*Database) CreateTeam 

func (d *Database) CreateTeam(ctx context.Context, request CreateTeamRequest, now time.Time) (result Team, retErr error)

func (*Database) CreateTeamInvitation 

func (d *Database) CreateTeamInvitation(
	ctx context.Context,
	request CreateInvitationRequest,
	now time.Time,
) (result InvitationSecret, retErr error)

func (*Database) DNSAuthorityReleaseReady 

func (d *Database) DNSAuthorityReleaseReady(ctx context.Context, domainID string, now time.Time) (bool, error)

func (*Database) DeleteAuthorizedRoute 

func (d *Database) DeleteAuthorizedRoute(
	ctx context.Context,
	request AuthorizedRouteDeleteRequest,
	now time.Time,
) error

func (*Database) DeleteExpiredEphemeralRoutes 

func (d *Database) DeleteExpiredEphemeralRoutes(ctx context.Context, now time.Time) (count int, retErr error)

DeleteExpiredEphemeralRoutes removes a limited batch of expired routes. It uses the same route-session, routing-table, and DNS cleanup as explicit deletion.

func (*Database) DeleteRoute 

func (d *Database) DeleteRoute(ctx context.Context, identityID, routeID string, now time.Time) (retErr error)

func (*Database) Diagnostics 

func (d *Database) Diagnostics(parent context.Context) (result DatabaseDiagnostics, retErr error)

Diagnostics uses a separate connection through the configured pooled URL. It cannot be starved by the local pgx pool; pooler/database unavailability is still bounded by the timeout. It never returns query text or connection data.

func (*Database) DisconnectPublisherConnection 

func (d *Database) DisconnectPublisherConnection(
	ctx context.Context,
	request PublisherConnectionClaimRequest,
	now time.Time,
	unexpected bool,
) (ClaimedPublisherConnection, error)

DisconnectPublisherConnection closes only the exact claimed connection.

func (*Database) EnsureACMEAccount 

func (d *Database) EnsureACMEAccount(
	ctx context.Context,
	directoryURL string,
	contactEmail string,
	now time.Time,
) (ACMEAccount, error)

func (*Database) EnsureExternalAuthorityPrincipal 

func (d *Database) EnsureExternalAuthorityPrincipal(
	ctx context.Context,
	identityID string,
	now time.Time,
) (result [32]byte, retErr error)

EnsureExternalAuthorityPrincipal records only the server-local principal ID needed by stored route and audit state and returns the shared retry secret.

func (*Database) FinalizeRouteUsageBuckets 

func (d *Database) FinalizeRouteUsageBuckets(
	ctx context.Context,
	through time.Time,
	now time.Time,
) (result int, retErr error)

FinalizeRouteUsageBuckets closes aggregate buckets through a cutoff and creates one stored delivery record for each finalized revision.

func (*Database) GetAuthorizedRouteByHostname 

func (d *Database) GetAuthorizedRouteByHostname(ctx context.Context, teamID, hostname string) (Route, error)

GetAuthorizedRouteByHostname reads one non-deleted route after a current team-read authorization decision, using the existing hostname index.

func (*Database) GetCertificateIssuance 

func (d *Database) GetCertificateIssuance(
	ctx context.Context,
	issuanceID string,
	token credentials.RouteSessionToken,
	now time.Time,
) (result CertificateIssuance, retErr error)

func (*Database) GetDNSAuthority 

func (d *Database) GetDNSAuthority(ctx context.Context, reference string) (DNSAuthority, error)

func (*Database) GetDNSChallengeContext 

func (d *Database) GetDNSChallengeContext(
	ctx context.Context,
	routeID, authorizationID string,
) (DNSChallengeContext, error)

func (*Database) GetRelayDNSChallengeContext 

func (d *Database) GetRelayDNSChallengeContext(ctx context.Context, orderID string) (RelayDNSChallengeContext, error)

func (*Database) GetRelayTransportCertificate 

func (d *Database) GetRelayTransportCertificate(
	ctx context.Context,
	identity RelayLeaseIdentity,
	now time.Time,
) (RelayTransportCertificate, error)

GetRelayTransportCertificate returns decrypted material only while the exact requesting relay process lease is current.

func (*Database) GetRoute 

func (d *Database) GetRoute(ctx context.Context, identityID, routeID string) (Route, error)

func (*Database) GetRouteForAuthorization 

func (d *Database) GetRouteForAuthorization(ctx context.Context, routeID string) (Route, error)

GetRouteForAuthorization returns stored route data for an authority request. Callers must not expose the result before the authority approves it.

func (*Database) GetRouteForSessionAuthorization 

func (d *Database) GetRouteForSessionAuthorization(
	ctx context.Context,
	routeID, idempotencyKey string,
) (Route, error)

GetRouteForSessionAuthorization returns the route version from an earlier matching route-session request, or the next version for a new request.

func (*Database) GetTeam 

func (d *Database) GetTeam(ctx context.Context, identityID, teamID string) (Team, error)

func (*Database) Health 

func (d *Database) Health(ctx context.Context) error

Health verifies that the database can serve a query through the runtime pool.

func (*Database) HeartbeatRouteSession 

func (d *Database) HeartbeatRouteSession(
	ctx context.Context,
	authentication RouteSessionAuthentication,
	now time.Time,
	leaseDuration time.Duration,
	connectionCredentialDuration time.Duration,
) (result RouteSessionSetup, retErr error)

HeartbeatRouteSession extends one route session and returns current or replacement publisher connection assignments.

func (*Database) IdentityContext 

func (d *Database) IdentityContext(ctx context.Context, identityID string) (IdentityContext, error)

func (*Database) Instrument 

func (d *Database) Instrument(metrics *observability.Metrics)

Instrument sends completed state operations and request-pool queries to one process registry. Configure it after Open and before serving requests.

func (*Database) ListAdminRelayLeases 

func (d *Database) ListAdminRelayLeases(ctx context.Context, cursor string, now time.Time) (AdminRelayPage, error)

ListAdminRelayLeases returns one page of current relay process leases.

func (*Database) ListAuthorizedRoutes 

func (d *Database) ListAuthorizedRoutes(ctx context.Context, teamID, cursor string) (RoutePage, error)

ListAuthorizedRoutes returns one team page after the caller has obtained a current authorization decision. It deliberately does not consult local memberships.

func (*Database) ListMaintenanceControls 

func (d *Database) ListMaintenanceControls(ctx context.Context) ([]MaintenanceControl, error)

ListMaintenanceControls returns all maintenance controls in name order.

func (*Database) ListRoutes 

func (d *Database) ListRoutes(ctx context.Context, identityID, teamID, cursor string) (RoutePage, error)

func (*Database) ListTeamDomains 

func (d *Database) ListTeamDomains(ctx context.Context, identityID, teamID string) ([]Domain, error)

func (*Database) ListTeamInvitations 

func (d *Database) ListTeamInvitations(
	ctx context.Context,
	identityID, teamID string,
	now time.Time,
) (result []Invitation, retErr error)

func (*Database) ListTeamMemberships 

func (d *Database) ListTeamMemberships(ctx context.Context, identityID, teamID string) ([]Membership, error)

func (*Database) ListTeams 

func (d *Database) ListTeams(ctx context.Context, identityID string) ([]Team, error)

func (*Database) MarkCertificateChallengeReady 

func (d *Database) MarkCertificateChallengeReady(
	ctx context.Context,
	issuanceID string,
	token credentials.RouteSessionToken,
	now time.Time,
) (CertificateIssuance, error)

func (*Database) MarkCertificateChallengeRemoved 

func (d *Database) MarkCertificateChallengeRemoved(
	ctx context.Context,
	issuanceID string,
	token credentials.RouteSessionToken,
	now time.Time,
) (CertificateIssuance, error)

func (*Database) MarkExpiredIngressUsageRunsIncomplete 

func (d *Database) MarkExpiredIngressUsageRunsIncomplete(ctx context.Context, now time.Time) (int, error)

MarkExpiredIngressUsageRunsIncomplete records only the uncovered tail of process runs that ended without a final report.

func (*Database) MarkPublisherConnectionReady 

func (d *Database) MarkPublisherConnectionReady(
	ctx context.Context,
	request PublisherConnectionClaimRequest,
	now time.Time,
) (result ClaimedPublisherConnection, retErr error)

MarkPublisherConnectionReady records that a claimed publisher connection can carry visitor streams.

func (*Database) MarkRouteCertificateInstalled 

func (d *Database) MarkRouteCertificateInstalled(
	ctx context.Context,
	authentication RouteSessionAuthentication,
	issuanceID string,
	notAfter time.Time,
	now time.Time,
) (result RouteSessionLifecycle, retErr error)

MarkRouteCertificateInstalled records publisher acknowledgement of the installed route certificate. First routability still requires both connections.

func (*Database) MarkRouteSessionReady 

func (d *Database) MarkRouteSessionReady(
	ctx context.Context,
	authentication RouteSessionAuthentication,
	now time.Time,
) (result RouteSessionLifecycle, retErr error)

func (*Database) Metrics 

func (d *Database) Metrics(now time.Time) DatabaseMetrics

Metrics returns one process-local database metrics snapshot.

func (*Database) ObserveRouteRecovery 

func (d *Database) ObserveRouteRecovery(
	ctx context.Context,
	ingressIdentity IngressLeaseIdentity,
	routeID string,
	routeVersion uint64,
	recoveryEpisodeID uint64,
	observedAt time.Time,
) (result RouteRecoveryObservation, retErr error)

ObserveRouteRecovery closes one open episode and updates its cumulative histogram in a transaction. Repeating an observed episode is safe.

func (*Database) PoolStats 

func (d *Database) PoolStats() *pgxpool.Stat

PoolStats returns an in-memory snapshot without acquiring a connection.

func (*Database) PrepareRelayCertificateOrder 

func (d *Database) PrepareRelayCertificateOrder(
	ctx context.Context,
	accountID string,
	now time.Time,
	failedRetryInterval time.Duration,
) (created bool, retErr error)

PrepareRelayCertificateOrder schedules managed material at its persisted RenewAt.

func (*Database) PrometheusMetrics 

func (d *Database) PrometheusMetrics(now time.Time) observability.DatabaseSnapshot

PrometheusMetrics supplies the same passive database snapshot to runtime scrapes and local load tests. It never acquires a database connection.

func (*Database) PruneIngressRoutingHistory 

func (d *Database) PruneIngressRoutingHistory(ctx context.Context, afterRevision uint64) (result RoutingHistoryPruneResult, retErr error)

PruneIngressRoutingHistory scans at most 1,000 committed events below the published floor. Callers yield between batches, retain NextRevision within a sweep, and restart at zero after More is false. A canceled/failed batch must retry its previous cursor. Busy means another control owns the current batch.

func (*Database) ReadIngressRoutingTableEvents 

func (d *Database) ReadIngressRoutingTableEvents(
	ctx context.Context,
	identity IngressLeaseIdentity,
	afterRevision uint64,
	pageSize int,
	now time.Time,
) (result IngressRoutingTablePage, retErr error)

ReadIngressRoutingTableEvents returns a size-limited page after one revision.

func (*Database) ReadIngressRoutingTableSnapshot 

func (d *Database) ReadIngressRoutingTableSnapshot(
	ctx context.Context,
	identity IngressLeaseIdentity,
	now time.Time,
) (result IngressRoutingTableSnapshot, retErr error)

ReadIngressRoutingTableSnapshot returns the latest unexpired projection for each route or challenge as of one repeatable-read high-water revision.

func (*Database) Readiness 

func (d *Database) Readiness(ctx context.Context) error

Readiness verifies runtime connectivity and the exact supported schema version. Unlike Open, it is safe to call repeatedly from a readiness probe.

func (*Database) ReencryptStorageSecrets 

func (d *Database) ReencryptStorageSecrets(ctx context.Context, limit int) (rotated int, retErr error)

ReencryptStorageSecrets claims and re-encrypts up to limit rows written with the configured previous storage key. Row locks are held through commit, so concurrent control processes skip work already claimed by another process.

func (*Database) RefreshControlSession 

func (d *Database) RefreshControlSession(
	ctx context.Context,
	token credentials.RefreshToken,
	loginSourceRevision int64,
	accessLifetime time.Duration,
	now time.Time,
) (result ControlSession, retErr error)

func (*Database) RegisterIngress 

func (d *Database) RegisterIngress(
	ctx context.Context,
	registration IngressRegistration,
	now time.Time,
	leaseDuration time.Duration,
) (result IngressLease, retErr error)

RegisterIngress creates or renews one ingress process lease.

func (*Database) RegisterRelay 

func (d *Database) RegisterRelay(
	ctx context.Context,
	registration RelayRegistration,
	now time.Time,
	leaseDuration time.Duration,
) (RelayLease, error)

RegisterRelay creates or renews one relay process lease. A different process run cannot replace an unexpired lease for the same relay identity.

func (*Database) ReleaseDNSAuthority 

func (d *Database) ReleaseDNSAuthority(
	ctx context.Context,
	reference, idempotencyKey string,
	now time.Time,
) (result DNSAuthority, retErr error)

func (*Database) ReleaseTeamDomain 

func (d *Database) ReleaseTeamDomain(
	ctx context.Context,
	identityID, teamID, domainID string,
	now time.Time,
) (retErr error)

func (*Database) RemoveMembership 

func (d *Database) RemoveMembership(
	ctx context.Context,
	identityID, teamID, membershipID string,
	now time.Time,
) (retErr error)

func (*Database) RenewIngress 

func (d *Database) RenewIngress(
	ctx context.Context,
	renewal IngressRenewal,
	now time.Time,
	leaseDuration time.Duration,
) (result IngressLease, retErr error)

RenewIngress extends one exact, unexpired ingress lease.

func (*Database) RenewRelay 

func (d *Database) RenewRelay(
	ctx context.Context,
	renewal RelayRenewal,
	now time.Time,
	leaseDuration time.Duration,
) (RelayLease, error)

RenewRelay extends one exact, unexpired relay lease.

func (*Database) ReportIngressUsage 

func (d *Database) ReportIngressUsage(
	ctx context.Context,
	identity IngressLeaseIdentity,
	batch IngressUsageBatch,
	receivedAt time.Time,
) (retErr error)

ReportIngressUsage deduplicates cumulative reports and applies only numeric deltas to aggregate route usage buckets.

func (*Database) RetryRouteUsageDelivery 

func (d *Database) RetryRouteUsageDelivery(
	ctx context.Context,
	work RouteUsageDeliveryWork,
	availableAt time.Time,
	lastError string,
	now time.Time,
) error

func (*Database) RevokeControlSession 

func (d *Database) RevokeControlSession(ctx context.Context, principal ControlPrincipal, now time.Time) error

func (*Database) RevokeTeamInvitation 

func (d *Database) RevokeTeamInvitation(
	ctx context.Context,
	identityID, teamID, invitationID string,
	now time.Time,
) (retErr error)

func (*Database) RouteSessionAuthentication 

func (d *Database) RouteSessionAuthentication(
	ctx context.Context,
	routeSessionID string,
	routeVersion uint64,
	token credentials.RouteSessionToken,
) (RouteSessionAuthentication, error)

func (*Database) RunControlTLSLeader 

func (d *Database) RunControlTLSLeader(ctx context.Context, run func(context.Context) error) error

func (*Database) SaveACMEOrderWork 

func (d *Database) SaveACMEOrderWork(
	ctx context.Context,
	work ACMEOrderWork,
	now time.Time,
) (result ACMEOrderWork, retErr error)

func (*Database) SaveDNSAuthorityWork 

func (d *Database) SaveDNSAuthorityWork(
	ctx context.Context,
	work DNSAuthorityWork,
	now time.Time,
) (result DNSAuthorityWork, retErr error)

func (*Database) SaveDNSRouteWork 

func (d *Database) SaveDNSRouteWork(ctx context.Context, work DNSRouteWork, now time.Time) (DNSRouteWork, error)

func (*Database) SaveRelayCertificateOrderWork 

func (d *Database) SaveRelayCertificateOrderWork(
	ctx context.Context,
	work RelayCertificateOrderWork,
	now time.Time,
) (result RelayCertificateOrderWork, retErr error)

func (*Database) SetMaintenanceControl 

func (d *Database) SetMaintenanceControl(
	ctx context.Context,
	name MaintenanceControlName,
	allowed bool,
	actorIdentityID, requestID string,
	now time.Time,
) (result MaintenanceControl, retErr error)

SetMaintenanceControl updates one gate and records the administrator action in the same transaction.

func (*Database) SetMembershipRole 

func (d *Database) SetMembershipRole(
	ctx context.Context,
	identityID, teamID, membershipID, role string,
	now time.Time,
) (result Membership, retErr error)

func (*Database) SetTeamDefaultDomain 

func (d *Database) SetTeamDefaultDomain(
	ctx context.Context,
	identityID, teamID, domainID string,
	now time.Time,
) (result Team, retErr error)

func (*Database) StoreRelayTransportCertificate 

func (d *Database) StoreRelayTransportCertificate(
	ctx context.Context,
	relayServiceID, tlsServerName string,
	certificatePEM, privateKeyPEM []byte,
	now time.Time,
) (RelayTransportCertificate, error)

StoreRelayTransportCertificate validates and encrypts a new relay transport certificate and private key before storing them in PostgreSQL.

func (*Database) UpdateACMEAccountRegistration 

func (d *Database) UpdateACMEAccountRegistration(
	ctx context.Context,
	accountID string,
	contactEmail string,
	accountURL string,
	acceptedTermsURL string,
	now time.Time,
) (ACMEAccount, error)

func (*Database) UpdateAuthorizedRoute 

func (d *Database) UpdateAuthorizedRoute(
	ctx context.Context,
	request AuthorizedRouteUpdateRequest,
	now time.Time,
) (result Route, retErr error)

func (*Database) WithDNSChallengeLock 

func (d *Database) WithDNSChallengeLock(ctx context.Context, recordName string, run func() error) (retErr error)

WithDNSChallengeLock serializes the stored snapshot and DNS update for one TXT name across control processes. A transaction lock also works with pooled PostgreSQL connections and is released on cancellation or connection loss.

type DatabaseConnectionCounts 

type DatabaseConnectionCounts struct {
	Open       int64 `json:"open"`
	Connecting int64 `json:"connecting"`
	Opened     int64 `json:"opened_total"`
	Closed     int64 `json:"closed_total"`
	Failed     int64 `json:"connect_failures_total"`
}

Counts describe this process's client sockets, not PostgreSQL backend slots. Only fixed purpose labels and counters are retained, never connection details.

type DatabaseDiagnostics 

type DatabaseDiagnostics struct {
	CapturedAt          time.Time                           `json:"captured_at"`
	Sessions            []DatabaseSession                   `json:"sessions"`
	Truncated           bool                                `json:"truncated"`
	ActiveOperations    []DatabaseOperation                 `json:"active_operations"`
	OperationsTruncated bool                                `json:"operations_truncated"`
	Connections         map[string]DatabaseConnectionCounts `json:"connections,omitempty"`
	Pooler              *DatabasePoolerDiagnostics          `json:"pooler,omitempty"`
	Error               string                              `json:"error,omitempty"`
}

DatabaseDiagnostics contains bounded, parameter-free PostgreSQL activity.

type DatabaseMetrics 

type DatabaseMetrics struct {
	Pool              *pgxpool.Stat
	ActiveOperations  []DatabaseOperation
	OperationsOmitted int
	Connections       map[string]DatabaseConnectionCounts
}

DatabaseMetrics contains process-local state that is safe to collect on every metrics scrape. It never acquires a database connection.

type DatabaseOperation 

type DatabaseOperation struct {
	Operation      string  `json:"operation"`
	ElapsedSeconds float64 `json:"elapsed_seconds"`
}

type DatabasePoolerClients 

type DatabasePoolerClients struct {
	Total     int  `json:"total"`
	Active    int  `json:"active"`
	Waiting   int  `json:"waiting"`
	Other     int  `json:"other"`
	Truncated bool `json:"truncated"`
}

type DatabasePoolerDiagnostics 

type DatabasePoolerDiagnostics struct {
	Settings map[string]string      `json:"settings,omitempty"`
	Clients  *DatabasePoolerClients `json:"clients,omitempty"`
	Error    string                 `json:"error,omitempty"`
}

PgBouncer may deny its admin console to the runtime user. Unavailable values remain absent and carry a sanitized error; they are never inferred from SKU.

type DatabaseSession 

type DatabaseSession struct {
	PID                   int32    `json:"pid"`
	Operation             string   `json:"operation,omitempty"`
	State                 string   `json:"state"`
	WaitType              string   `json:"wait_type"`
	WaitEvent             string   `json:"wait_event"`
	TransactionAgeSeconds *float64 `json:"transaction_age_seconds"`
	QueryAgeSeconds       *float64 `json:"query_age_seconds"`
	QueryID               *int64   `json:"query_id,omitempty"`
	BlockingPIDs          []int32  `json:"blocking_pids"`
	BlockingPIDsTruncated bool     `json:"blocking_pids_truncated"`
}

type Domain 

type Domain struct {
	ID                    string
	Kind                  string
	TeamID                string
	CanonicalDomain       string
	DNSAuthorityReference string
	State                 string
	AuthorityRevision     int64
	RequiredRecords       []DNSRecord
	CreatedAt             time.Time
	VerifiedAt            time.Time
	UpdatedAt             time.Time
}

type Identity 

type Identity struct {
	ID              string
	DisplayName     string
	NormalizedEmail string
	EmailVerified   bool
	Administrator   bool
	CreatedAt       time.Time
}

type IdentityContext 

type IdentityContext struct {
	Identity       Identity
	PersonalTeamID string
	Memberships    []Membership
}

type IngressLease 

type IngressLease struct {
	IngressLeaseIdentity
	ProtocolVersion        uint64
	ConnectionCapacity     uint64
	ReportedConnections    uint64
	RoutingTableRevision   uint64
	VisitorNetworkHashKeys [2]VisitorNetworkHashKey
	Draining               bool
	DrainDeadline          *time.Time
	RegisteredAt           time.Time
	RenewedAt              time.Time
	LeaseExpiresAt         time.Time
}

IngressLease is the control-issued lease for one ingress process.

type IngressLeaseIdentity 

type IngressLeaseIdentity struct {
	IngressID            string
	IngressRunID         string
	IngressLeaseRevision uint64
}

IngressLeaseIdentity identifies one exact ingress process lease.

type IngressRegistration 

type IngressRegistration struct {
	IngressID          string
	IngressRunID       string
	ProtocolVersion    uint64
	ConnectionCapacity uint64
}

IngressRegistration describes one ingress process run.

type IngressRenewal 

type IngressRenewal struct {
	IngressLeaseIdentity
	ReportedConnections  uint64
	RoutingTableRevision uint64
}

IngressRenewal reports load and applied routing-table state.

type IngressRoutingTableEvent 

type IngressRoutingTableEvent struct {
	RoutingTableRevision uint64
	Kind                 IngressRoutingTableEventKind
	RouteID              string
	RouteVersion         uint64
	CanonicalHostname    string
	EntryRevision        uint64
	Projection           IngressRoutingTableProjection
	RouteExpiresAt       *time.Time
	CreatedAt            time.Time
}

IngressRoutingTableEvent is one stored, ordered projection update.

type IngressRoutingTableEventKind 

type IngressRoutingTableEventKind string

IngressRoutingTableEventKind identifies one routing-table projection mutation. 

const (
	IngressRouteUpsert        IngressRoutingTableEventKind = "route_upsert"
	IngressRouteTombstone     IngressRoutingTableEventKind = "route_tombstone"
	IngressChallengeUpsert    IngressRoutingTableEventKind = "challenge_upsert"
	IngressChallengeTombstone IngressRoutingTableEventKind = "challenge_tombstone"
)

type IngressRoutingTablePage 

type IngressRoutingTablePage struct {
	ThroughRevision       uint64
	RetainedAfterRevision uint64
	NextRevision          uint64
	More                  bool
	ResnapshotRequired    bool
	Events                []IngressRoutingTableEvent
}

IngressRoutingTablePage is an ordered revision response.

type IngressRoutingTableProjection 

type IngressRoutingTableProjection struct {
	RouteSessionID       string                                   `json:"route_session_id"`
	RouteID              string                                   `json:"route_id"`
	RouteVersion         uint64                                   `json:"route_version"`
	CanonicalHostname    string                                   `json:"canonical_hostname"`
	PolicyRevision       uint64                                   `json:"policy_revision"`
	IPPolicy             string                                   `json:"ip_policy"`
	AllowedIPPrefixes    []netip.Prefix                           `json:"allowed_ip_prefixes"`
	RouteExpiresAt       time.Time                                `json:"route_expires_at"`
	RecoveryEpisodeID    *uint64                                  `json:"recovery_episode_id,omitempty"`
	PublisherConnections []IngressRoutingTablePublisherConnection `json:"publisher_connections"`
}

IngressRoutingTableProjection is the stored route view used by ingress.

type IngressRoutingTablePublisherConnection 

type IngressRoutingTablePublisherConnection struct {
	ConnectionSlot               int       `json:"connection_slot"`
	PublisherConnectionID        string    `json:"publisher_connection_id"`
	ConnectionAssignmentRevision uint64    `json:"connection_assignment_revision"`
	RelayServiceID               string    `json:"relay_service_id"`
	RelayID                      string    `json:"relay_id"`
	RelayRunID                   string    `json:"relay_run_id"`
	RelayLeaseRevision           uint64    `json:"relay_lease_revision"`
	InternalRelayAddress         string    `json:"internal_relay_address"`
	TLSServerName                string    `json:"tls_server_name"`
	LeaseExpiresAt               time.Time `json:"lease_expires_at"`
}

IngressRoutingTablePublisherConnection identifies one connected relay that ingress may use for a visitor connection.

type IngressRoutingTableSnapshot 

type IngressRoutingTableSnapshot struct {
	RoutingTableRevision  uint64
	RetainedAfterRevision uint64
	Routes                []IngressRoutingTableEvent
}

IngressRoutingTableSnapshot is a repeatable-read view through one revision.

type IngressUsageBatch 

type IngressUsageBatch struct {
	Reports         []IngressUsageReport
	ObservedThrough *time.Time
	Complete        bool
}

IngressUsageBatch advances one ingress process run only after every report through the optional watermark has been committed.

type IngressUsageReport 

type IngressUsageReport struct {
	RouteID                   string
	RouteVersion              uint64
	BucketStart               time.Time
	BucketEnd                 time.Time
	ObservedThrough           time.Time
	ReportRevision            uint64
	ConnectionAttempts        uint64
	PolicyDenials             uint64
	CapacityDenials           uint64
	VisitorStreamOpenFailures uint64
	SuccessfulStreams         uint64
	ConnectionNanoseconds     uint64
	IngressBytes              uint64
	EgressBytes               uint64
	HistogramData             []byte
	Final                     bool
}

IngressUsageReport contains cumulative usage for one ingress process, route version, and time bucket.

type Invitation 

type Invitation struct {
	ID                         string
	TeamID                     string
	MemberSlug                 string
	InitialRole                string
	NormalizedEmailRestriction string
	State                      string
	CreatedAt                  time.Time
	ExpiresAt                  time.Time
}

type InvitationSecret 

type InvitationSecret struct {
	Invitation Invitation
	Secret     string
}

type MaintenanceControl 

type MaintenanceControl struct {
	Name      MaintenanceControlName
	Allowed   bool
	Revision  uint64
	UpdatedAt time.Time
	UpdatedBy string
}

MaintenanceControl is one stored gate for starting new work.

type MaintenanceControlName 

type MaintenanceControlName string
const (
	MaintenanceControlRouteCreation        MaintenanceControlName = "route_creation"
	MaintenanceControlRouteSessionCreation MaintenanceControlName = "route_session_creation"
	MaintenanceControlCertificateIssuance  MaintenanceControlName = "certificate_issuance"
)

type Membership 

type Membership struct {
	ID              string
	TeamID          string
	IdentityID      string
	TeamDisplayName string
	TeamKind        string
	Role            string
	MemberSlug      string
	ManagedLabel    string
	PolicyRevision  int64
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type OIDCIdentity 

type OIDCIdentity struct {
	Issuer          string
	Subject         string
	DisplayName     string
	NormalizedEmail string
	EmailVerified   bool
	AssertionDigest [32]byte
	AssertionExpiry time.Time
}

OIDCIdentity contains the limited identity and assertion fields verified from an ID token.

type PublisherConnectionClaimRequest 

type PublisherConnectionClaimRequest struct {
	ConnectionAssignmentIdentity
	RelayLeaseIdentity
	ClaimID          string
	CredentialDigest [32]byte
}

PublisherConnectionClaimRequest contains the assignment, relay lease, and credential hash needed to claim one publisher connection in a transaction.

type PublisherConnectionState 

type PublisherConnectionState string

PublisherConnectionState is the stored state of one connection slot. 

const (
	PublisherConnectionAssigned  PublisherConnectionState = "assigned"
	PublisherConnectionConnected PublisherConnectionState = "connected"
	PublisherConnectionReady     PublisherConnectionState = "ready"
	PublisherConnectionDraining  PublisherConnectionState = "draining"
	PublisherConnectionClosed    PublisherConnectionState = "closed"
	PublisherConnectionExpired   PublisherConnectionState = "expired"
)

type RelayCertificateOrderWork 

type RelayCertificateOrderWork struct {
	ID                    string
	Account               ACMEAccount
	RelayServiceID        string
	TLSServerName         string
	PrivateKeyPEM         []byte
	CSRDER                []byte
	CSRDigest             [32]byte
	State                 string
	OrderRevision         uint64
	OrderURL              string
	FinalizeURL           string
	CertificateURL        string
	AuthorizationURL      string
	ChallengeURL          string
	ChallengeToken        string
	ChallengeDigest       [32]byte
	PresentationReference string
	CertificatePEM        []byte
	NotBefore             *time.Time
	NotAfter              *time.Time
	RenewAt               *time.Time
	Attempts              uint64
	AvailableAt           time.Time
	LastError             string
	CreatedAt             time.Time
	UpdatedAt             time.Time
	WorkerID              string
	WorkEpoch             uint64
	WorkExpiresAt         time.Time
}

type RelayDNSChallengeContext 

type RelayDNSChallengeContext struct {
	OrderID               string
	RelayServiceID        string
	TLSServerName         string
	State                 string
	ChallengeDigest       [32]byte
	PresentationReference string
	Presentations         []DNSChallengePresentation
}

type RelayLease 

type RelayLease struct {
	RelayLeaseIdentity
	ProtocolVersion      uint64
	RelayAddress         string
	TLSServerName        string
	InternalRelayAddress string
	ObservedAddress      *netip.Addr
	InternalNetworks     []netip.Prefix
	ConnectionCapacity   uint64
	StreamCapacity       uint64
	ReportedConnections  uint64
	ReportedStreams      uint64
	Draining             bool
	DrainDeadline        *time.Time
	RegisteredAt         time.Time
	RenewedAt            time.Time
	LeaseExpiresAt       time.Time
}

RelayLease is the control-issued lease for one relay process.

type RelayLeaseIdentity 

type RelayLeaseIdentity struct {
	RelayServiceID     string
	RelayID            string
	RelayRunID         string
	RelayLeaseRevision uint64
}

RelayLeaseIdentity identifies one exact relay process lease.

type RelayRegistration 

type RelayRegistration struct {
	RelayServiceID       string
	RelayID              string
	RelayRunID           string
	ProtocolVersion      uint64
	RelayAddress         string
	TLSServerName        string
	InternalRelayAddress string
	InternalNetworks     []netip.Prefix
	ConnectionCapacity   uint64
	StreamCapacity       uint64
}

RelayRegistration describes one relay process and its relay service.

type RelayRenewal 

type RelayRenewal struct {
	RelayLeaseIdentity
	ReportedConnections uint64
	ReportedStreams     uint64
}

RelayRenewal reports the relay process's current load.

type RelayTransportCertificate 

type RelayTransportCertificate struct {
	RelayServiceID string
	TLSServerName  string
	CertificatePEM string
	PrivateKeyPEM  string
	Serial         string
	NotAfter       time.Time
}

RelayTransportCertificate contains a relay transport certificate and private key. It is returned only to a relay process with a current lease for the matching relay service.

type Route 

type Route struct {
	ID                        string
	TeamID                    string
	DomainID                  string
	MembershipID              string
	CanonicalHostname         string
	Target                    string
	RouteScope                RouteScope
	PolicyRevision            int64
	LifecycleState            RouteLifecycleState
	DNSAuthorityReference     string
	DNSState                  RouteDNSState
	AllowedIPPrefixes         []netip.Prefix
	NextRouteVersion          int64
	MutationRevision          uint64
	AuthorizationRouteVersion uint64
	Ephemeral                 bool
	ExpiresAt                 *time.Time
	OpenRouteSessionID        string
	CreatedAt                 time.Time
	UpdatedAt                 time.Time
}

type RouteDNSState 

type RouteDNSState string

RouteDNSState is the stored state of public route DNS. 

const (
	RouteDNSUnmanaged RouteDNSState = "unmanaged"
	RouteDNSPending   RouteDNSState = "pending"
	RouteDNSPublished RouteDNSState = "published"
	RouteDNSRemoving  RouteDNSState = "removing"
	RouteDNSRemoved   RouteDNSState = "removed"
	RouteDNSFailed    RouteDNSState = "failed"
)

type RouteLifecycleState 

type RouteLifecycleState string

RouteLifecycleState is the stored state of a route. 

const (
	RouteLifecycleEnabled   RouteLifecycleState = "enabled"
	RouteLifecycleSuspended RouteLifecycleState = "suspended"
	RouteLifecycleDeleted   RouteLifecycleState = "deleted"
)

type RoutePage 

type RoutePage struct {
	Routes     []Route
	NextCursor string
}

type RouteRecoveryObservation 

type RouteRecoveryObservation struct {
	RecoveryEpisodeID uint64
	RouteID           string
	RouteVersion      uint64
	OpenedAt          time.Time
	ObservedAt        time.Time
	ObservedSeconds   float64
}

RouteRecoveryObservation is one stored route recovery measurement.

type RouteScope 

type RouteScope string

RouteScope identifies whether a route belongs to one membership or a team. 

const (
	RouteScopeMember RouteScope = "member"
	RouteScopeShared RouteScope = "shared"
)

type RouteSessionAuthentication 

type RouteSessionAuthentication struct {
	RouteSessionID    string
	RouteID           string
	RouteVersion      uint64
	RouteSessionToken credentials.RouteSessionToken
}

RouteSessionAuthentication binds a route session credential to one exact route version.

type RouteSessionLifecycle 

type RouteSessionLifecycle struct {
	RouteSessionID                string
	RouteID                       string
	TeamID                        string
	MembershipID                  string
	RouteVersion                  uint64
	PolicyRevision                uint64
	State                         RouteSessionState
	CreatedAt                     time.Time
	ExpiresAt                     time.Time
	ReadyAt                       *time.Time
	CertificateAt                 *time.Time
	ClosedAt                      *time.Time
	ReadyPublisherConnectionCount int
	Routable                      bool
	RoutingTableRevision          uint64
	RouteEntryRevision            uint64
}

RouteSessionLifecycle reports saved readiness and current publisher connection availability.

type RouteSessionRequest 

type RouteSessionRequest struct {
	RouteID                  string
	TeamID                   string
	MembershipID             string
	ActingIdentityID         string
	RequireLocalAuthority    bool
	RetrySecret              []byte
	IdempotencyKey           string
	RequestDigest            [32]byte
	PolicyRevision           uint64
	CertificateCacheKey      string
	CertificateScope         string
	CertificateIdentifiers   []string
	CertificateChallenge     string
	AuthorityIssuer          string
	ExpectedMutationRevision uint64
}

RouteSessionRequest contains authority already established by the control API plus the authenticated request secret used for retry-stable credentials.

type RouteSessionSetup 

type RouteSessionSetup struct {
	RouteSessionID       string
	RouteID              string
	TeamID               string
	MembershipID         string
	RouteVersion         uint64
	PolicyRevision       uint64
	RouteSessionToken    credentials.RouteSessionToken
	State                RouteSessionState
	CreatedAt            time.Time
	ExpiresAt            time.Time
	ReadyAt              *time.Time
	ClosedAt             *time.Time
	PolicyDenials        uint64
	PublisherConnections [routeSessionConnectionCount]ConnectionAssignment
}

RouteSessionSetup is the retry-stable result of route-session creation.

type RouteSessionState 

type RouteSessionState string

RouteSessionState is the stored state of one route session. 

const (
	RouteSessionStarting RouteSessionState = "starting"
	RouteSessionReady    RouteSessionState = "ready"
	RouteSessionClosed   RouteSessionState = "closed"
	RouteSessionExpired  RouteSessionState = "expired"
	RouteSessionCanceled RouteSessionState = "canceled"
)

type RouteUsageDeliveryWork 

type RouteUsageDeliveryWork struct {
	DeliveryID                uint64
	DeliveryKey               string
	SourceRevision            uint64
	RouteID                   string
	RouteVersion              uint64
	TeamID                    string
	ActingIdentityID          string
	BucketStart               time.Time
	BucketEnd                 time.Time
	ObservedThrough           time.Time
	ConnectionAttempts        uint64
	PolicyDenials             uint64
	CapacityDenials           uint64
	VisitorStreamOpenFailures uint64
	SuccessfulStreams         uint64
	ConnectionNanoseconds     uint64
	IngressBytes              uint64
	EgressBytes               uint64
	Checkpoint                routeusage.Checkpoint
	Complete                  bool
	Attempts                  uint64
	WorkerID                  string
	WorkEpoch                 uint64
	WorkExpiresAt             time.Time
}

RouteUsageDeliveryWork is one immutable finalized bucket held under a PostgreSQL work lease.

type RoutingHistoryPruneResult 

type RoutingHistoryPruneResult struct {
	NextRevision uint64
	Scanned      int64
	Deleted      int64
	More         bool
	Busy         bool
}

type Team 

type Team struct {
	ID              string
	Kind            string
	DisplayName     string
	ManagedLabel    string
	DefaultDomainID string
	PolicyRevision  int64
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type VisitorNetworkHashKey 

type VisitorNetworkHashKey struct {
	UTCDate time.Time
	Key     [32]byte
}

VisitorNetworkHashKey limits visitor-network pseudonyms to one UTC date.

Source Files

View all Source files

Directories

Path Synopsis

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.