controlstate

package
v0.1.0-rc.40 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 47 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 (
	ErrDNSPublicURLWorkStale = errors.New("controlstate: DNS route work lease is stale")
	ErrDNSPublicURLInvalid   = 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 (
	ErrPublishRunCredential = errors.New("controlstate: publish-run credential is invalid")
	ErrPublishRunStale      = errors.New("controlstate: publish run identity or version is stale")
	ErrPublishRunNotReady   = errors.New("controlstate: publish run is not ready")
	ErrPublicURLCertificate = errors.New("controlstate: public URL certificate acknowledgement is invalid")
)
View Source 
var (
	ErrPublicURLAccess        = errors.New("controlstate: public URL access denied")
	ErrPublicURLConflict      = errors.New("controlstate: public URL hostname is already in use")
	ErrPublicURLCreationGated = errors.New("controlstate: public URL creation is disabled")
	ErrPublicURLIdempotency   = errors.New("controlstate: public URL idempotency conflict")
	ErrPublicURLInvalid       = errors.New("controlstate: public URL request is invalid")
	ErrPublishRunOpen         = errors.New("controlstate: public URL has an open publish run")
	ErrPublicURLMutationStale = errors.New("controlstate: authorized public URL state changed")
)
View Source 
var (
	ErrPublicURLNotFound         = errors.New("controlstate: public URL not found")
	ErrPublicURLNotEnabled       = errors.New("controlstate: public URL is not enabled")
	ErrPublicURLCredential       = errors.New("controlstate: public URL credential is invalid")
	ErrPublicURLAuthority        = errors.New("controlstate: route authority is stale")
	ErrPublishRunConflict        = errors.New("controlstate: public URL already has a live session")
	ErrPublishRunIdempotency     = errors.New("controlstate: publish-run idempotency conflict")
	ErrPublishRunCreationGated   = errors.New("controlstate: publish-run creation is disabled")
	ErrInsufficientRelayServices = errors.New("controlstate: insufficient relay-service placement capacity")
)
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 (
	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")
	ErrTeamNameUnavailable  = errors.New("controlstate: team name unavailable")
	ErrMemberSlugRequired   = errors.New("controlstate: member slug required")
)
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")
	ErrIngressUsagePublicURLNotFound = errors.New("controlstate: ingress usage publish run number was not found")
	ErrPublicURLUsageBucketFinalized = errors.New("controlstate: public URL usage bucket is finalized")
)
View Source 
var (
	ErrPublicURLUsageDeliveryWorkStale = errors.New("controlstate: public URL usage delivery work is stale")
	ErrPublicURLUsageDeliveryInvalid   = errors.New("controlstate: public URL 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 ErrPublicURLRecoveryEpisodeStale = 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 ACMEAuthorizationState 

type ACMEAuthorizationState string

ACMEAuthorizationState is the persisted stage for one identifier in an order. cleaning records intent before a DNS provider call; complete records cleanup. 

const (
	ACMEAuthorizationPending    ACMEAuthorizationState = "pending"
	ACMEAuthorizationPresenting ACMEAuthorizationState = "presenting"
	ACMEAuthorizationPresented  ACMEAuthorizationState = "presented"
	ACMEAuthorizationValidating ACMEAuthorizationState = "validating"
	ACMEAuthorizationValid      ACMEAuthorizationState = "valid"
	ACMEAuthorizationCleaning   ACMEAuthorizationState = "cleaning"
	ACMEAuthorizationComplete   ACMEAuthorizationState = "complete"
	ACMEAuthorizationFailed     ACMEAuthorizationState = "failed"
	ACMEAuthorizationCanceled   ACMEAuthorizationState = "canceled"
)

type ACMEAuthorizationWork 

type ACMEAuthorizationWork struct {
	ID                    string
	Identifier            string
	AuthorizationURL      string
	ChallengeType         certificateidentity.ChallengeMethod
	ChallengeURL          string
	ChallengeToken        string
	ChallengeDigest       [32]byte
	PresentationReference string
	State                 ACMEAuthorizationState
	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 ACMEOrderState 

type ACMEOrderState string

ACMEOrderState is the persisted stage of one public URL certificate issuance. certificate availability and publisher installation are separate transitions. 

const (
	ACMEOrderPending           ACMEOrderState = "pending"
	ACMEOrderAuthorizing       ACMEOrderState = "authorizing"
	ACMEOrderReadyToFinalize   ACMEOrderState = "ready_to_finalize"
	ACMEOrderFinalizing        ACMEOrderState = "finalizing"
	ACMEOrderWaitingForInstall ACMEOrderState = "waiting_for_install"
	ACMEOrderInstalled         ACMEOrderState = "installed"
	ACMEOrderFailed            ACMEOrderState = "failed"
	ACMEOrderCanceled          ACMEOrderState = "canceled"
)

type ACMEOrderWork 

type ACMEOrderWork struct {
	ID                     string
	Account                ACMEAccount
	PublishRunID           string
	PublicURLID            string
	PublishRunNumber       uint64
	CertificateCacheKey    string
	CertificateScope       string
	CertificateIdentifiers []string
	ChallengeMethod        certificateidentity.ChallengeMethod
	CSRDER                 []byte
	CSRDigest              [32]byte
	State                  ACMEOrderState
	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 {
	EnabledPublicURLs   int64
	SuspendedPublicURLs int64
	StartingPublishRuns int64
	ReadyPublishRuns    int64
	IngressLeases       int64
	RelayLeases         int64
}

AdminRuntimeCounts contains current stored state counts for server status.

type AuthorizedPublicURLDeleteRequest 

type AuthorizedPublicURLDeleteRequest struct {
	PublicURLID              string
	TeamID                   string
	ActingIdentityID         string
	AuthorityIssuer          string
	PolicyRevision           uint64
	ExpectedMutationRevision uint64
}

type AuthorizedPublicURLUpdateRequest 

type AuthorizedPublicURLUpdateRequest struct {
	PublicURLID              string
	TeamID                   string
	ActingIdentityID         string
	Target                   string
	AllowedIPPrefixes        []string
	AuthorityIssuer          string
	PolicyRevision           uint64
	ExpectedMutationRevision uint64
}

type CertificateChallenge 

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

type CertificateIssuance 

type CertificateIssuance struct {
	ID               string
	PublishRunID     string
	PublicURLID      string
	PublishRunNumber uint64
	CertificatePlan  CertificatePlan
	State            ACMEOrderState
	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 certificateidentity.ChallengeMethod
}

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 publish-run setup and heartbeat replenishment.

type ConnectionAssignmentIdentity 

type ConnectionAssignmentIdentity struct {
	PublishRunID                 string
	PublicURLID                  string
	PublishRunNumber             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 PublishRunAuthentication
	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      TeamRole
	ExpiresAt        time.Time
	EmailRestriction string
	RetrySecret      []byte
}

type CreatePublicURLRequest 

type CreatePublicURLRequest struct {
	TeamID                string
	DomainID              string
	MembershipID          string
	ActingIdentityID      string
	IdempotencyKey        string
	RequestDigest         [32]byte
	CanonicalHostname     string
	Target                string
	PublicURLScope        PublicURLScope
	AllowedIPPrefixes     []string
	DNSState              PublicURLDNSState
	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           DNSAuthorityState
	RequiredRecords []DNSRecord
	LastError       string
	ProviderZoneID  string
	Nameservers     []string
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type DNSAuthorityState 

type DNSAuthorityState string

DNSAuthorityState is the stored state of a claimed-domain DNS authority. 

const (
	DNSAuthorityPending   DNSAuthorityState = "pending"
	DNSAuthorityReady     DNSAuthorityState = "ready"
	DNSAuthorityReleasing DNSAuthorityState = "releasing"
	DNSAuthorityReleased  DNSAuthorityState = "released"
	DNSAuthorityFailed    DNSAuthorityState = "failed"
)

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 DNSChallengeChange 

type DNSChallengeChange struct {
	DesiredDigest [32]byte
	ChangeID      string
}

type DNSChallengeContext 

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

type DNSChallengePresentation 

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

type DNSPublicURLWork 

type DNSPublicURLWork struct {
	PublicURLID           string
	DomainID              string
	DNSAuthorityReference string
	CanonicalHostname     string
	PublicURLScope        PublicURLScope
	State                 PublicURLDNSState
	DNSRevision           uint64
	Attempts              uint64
	AvailableAt           time.Time
	LastError             string
	WorkerID              string
	WorkEpoch             uint64
	WorkExpiresAt         time.Time
}

type DNSRecord 

type DNSRecord struct {
	Name  string
	Type  string
	Value string
}

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) ACMEChallengeRoutingReady 

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

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. the 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 publish runs 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) ClaimDNSPublicURLWork 

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

func (*Database) ClaimPublicURLUsageDeliveries 

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

ClaimPublicURLUsageDeliveries claims up to batchSize finalized buckets.

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) 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) ClosePublishRun 

func (d *Database) ClosePublishRun(ctx context.Context, publishRunID string, token credentials.PublishRunToken, now time.Time) (retErr error)

func (*Database) CompletePublicURLUsageDelivery 

func (d *Database) CompletePublicURLUsageDelivery(
	ctx context.Context,
	work PublicURLUsageDeliveryWork,
	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) CreatePublicURL 

func (d *Database) CreatePublicURL(ctx context.Context, request CreatePublicURLRequest, now time.Time) (result PublicURL, retErr error)

func (*Database) CreatePublishRun 

func (d *Database) CreatePublishRun(
	ctx context.Context,
	request PublishRunRequest,
	now time.Time,
	publisherLeaseDuration time.Duration,
	connectionCredentialDuration time.Duration,
) (result PublishRunSetup, retErr error)

CreatePublishRun creates one publish run with two connection assignments on distinct relay services. an authenticated retry returns the same publish run 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) DeleteAuthorizedPublicURL 

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

func (*Database) DeleteExpiredEphemeralPublicURLs 

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

DeleteExpiredEphemeralPublicURLs removes a bounded batch of expired public URLs. it uses the same publish-run, routing-table, and DNS cleanup as explicit deletion.

func (*Database) DeletePublicURL 

func (d *Database) DeletePublicURL(ctx context.Context, identityID, publicURLID 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 public URL and audit state and returns the shared retry secret.

func (*Database) ExpireSavedPublishRuns 

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

ExpireSavedPublishRuns closes at most one batch of expired runs, including runs on saved public URLs that no publisher will touch again. each closure also releases its relay reservations and publishes routing tombstones.

func (*Database) FinalizePublicURLUsageBuckets 

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

FinalizePublicURLUsageBuckets closes aggregate buckets through a cutoff and creates delivery work for each finalized revision.

func (*Database) GetAuthorizedPublicURLByHostname 

func (d *Database) GetAuthorizedPublicURLByHostname(ctx context.Context, teamID, hostname string) (PublicURL, error)

GetAuthorizedPublicURLByHostname reads one non-deleted public URL 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.PublishRunToken,
	now time.Time,
) (result CertificateIssuance, retErr error)

func (*Database) GetDNSAuthority 

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

func (*Database) GetDNSChallengeChange 

func (d *Database) GetDNSChallengeChange(ctx context.Context, zoneID, recordName string) (DNSChallengeChange, bool, error)

func (*Database) GetDNSChallengeContext 

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

func (*Database) GetPublicURL 

func (d *Database) GetPublicURL(ctx context.Context, identityID, publicURLID string) (PublicURL, error)

func (*Database) GetPublicURLForAuthorization 

func (d *Database) GetPublicURLForAuthorization(ctx context.Context, publicURLID string) (PublicURL, error)

GetPublicURLForAuthorization returns stored public URL data for an authority request. callers must not expose the result before the authority approves it.

func (*Database) GetPublicURLForPublishRunAuthorization 

func (d *Database) GetPublicURLForPublishRunAuthorization(
	ctx context.Context,
	publicURLID, idempotencyKey string,
) (PublicURL, error)

GetPublicURLForPublishRunAuthorization returns the publish run number from an earlier matching publish run request, or the next number for a new request.

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) 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) HeartbeatPublishRun 

func (d *Database) HeartbeatPublishRun(
	ctx context.Context,
	authentication PublishRunAuthentication,
	now time.Time,
	leaseDuration time.Duration,
	connectionCredentialDuration time.Duration,
) (result PublishRunSetup, retErr error)

HeartbeatPublishRun extends one publish run 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) ListAuthorizedPublicURLs 

func (d *Database) ListAuthorizedPublicURLs(ctx context.Context, teamID, cursor string) (PublicURLPage, error)

ListAuthorizedPublicURLs returns one team page after the caller has obtained a current authorization decision. it 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) ListPublicURLs 

func (d *Database) ListPublicURLs(ctx context.Context, identityID, teamID, cursor string) (PublicURLPage, 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.PublishRunToken,
	now time.Time,
) (CertificateIssuance, error)

func (*Database) MarkCertificateChallengeRemoved 

func (d *Database) MarkCertificateChallengeRemoved(
	ctx context.Context,
	issuanceID string,
	token credentials.PublishRunToken,
	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) MarkPublicURLCertificateInstalled 

func (d *Database) MarkPublicURLCertificateInstalled(
	ctx context.Context,
	authentication PublishRunAuthentication,
	issuanceID string,
	notAfter time.Time,
	now time.Time,
) (result PublishRunLifecycle, retErr error)

MarkPublicURLCertificateInstalled records publisher acknowledgement of the installed public URL certificate. first routability still requires both connections.

func (*Database) MarkPublishRunReady 

func (d *Database) MarkPublishRunReady(
	ctx context.Context,
	authentication PublishRunAuthentication,
	now time.Time,
) (result PublishRunLifecycle, retErr error)

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) Metrics 

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

Metrics returns one process-local database metrics snapshot.

func (*Database) ObservePublicURLRecovery 

func (d *Database) ObservePublicURLRecovery(
	ctx context.Context,
	ingressIdentity IngressLeaseIdentity,
	publicURLID string,
	publishRunNumber uint64,
	recoveryEpisodeID uint64,
	observedAt time.Time,
) (result PublicURLRecoveryObservation, retErr error)

ObservePublicURLRecovery 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) PublishRunAuthentication 

func (d *Database) PublishRunAuthentication(
	ctx context.Context,
	publishRunID string,
	publishRunNumber uint64,
	token credentials.PublishRunToken,
) (PublishRunAuthentication, error)

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 public URL 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 schema compatibility. 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 previous storage key. row locks last 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) RejectPublicURLUsageDelivery 

func (d *Database) RejectPublicURLUsageDelivery(
	ctx context.Context,
	work PublicURLUsageDeliveryWork,
	reason string,
	now time.Time,
) error

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 public URL usage buckets.

func (*Database) RetryPublicURLUsageDelivery 

func (d *Database) RetryPublicURLUsageDelivery(
	ctx context.Context,
	work PublicURLUsageDeliveryWork,
	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) 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) SaveDNSChallengeChange 

func (d *Database) SaveDNSChallengeChange(ctx context.Context, zoneID, recordName string, desiredDigest [32]byte, changeID string, now time.Time) error

func (*Database) SaveDNSPublicURLWork 

func (d *Database) SaveDNSPublicURLWork(ctx context.Context, work DNSPublicURLWork, now time.Time) (DNSPublicURLWork, 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 string,
	role TeamRole,
	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) UpdateAuthorizedPublicURL 

func (d *Database) UpdateAuthorizedPublicURL(
	ctx context.Context,
	request AuthorizedPublicURLUpdateRequest,
	now time.Time,
) (result PublicURL, 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. the dedicated transaction rolls back after the callback returns, releasing its lock; connection loss releases it too. the callback can still read through the pooled runtime connections.

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                  DomainKind
	TeamID                string
	CanonicalDomain       string
	DNSAuthorityReference string
	State                 DomainState
	AuthorityRevision     int64
	RequiredRecords       []DNSRecord
	CreatedAt             time.Time
	VerifiedAt            time.Time
	UpdatedAt             time.Time
}

type DomainKind 

type DomainKind string

DomainKind distinguishes managed and claimed team domains. 

const (
	DomainKindManaged DomainKind = "managed"
	DomainKindClaimed DomainKind = "claimed"
)

type DomainState 

type DomainState string

DomainState is the stored state of a team domain, including released domains. the team-domain query excludes released domains from public responses. 

const (
	DomainPending   DomainState = "pending"
	DomainReady     DomainState = "ready"
	DomainReleasing DomainState = "releasing"
	DomainReleased  DomainState = "released"
	DomainFailed    DomainState = "failed"
)

type IPPolicy 

type IPPolicy string

IPPolicy is the stored visitor address policy for a public URL. 

const (
	IPPolicyAllowAll  IPPolicy = "allow_all"
	IPPolicyAllowlist IPPolicy = "allowlist"
)

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
	PublicURLID          string
	PublishRunNumber     uint64
	CanonicalHostname    string
	EntryRevision        uint64
	Projection           IngressRoutingTableProjection
	PublicUrlExpiresAt   *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 (
	IngressPublicURLUpsert    IngressRoutingTableEventKind = "public_url_upsert"
	IngressPublicURLTombstone IngressRoutingTableEventKind = "public_url_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 {
	PublishRunID         string                                   `json:"publish_run_id"`
	PublicURLID          string                                   `json:"public_url_id"`
	PublishRunNumber     uint64                                   `json:"publish_run_number"`
	CanonicalHostname    string                                   `json:"canonical_hostname"`
	PolicyRevision       uint64                                   `json:"policy_revision"`
	IPPolicy             IPPolicy                                 `json:"ip_policy"`
	AllowedIPPrefixes    []netip.Prefix                           `json:"allowed_ip_prefixes"`
	PublicUrlExpiresAt   time.Time                                `json:"public_url_expires_at"`
	RecoveryEpisodeID    *uint64                                  `json:"recovery_episode_id,omitempty"`
	PublisherConnections []IngressRoutingTablePublisherConnection `json:"publisher_connections"`
}

IngressRoutingTableProjection is the stored public URL 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
	Entries               []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 {
	PublicURLID               string
	PublishRunNumber          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, public URL, publish run number, and time bucket.

type Invitation 

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

type InvitationSecret 

type InvitationSecret struct {
	Invitation Invitation
	Secret     string
}

type InvitationState 

type InvitationState string

InvitationState is the stored state of a team invitation. 

const (
	InvitationPending  InvitationState = "pending"
	InvitationAccepted InvitationState = "accepted"
	InvitationRevoked  InvitationState = "revoked"
	InvitationExpired  InvitationState = "expired"
)

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 (
	MaintenanceControlPublicURLCreation   MaintenanceControlName = "public_url_creation"
	MaintenanceControlPublishRunCreation  MaintenanceControlName = "publish_run_creation"
	MaintenanceControlCertificateIssuance MaintenanceControlName = "certificate_issuance"
)

type Membership 

type Membership struct {
	ID              string
	TeamID          string
	IdentityID      string
	TeamDisplayName string
	TeamKind        TeamKind
	Role            TeamRole
	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 PublicURL 

type PublicURL struct {
	ID                            string
	TeamID                        string
	DomainID                      string
	MembershipID                  string
	CanonicalHostname             string
	Target                        string
	PublicURLScope                PublicURLScope
	PolicyRevision                int64
	LifecycleState                PublicURLLifecycleState
	DNSAuthorityReference         string
	DNSState                      PublicURLDNSState
	AllowedIPPrefixes             []netip.Prefix
	NextPublishRunNumber          int64
	MutationRevision              uint64
	AuthorizationPublishRunNumber uint64
	Ephemeral                     bool
	ExpiresAt                     *time.Time
	OpenPublishRunID              string
	CreatedAt                     time.Time
	UpdatedAt                     time.Time
}

type PublicURLDNSState 

type PublicURLDNSState string

PublicURLDNSState is the stored state of public URL DNS. 

const (
	PublicURLDNSUnmanaged PublicURLDNSState = "unmanaged"
	PublicURLDNSPending   PublicURLDNSState = "pending"
	PublicURLDNSPublished PublicURLDNSState = "published"
	PublicURLDNSRemoving  PublicURLDNSState = "removing"
	PublicURLDNSRemoved   PublicURLDNSState = "removed"
	PublicURLDNSFailed    PublicURLDNSState = "failed"
)

type PublicURLLifecycleState 

type PublicURLLifecycleState string

PublicURLLifecycleState is the stored state of a public URL. 

const (
	PublicURLLifecycleEnabled   PublicURLLifecycleState = "enabled"
	PublicURLLifecycleSuspended PublicURLLifecycleState = "suspended"
	PublicURLLifecycleDeleted   PublicURLLifecycleState = "deleted"
)

type PublicURLPage 

type PublicURLPage struct {
	PublicURLs []PublicURL
	NextCursor string
}

type PublicURLRecoveryObservation 

type PublicURLRecoveryObservation struct {
	RecoveryEpisodeID uint64
	PublicURLID       string
	PublishRunNumber  uint64
	OpenedAt          time.Time
	ObservedAt        time.Time
	ObservedSeconds   float64
}

PublicURLRecoveryObservation is one stored public URL recovery measurement.

type PublicURLScope 

type PublicURLScope string

PublicURLScope identifies whether a public URL belongs to one membership or a team. 

const (
	PublicURLScopeMember PublicURLScope = "member"
	PublicURLScopeShared PublicURLScope = "shared"
)

type PublicURLUsageDeliveryWork 

type PublicURLUsageDeliveryWork struct {
	DeliveryID                uint64
	DeliveryKey               string
	SourceRevision            uint64
	PublicURLID               string
	PublishRunNumber          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                publicurlusage.Checkpoint
	Complete                  bool
	Attempts                  uint64
	WorkerID                  string
	WorkEpoch                 uint64
	WorkExpiresAt             time.Time
}

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

type PublishRunAuthentication 

type PublishRunAuthentication struct {
	PublishRunID     string
	PublicURLID      string
	PublishRunNumber uint64
	PublishRunToken  credentials.PublishRunToken
}

PublishRunAuthentication binds a publish run credential to one exact publish run number.

type PublishRunLifecycle 

type PublishRunLifecycle struct {
	PublishRunID                  string
	PublicURLID                   string
	TeamID                        string
	MembershipID                  string
	PublishRunNumber              uint64
	PolicyRevision                uint64
	State                         PublishRunState
	CreatedAt                     time.Time
	ExpiresAt                     time.Time
	ReadyAt                       *time.Time
	CertificateAt                 *time.Time
	ClosedAt                      *time.Time
	ReadyPublisherConnectionCount int
	Routable                      bool
	RoutingTableRevision          uint64
	PublicURLEntryRevision        uint64
}

PublishRunLifecycle reports saved readiness and current publisher connection availability.

type PublishRunNotReadyError 

type PublishRunNotReadyError struct {
	CertificateInstalled          bool
	ReadyPublisherConnectionCount int
	DNSState                      PublicURLDNSState
	CreatedAt                     time.Time
}

PublishRunNotReadyError reports the prerequisites checked under the public URL and publish run locks. it does not contain credentials or certificate material.

func (*PublishRunNotReadyError) Error 

func (e *PublishRunNotReadyError) Error() string

func (*PublishRunNotReadyError) Reason 

func (e *PublishRunNotReadyError) Reason() readiness.Outcome

func (*PublishRunNotReadyError) Unwrap 

func (e *PublishRunNotReadyError) Unwrap() error

type PublishRunRequest 

type PublishRunRequest struct {
	PublicURLID              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     certificateidentity.ChallengeMethod
	AuthorityIssuer          string
	ExpectedMutationRevision uint64
}

PublishRunRequest carries authority already established by the control API and the authenticated request secret used for retry-stable credentials.

type PublishRunSetup 

type PublishRunSetup struct {
	PublishRunID         string
	PublicURLID          string
	TeamID               string
	MembershipID         string
	PublishRunNumber     uint64
	PolicyRevision       uint64
	PublishRunToken      credentials.PublishRunToken
	State                PublishRunState
	CreatedAt            time.Time
	ExpiresAt            time.Time
	ReadyAt              *time.Time
	ClosedAt             *time.Time
	PolicyDenials        uint64
	PublisherConnections [publishRunConnectionCount]ConnectionAssignment
}

PublishRunSetup is the retry-stable result of publish-run creation.

type PublishRunState 

type PublishRunState string

PublishRunState is the stored state of one publish run. 

const (
	PublishRunStarting PublishRunState = "starting"
	PublishRunReady    PublishRunState = "ready"
	PublishRunClosed   PublishRunState = "closed"
	PublishRunExpired  PublishRunState = "expired"
	PublishRunCanceled PublishRunState = "canceled"
)

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 RelayCertificateOrderState 

type RelayCertificateOrderState string

RelayCertificateOrderState is the persisted stage of relay transport certificate issuance. cleaning precedes installation; failed_cleaning preserves cleanup after failure. 

const (
	RelayCertificatePending         RelayCertificateOrderState = "pending"
	RelayCertificateAuthorizing     RelayCertificateOrderState = "authorizing"
	RelayCertificatePresenting      RelayCertificateOrderState = "presenting"
	RelayCertificatePresented       RelayCertificateOrderState = "presented"
	RelayCertificateValidating      RelayCertificateOrderState = "validating"
	RelayCertificateReadyToFinalize RelayCertificateOrderState = "ready_to_finalize"
	RelayCertificateFinalizing      RelayCertificateOrderState = "finalizing"
	RelayCertificateCleaning        RelayCertificateOrderState = "cleaning"
	RelayCertificateFailedCleaning  RelayCertificateOrderState = "failed_cleaning"
	RelayCertificateComplete        RelayCertificateOrderState = "complete"
	RelayCertificateFailed          RelayCertificateOrderState = "failed"
)

type RelayCertificateOrderWork 

type RelayCertificateOrderWork struct {
	ID                     string
	Account                ACMEAccount
	RelayServiceID         string
	TLSServerName          string
	PrivateKeyPEM          []byte
	CSRDER                 []byte
	CSRDigest              [32]byte
	State                  RelayCertificateOrderState
	OrderRevision          uint64
	OrderURL               string
	FinalizeURL            string
	CertificateURL         string
	AuthorizationURL       string
	AuthorizationExpiresAt *time.Time
	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                 RelayCertificateOrderState
	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 RoutingHistoryPruneResult 

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

type Team 

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

type TeamKind 

type TeamKind string

TeamKind distinguishes personal and organization teams. 

const (
	TeamKindPersonal     TeamKind = "personal"
	TeamKindOrganization TeamKind = "organization"
)

type TeamRole 

type TeamRole string

TeamRole is a membership's authorization role. 

const (
	TeamRoleMember TeamRole = "member"
	TeamRoleAdmin  TeamRole = "admin"
	TeamRoleOwner  TeamRole = "owner"
)

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.