credential

package
v8.21.0 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package credential defines the main SDKCredential interface used throughout the codebase, as well as a means to detect how a credential has changed.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptedKey added in v8.21.0 

type AcceptedKey struct {
	// Expiry is the key's expiry. A nil expiry means the key is permanent.
	Expiry *time.Time
	// Key is the non-secret wire identifier, a human-readable name. Nil when the source carried none
	// (manual configuration, or an old-format payload predating concurrent keys).
	Key *string
}

AcceptedKey is the metadata for one accepted credential: its optional expiry and its optional wire identifier. The credential value itself is the map key wherever AcceptedKey is stored.

type AcceptedKeySet added in v8.21.0 

type AcceptedKeySet struct {
	Server        map[config.SDKKey]AcceptedKey
	Mobile        map[config.MobileKey]AcceptedKey
	Anchor        config.SDKKey
	PrimaryMobile config.MobileKey
}

AcceptedKeySet is a point-in-time snapshot of an environment's full accepted set, returned by Rotator.AcceptedKeys. Server and Mobile are keyed by credential value; Anchor and PrimaryMobile name the designated keys within them. Reads are taken under one lock, so the fields agree.

type AcceptedSet added in v8.21.0 

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

AcceptedSet is the full set of credentials an environment accepts after a reconcile: every server-side SDK key and mobile key with an optional expiry, the environment ID, and two designations.

  • The anchor is the one SDK key that owns the environment's upstream connection.
  • The primary mobile key is the default used where one mobile key is required, such as event forwarding.

Construct an AcceptedSet with AcceptedSetBuilder. Structural validation of the wire payload happens upstream, in BuildAcceptedSet.

type AcceptedSetBuilder added in v8.21.0 

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

AcceptedSetBuilder accumulates the credentials for an AcceptedSet. Build validates the accumulated set (see Build) before returning it.

func NewAcceptedSetBuilder added in v8.21.0 

func NewAcceptedSetBuilder() *AcceptedSetBuilder

NewAcceptedSetBuilder returns an empty AcceptedSetBuilder.

func (*AcceptedSetBuilder) Build added in v8.21.0 

func (b *AcceptedSetBuilder) Build() (AcceptedSet, error)

Build validates and returns the accumulated AcceptedSet. It returns a *MalformedCredentialSetError if no SDK key was added, or if no anchor was designated.

func (*AcceptedSetBuilder) WithAnchor added in v8.21.0 

func (b *AcceptedSetBuilder) WithAnchor(p SDKKeyParams) *AcceptedSetBuilder

WithAnchor adds p.Value and designates it as the anchor. The anchor is always permanent, so p.Expiry is ignored. It is a no-op if the value is undefined. Unlike WithSDKKey, it overwrites an existing entry for the value.

func (*AcceptedSetBuilder) WithEnvironmentID added in v8.21.0 

func (b *AcceptedSetBuilder) WithEnvironmentID(id config.EnvironmentID) *AcceptedSetBuilder

WithEnvironmentID sets the environment ID. It is a no-op if the ID is undefined.

func (*AcceptedSetBuilder) WithMobileKey added in v8.21.0 

func (b *AcceptedSetBuilder) WithMobileKey(p MobileKeyParams) *AcceptedSetBuilder

WithMobileKey adds a mobile key. It is a no-op if the value is undefined or already present.

func (*AcceptedSetBuilder) WithPrimaryMobileKey added in v8.21.0 

func (b *AcceptedSetBuilder) WithPrimaryMobileKey(p MobileKeyParams) *AcceptedSetBuilder

WithPrimaryMobileKey adds p.Value and designates it as the primary mobile key. The primary is always permanent, so p.Expiry is ignored. It is a no-op if the value is undefined.

func (*AcceptedSetBuilder) WithSDKKey added in v8.21.0 

func (b *AcceptedSetBuilder) WithSDKKey(p SDKKeyParams) *AcceptedSetBuilder

WithSDKKey adds a server-side SDK key. It is a no-op if the value is undefined or already present (the first metadata recorded for a value wins).

type AnchorChange added in v8.21.0 

type AnchorChange struct {
	PreviousAnchor              config.SDKKey
	PreviousAnchorName          *string
	NewAnchor                   config.SDKKey
	NewAnchorPreviouslyAccepted bool
}

AnchorChange describes an SDK anchor transition produced by Reconcile.

NewAnchorPreviouslyAccepted is false when the new anchor is a brand-new key, so the re-anchor must register that key's credential mappings. It is true when the key was already accepted, so the mappings already exist and a client may too. See envContextImpl.reanchor.

PreviousAnchorName is the previous anchor's wire "key" identifier, captured before this reconcile. A rollback that re-admits the previous anchor restores the name from here. See RevertAnchorChange. It is nil when the key had no name.

type MalformedCredentialSetError added in v8.21.0 

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

MalformedCredentialSetError is returned when a credential payload cannot produce a valid AcceptedSet. Each constructor below documents one cause.

Validation runs before Reconcile, so the environment keeps its previous accepted set. The caller must also reconnect the RAC stream with jitter: RAC is one-way push with no NAK channel, so without a reconnect the backend assumes the patch was applied and sends nothing new.

func NewAnchorNotInSetError added in v8.21.0 

func NewAnchorNotInSetError() *MalformedCredentialSetError

NewAnchorNotInSetError reports a payload whose designated anchor (sdkKey.value) is defined but absent from sdkKeys[]. Credential values are secrets, so no message here includes one.

func NewEmptyCredentialError added in v8.21.0 

func NewEmptyCredentialError(kind, key string) *MalformedCredentialSetError

NewEmptyCredentialError reports a key-array entry whose value field is empty. kind is "sdkKeys" or "mobileKeys"; key is the entry's wire identifier, which old-format payloads leave empty.

func NewPrimaryMobileKeyMissingError added in v8.21.0 

func NewPrimaryMobileKeyMissingError() *MalformedCredentialSetError

NewPrimaryMobileKeyMissingError reports a payload with a non-empty mobileKeys[] and no designated primary. Accepting it would clear the primary without a repoint, leaving event forwarding on the previous key.

func NewPrimaryMobileKeyNotInSetError added in v8.21.0 

func NewPrimaryMobileKeyNotInSetError() *MalformedCredentialSetError

NewPrimaryMobileKeyNotInSetError reports a payload whose designated primary mobile key (mobKey) is defined but absent from mobileKeys[].

func (*MalformedCredentialSetError) Error added in v8.21.0 

func (e *MalformedCredentialSetError) Error() string

type MobileKeyParams added in v8.21.0 

type MobileKeyParams struct {
	Value  config.MobileKey
	Key    *string
	Expiry *time.Time
}

MobileKeyParams describes one accepted mobile key for the builder. See SDKKeyParams.

type ReconcileResult added in v8.21.0 

type ReconcileResult struct {
	AnchorChange         *AnchorChange
	MobilePrimaryRepoint *config.MobileKey
}

ReconcileResult signals state changes the caller must apply itself, rather than through the StepTime-driven addCredential and removeCredential flow.

AnchorChange is non-nil when the SDK anchor changed. The caller drives the re-anchor sequence; see envContextImpl.reanchor.

MobilePrimaryRepoint is non-nil when the primary mobile key changed to a key already accepted. Such a key is not in additions, so addCredential does not repoint the event dispatcher for it and the caller must do so.

type Rotator added in v8.8.0 

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

func NewRotator added in v8.8.0 

func NewRotator(loggers ldlog.Loggers) *Rotator

NewRotator constructs a rotator with the provided loggers. A new rotator contains no credentials and can optionally be initialized via Initialize.

func (*Rotator) AcceptedKeys added in v8.21.0 

func (r *Rotator) AcceptedKeys() AcceptedKeySet

AcceptedKeys returns a snapshot of the full accepted set. See AcceptedKeySet.

func (*Rotator) AllCredentials added in v8.8.0 

func (r *Rotator) AllCredentials() []SDKCredential

AllCredentials returns every accepted credential: SDK keys, mobile keys, and the environment ID.

func (*Rotator) AnchorKey added in v8.21.0 

func (r *Rotator) AnchorKey() config.SDKKey

AnchorKey returns the anchor SDK key, which owns the upstream connection.

func (*Rotator) CommitAnchor added in v8.21.0 

func (r *Rotator) CommitAnchor(key config.SDKKey)

CommitAnchor moves the rotator's SDK anchor pointer to key. The caller invokes it once the new anchor's client is ready. Until then the anchor stays on the previous key, so GetClient() returns the still-serving old client. Initialize and CommitAnchor are the only paths that move the pointer.

func (*Rotator) DeprecatedCredentials added in v8.8.0 

func (r *Rotator) DeprecatedCredentials() []SDKCredential

DeprecatedCredentials returns every accepted SDK key, other than the anchor, that carries an expiry. It does not return mobile keys, which expire the same way.

func (*Rotator) EnvironmentID added in v8.8.0 

func (r *Rotator) EnvironmentID() config.EnvironmentID

EnvironmentID returns the environment ID.

func (*Rotator) Initialize added in v8.8.0 

func (r *Rotator) Initialize(credentials []SDKCredential)

Initialize sets the initial credentials. Only credentials that are defined will be stored.

func (*Rotator) IsAccepted added in v8.21.0 

func (r *Rotator) IsAccepted(cred SDKCredential) bool

IsAccepted reports whether cred is currently one of the environment's accepted credentials: an accepted SDK key, an accepted mobile key (including one carrying a future expiry, which still authenticates until the cleanup ticker drops it), or the environment ID. Any other credential type is never accepted.

This answers the same question as membership in AllCredentials, by direct map lookup, so callers on request paths do not allocate a credential slice per call.

func (*Rotator) MobileKey added in v8.8.0 

func (r *Rotator) MobileKey() config.MobileKey

MobileKey returns the primary mobile key.

func (*Rotator) Reconcile added in v8.21.0 

func (r *Rotator) Reconcile(set AcceptedSet, now time.Time) ReconcileResult

Reconcile updates the rotator to match set. It queues additions and expirations, which the next StepTime call drains. Keys newly present are accepted; keys no longer present are revoked. An undefined environment ID leaves the current one unchanged. Per-key expiry is stored on the accepted entry, and StepTime acts on it.

set is assumed well-formed: AcceptedSetBuilder.Build already guaranteed a designated anchor.

Reconcile does NOT flip the anchor pointer. The returned AnchorChange signals the change; the caller drives the re-anchor and then calls CommitAnchor. A brand-new anchor is also stripped from additions, because reanchor registers that key's mappings itself.

func (*Rotator) RevertAnchorChange added in v8.21.0 

func (r *Rotator) RevertAnchorChange(change AnchorChange)

RevertAnchorChange undoes the accepted-set effects of a failed re-anchor. CommitAnchor was never called, so the anchor pointer still names the previous anchor. This method realigns the accepted set.

If this reconcile revoked the previous anchor outright, RevertAnchorChange re-admits that key as a permanent key with no expiry. The re-admission discards the key's previous expiry, because that key is still the anchor and still serving. It keeps the key's name, so /status still names the key that is serving. A previous anchor that is only grace-demoted stays accepted and keeps its expiry. The new anchor is dropped only if that key was brand new.

func (*Rotator) StepTime added in v8.8.0 

func (r *Rotator) StepTime(now time.Time) (additions []SDKCredential, expirations []SDKCredential)

StepTime provides the current time to the Rotator, so it can compute the additions and expirations for the tracked credentials since the last call. It enforces per-key expiry for SDK and mobile keys, strictly after a key's expiry timestamp.

type SDKCredential 

type SDKCredential interface {
	// GetAuthorizationHeaderValue returns the value that should be passed in an HTTP Authorization header
	// when using this credential, or "" if the header is not used.
	GetAuthorizationHeaderValue() string
	// Defined returns true if the credential is present.
	Defined() bool
	// String returns the string form of the credential.
	String() string
	// Masked returns a masked form of the credential suitable for log messages.
	Masked() string
}

SDKCredential is implemented by types that represent an SDK authorization credential (SDKKey, etc.).

type SDKKeyParams added in v8.21.0 

type SDKKeyParams struct {
	Value  config.SDKKey
	Key    *string
	Expiry *time.Time
}

SDKKeyParams describes one accepted server-side SDK key for the builder: the credential value plus the optional wire "key" identifier (nil when absent) and optional expiry (nil = permanent).

Source Files

View all Source files

Jump to

Keyboard shortcuts

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