home

package
v8.0.21 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source
const (
	InFlightFramePart     InFlightFrameKind       = "part"
	InFlightFrameOverflow InFlightFrameKind       = "overflow"
	InFlightAccounted     InFlightAccountedStatus = "accounted"
	InFlightUnaccounted   InFlightAccountedStatus = "unaccounted"
)

Variables

View Source
var (
	ErrDisabled              = errors.New("home client disabled")
	ErrNotConnected          = errors.New("home not connected")
	ErrEmptyResponse         = errors.New("home returned empty response")
	ErrAuthNotFound          = errors.New("home auth not found")
	ErrConfigNotFound        = errors.New("home config not found")
	ErrModelsNotFound        = errors.New("home models not found")
	ErrPluginSyncUnsupported = errors.New("home plugin sync is unsupported")
	ErrDispatchFenced        = errors.New("home auth dispatch is fenced")
	// ErrCompareAndSwapUnsupported reports that this Home predates the CAS command.
	ErrCompareAndSwapUnsupported = errors.New("home compare-and-swap is unsupported")
)

Functions

func ClearCurrent

func ClearCurrent()

ClearCurrent removes the active home client.

func ClearCurrentIf

func ClearCurrentIf(client *Client)

ClearCurrentIf removes the active client only when it is client.

func ConfigFromJWT

func ConfigFromJWT(ctx context.Context, rawJWT string) (config.HomeConfig, error)

ConfigFromJWT prepares a Home config from the JWT and ensures local mTLS files exist.

func HashKeyPart

func HashKeyPart(value string) string

func IsAmbiguousDispatchError

func IsAmbiguousDispatchError(err error) bool

IsAmbiguousDispatchError reports whether Home may have processed the dispatch request.

func IsLegacyMembershipProtocolError

func IsLegacyMembershipProtocolError(err error) bool

IsLegacyMembershipProtocolError reports whether Home rejected the secure subscription argument count.

func IsMembershipTakeoverUnavailableError

func IsMembershipTakeoverUnavailableError(err error) bool

IsMembershipTakeoverUnavailableError reports whether Home cannot preserve the previous membership state.

func KVDelBestEffort

func KVDelBestEffort(ctx context.Context, keys ...string) bool

func KVDelRequired

func KVDelRequired(ctx context.Context, keys ...string) (bool, int64, error)

func KVExpireBestEffort

func KVExpireBestEffort(ctx context.Context, key string, ttl time.Duration) bool

func KVExpireRequired

func KVExpireRequired(ctx context.Context, key string, ttl time.Duration) (bool, error)

func KVGetJSONBestEffort

func KVGetJSONBestEffort(ctx context.Context, key string, out any) (bool, bool)

func KVGetJSONRequired

func KVGetJSONRequired(ctx context.Context, key string, out any) (bool, bool, error)

func KVSetBytesBestEffort

func KVSetBytesBestEffort(ctx context.Context, key string, value []byte, ttl time.Duration) bool

func KVSetBytesRequired

func KVSetBytesRequired(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)

func KVSetJSONBestEffort

func KVSetJSONBestEffort(ctx context.Context, key string, value any, ttl time.Duration) bool

func KVSetJSONRequired

func KVSetJSONRequired(ctx context.Context, key string, value any, ttl time.Duration) (bool, error)

func KVSetNXBestEffort

func KVSetNXBestEffort(ctx context.Context, key string, value []byte, ttl time.Duration) bool

func KVSetNXRequired

func KVSetNXRequired(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, bool, error)

func NewAmbiguousDispatchError

func NewAmbiguousDispatchError(err error) error

NewAmbiguousDispatchError marks a post-send transport failure as requiring a client abort.

func NewReleaseFlusher

func NewReleaseFlusher(configProvider func() internalconfig.CredentialConcurrencyConfig, send func(context.Context, ConcurrencyReleaseFrame) error) *releaseFlusher

NewReleaseFlusher creates a flusher that reads timing updates from the current limiter configuration.

func ReportPluginStatus

func ReportPluginStatus(ctx context.Context, client PluginStatusClient, nodeID string, report homeplugins.SyncReport) error

ReportPluginStatus marshals the given report, sets NodeID and UpdatedAt, and pushes it to the provided client with a timeout.

func SetCurrent

func SetCurrent(client *Client)

SetCurrent sets the active home client used by runtime integrations.

Types

type Client

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

func Current

func Current() *Client

Current returns the active home client instance, if any.

func CurrentKVClient

func CurrentKVClient() (*Client, bool, error)

func New

func New(homeCfg config.HomeConfig) *Client

func (*Client) AbortAmbiguousDispatch

func (c *Client) AbortAmbiguousDispatch()

AbortAmbiguousDispatch fences this client after an auth dispatch response is ambiguous.

func (*Client) AmbiguousDispatch

func (c *Client) AmbiguousDispatch() bool

AmbiguousDispatch reports whether this lifetime observed an issued dispatch with an unknown delivery result.

func (*Client) Close

func (c *Client) Close()

Close permanently ends this client's dispatch lifetime.

func (*Client) EnableLegacyMembership

func (c *Client) EnableLegacyMembership()

EnableLegacyMembership permanently downgrades this subscriber lifetime chain.

func (*Client) Enabled

func (c *Client) Enabled() bool

func (*Client) GetConfig

func (c *Client) GetConfig(ctx context.Context) ([]byte, error)

func (*Client) GetModels

func (c *Client) GetModels(ctx context.Context, headers http.Header, query url.Values) ([]byte, error)

func (*Client) GetPluginSync

func (*Client) GetPluginTasks

func (c *Client) GetPluginTasks(ctx context.Context) ([]PluginTask, error)

func (*Client) GetRefreshAuth

func (c *Client) GetRefreshAuth(ctx context.Context, authIndex string, accessTokenSHA256 string) ([]byte, error)

func (*Client) HeartbeatOK

func (c *Client) HeartbeatOK() bool

func (*Client) KVCompareAndSwap

func (c *Client) KVCompareAndSwap(ctx context.Context, key string, expected []byte, expectedExists bool, value []byte, ttl time.Duration) (bool, error)

KVCompareAndSwap atomically replaces a value only when its current state matches the expected state.

It uses Home's dedicated CAS command:

CAS <key> <expected-exists 0|1> <expected-value> <new-value> [PX <ttl-ms>]

Omitting PX stores the value without a TTL. Home replies integer 1 when the swap happened and integer 0 when the state did not match. Deployments that predate CAS reject the command, which latches ErrCompareAndSwapUnsupported for this client lifetime so later calls skip the round trip.

func (*Client) KVDel

func (c *Client) KVDel(ctx context.Context, keys ...string) (int64, error)

func (*Client) KVExpire

func (c *Client) KVExpire(ctx context.Context, key string, ttl time.Duration) (bool, error)

func (*Client) KVGet

func (c *Client) KVGet(ctx context.Context, key string) ([]byte, bool, error)

func (*Client) KVIncrBy

func (c *Client) KVIncrBy(ctx context.Context, key string, delta int64) (int64, error)

func (*Client) KVMGet

func (c *Client) KVMGet(ctx context.Context, keys ...string) ([][]byte, []bool, error)

func (*Client) KVMSet

func (c *Client) KVMSet(ctx context.Context, pairs map[string][]byte) error

func (*Client) KVSet

func (c *Client) KVSet(ctx context.Context, key string, value []byte, opts KVSetOptions) (bool, error)

func (*Client) KVSetNX

func (c *Client) KVSetNX(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)

func (*Client) KVTTL

func (c *Client) KVTTL(ctx context.Context, key string) (time.Duration, bool, error)

func (*Client) LPushInFlightSnapshot

func (c *Client) LPushInFlightSnapshot(ctx context.Context, payload []byte) error

LPushInFlightSnapshot publishes a bounded in-flight observation frame.

func (*Client) LPushUsage

func (c *Client) LPushUsage(ctx context.Context, payload []byte) error

func (*Client) LegacyMembership

func (c *Client) LegacyMembership() bool

LegacyMembership reports whether this subscriber has downgraded to the legacy protocol.

func (*Client) LimiterConfig

func (c *Client) LimiterConfig() config.CredentialConcurrencyConfig

LimiterConfig returns the latest immutable, validated Home limiter configuration.

func (*Client) MembershipInstanceID

func (c *Client) MembershipInstanceID() string

MembershipInstanceID returns the process-scoped Home membership identity.

func (*Client) NewLifetime

func (c *Client) NewLifetime() *Client

NewLifetime creates a fresh client while preserving cluster failover state.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

func (*Client) PushConcurrencyRelease

func (c *Client) PushConcurrencyRelease(ctx context.Context, frame ConcurrencyReleaseFrame) error

PushConcurrencyRelease sends one cumulative concurrency release frame through an independent client.

func (*Client) RPopAuth

func (c *Client) RPopAuth(ctx context.Context, requestedModel string, sessionID string, headers http.Header, count int) ([]byte, error)

func (*Client) RPopAuthWithConstraints

func (c *Client) RPopAuthWithConstraints(ctx context.Context, requestedModel string, sessionID string, headers http.Header, count int, excludedAuthIDs []string, pinnedAuthID string) ([]byte, error)

RPopAuthWithConstraints requests a credential using the current retry-round exclusions and optional pinned credential constraint.

func (*Client) RPopAuthWithPolicy

func (c *Client) RPopAuthWithPolicy(ctx context.Context, requestedModel string, sessionID string, headers http.Header, count int, credentialPolicy string) ([]byte, error)

RPopAuthWithPolicy requests a Home credential constrained by the supplied fixed policy.

func (*Client) RPopAuthWithPolicyAndConstraints

func (c *Client) RPopAuthWithPolicyAndConstraints(ctx context.Context, requestedModel string, sessionID string, headers http.Header, count int, credentialPolicy string, excludedAuthIDs []string, pinnedAuthID string) ([]byte, error)

RPopAuthWithPolicyAndConstraints combines a fixed credential policy with the current retry-round exclusions and optional pinned credential constraint.

func (*Client) RPopAuthWithPolicyAndRetryRoundConstraints

func (c *Client) RPopAuthWithPolicyAndRetryRoundConstraints(ctx context.Context, requestedModel string, sessionID string, headers http.Header, count int, credentialPolicy string, retryRound int, excludedAuthIDs []string, pinnedAuthID string) ([]byte, error)

RPopAuthWithPolicyAndRetryRoundConstraints combines a credential policy with the retry round, current-round exclusions, and optional pin.

func (*Client) RPopAuthWithRetryRoundConstraints

func (c *Client) RPopAuthWithRetryRoundConstraints(ctx context.Context, requestedModel string, sessionID string, headers http.Header, count int, retryRound int, excludedAuthIDs []string, pinnedAuthID string) ([]byte, error)

RPopAuthWithRetryRoundConstraints requests a credential with the retry round, current-round exclusions, and optional pinned credential constraint.

func (*Client) RPopAuthWithSessionHierarchy

func (c *Client) RPopAuthWithSessionHierarchy(ctx context.Context, requestedModel string, sessionID string, parentSessionID string, headers http.Header, count int, credentialPolicy string, retryRound *int, excludedAuthIDs []string, pinnedAuthID string) ([]byte, error)

RPopAuthWithSessionHierarchy requests a Home credential with both session ID and parent session ID for hierarchical soft affinity.

func (*Client) RPushAppLog

func (c *Client) RPushAppLog(ctx context.Context, payload []byte) error

func (*Client) RPushPluginStatus

func (c *Client) RPushPluginStatus(ctx context.Context, payload []byte) error

func (*Client) RPushRequestLog

func (c *Client) RPushRequestLog(ctx context.Context, payload []byte) error

func (*Client) RunConfigSubscriberLifetime

func (c *Client) RunConfigSubscriberLifetime(ctx context.Context, onConfig func([]byte) error, onReady func()) error

RunConfigSubscriberLifetime runs one GET, SUBSCRIBE, and receive lifetime. Reconnection is owned by the service so each replacement can install a new client lifetime.

func (*Client) SetLifecycleConfig

func (c *Client) SetLifecycleConfig(cfg config.CredentialConcurrencyConfig) error

func (*Client) SetManagedLifetime

func (c *Client) SetManagedLifetime(managed bool)

SetManagedLifetime defers client shutdown to the Service lifetime owner.

func (*Client) StartConfigSubscriber

func (c *Client) StartConfigSubscriber(ctx context.Context, onConfig func([]byte) error)

StartConfigSubscriber is retained for callers that do not need the lifetime error.

func (*Client) SuppressTakeover

func (c *Client) SuppressTakeover()

SuppressTakeover forces the next subscriber lifetime through normal membership recovery.

type ConcurrencyReleaseFrame

type ConcurrencyReleaseFrame struct {
	CredentialID string `json:"credential_id"`
	Model        string `json:"model"`
	ReleaseSeq   int64  `json:"release_seq"`
}

ConcurrencyReleaseFrame is the cumulative release accepted by Home for one credential and model.

type DispatchError

type DispatchError struct {
	Err       error
	Ambiguous bool
}

DispatchError classifies whether Home may have processed an auth dispatch request.

func (*DispatchError) Error

func (e *DispatchError) Error() string

func (*DispatchError) Unwrap

func (e *DispatchError) Unwrap() error

type InFlightAccountedStatus

type InFlightAccountedStatus string

type InFlightAggregate

type InFlightAggregate struct {
	CredentialID string                  `json:"credential_id"`
	Model        string                  `json:"model"`
	Status       InFlightAccountedStatus `json:"status"`
	Count        int64                   `json:"count"`
}

type InFlightFrameKind

type InFlightFrameKind string

type InFlightRequestDetail

type InFlightRequestDetail struct {
	RequestID    string    `json:"request_id"`
	CredentialID string    `json:"credential_id"`
	Model        string    `json:"model"`
	RequestKind  string    `json:"request_kind"`
	StartedAt    time.Time `json:"started_at"`
}

type InFlightSnapshotFrame

type InFlightSnapshotFrame struct {
	Kind                InFlightFrameKind       `json:"kind"`
	Revision            int64                   `json:"revision"`
	ObservedAt          time.Time               `json:"observed_at"`
	BarrierRevision     int64                   `json:"barrier_revision"`
	PartIndex           *int                    `json:"part_index,omitempty"`
	PartCount           *int                    `json:"part_count,omitempty"`
	DetailsTruncated    bool                    `json:"details_truncated,omitempty"`
	Aggregates          []InFlightAggregate     `json:"aggregates,omitempty"`
	Details             []InFlightRequestDetail `json:"details,omitempty"`
	AggregateGroupCount int                     `json:"aggregate_group_count,omitempty"`
}

type KVSetOptions

type KVSetOptions struct {
	EX time.Duration
	PX time.Duration
	NX bool
	XX bool
}

type PluginStatusClient

type PluginStatusClient interface {
	RPushPluginStatus(ctx context.Context, payload []byte) error
}

PluginStatusClient defines the interface for pushing plugin status reports.

type PluginTask

type PluginTask struct {
	ID             uint      `json:"id"`
	Operation      string    `json:"operation"`
	PluginID       string    `json:"plugin_id"`
	TargetNodeType string    `json:"target_node_type,omitempty"`
	TargetNodeID   string    `json:"target_node_id,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL