cachecore

package
v4.0.0 Latest Latest
Warning

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

Go to latest
Published: Jun 29, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package cachecore provides reusable client-side cache and outbox mechanics.

The package is intentionally domain-agnostic and does not include example-100 or product-specific resource names.

Index

Constants

View Source
const (
	InvalidationReasonLogout                = "logout"
	InvalidationReasonSessionRevoked        = "session_revoked"
	InvalidationReasonWorkspaceSwitch       = "workspace_switch"
	InvalidationReasonLocaleChange          = "locale_change"
	InvalidationReasonAppVersionChange      = "app_version_change"
	InvalidationReasonMutationAck           = "mutation_ack"
	InvalidationReasonRouteThreadNormalize  = "route_thread_normalization"
	InvalidationReasonServerVersionMismatch = "server_version_hash_mismatch"
)
View Source
const (
	CacheStatusReady = "ready"
	CacheStatusStale = "stale"
	CacheStatusError = "error"
)
View Source
const (
	OutboxStatusQueued  = "queued"
	OutboxStatusSending = "sending"
	OutboxStatusAcked   = "acked"
	OutboxStatusFailed  = "failed"
)
View Source
const (
	FlushOperationPersistLowPriority = "persist_low_priority"
	FlushOperationDrainQueuedLogs    = "drain_queued_logs"
	FlushOperationResendQueuedSends  = "resend_queued_sends"
)

Variables

This section is empty.

Functions

func BuildCacheRecordEnvelopeJSON

func BuildCacheRecordEnvelopeJSON(parseRecord CacheRecordEnvelope) ([]byte, error)

BuildCacheRecordEnvelopeJSON marshals one normalized cache-record envelope into JSON.

func BuildFreshnessWindow

func BuildFreshnessWindow(parseFetchedAt time.Time, parseStaleAfter time.Duration, parseExpiresAfter time.Duration) (string, string, string)

BuildFreshnessWindow formats fetched/stale/expire timestamps from one fetched-at baseline and TTL policy.

func BuildOutboxRecordEnvelopeJSON

func BuildOutboxRecordEnvelopeJSON(parseRecord OutboxRecordEnvelope) ([]byte, error)

BuildOutboxRecordEnvelopeJSON marshals one normalized outbox-record envelope into JSON.

func BuildScopeKey

func BuildScopeKey(parseScope ScopeKey) string

BuildScopeKey formats one stable scope key for cache and outbox records.

func BuildScopePrefixForAccountSwitch

func BuildScopePrefixForAccountSwitch(parseScope ScopeKey) string

BuildScopePrefixForAccountSwitch returns one deterministic scope prefix for account-switch eviction.

func BuildScopePrefixForLocaleSwitch

func BuildScopePrefixForLocaleSwitch(parseScope ScopeKey) string

BuildScopePrefixForLocaleSwitch returns one deterministic scope prefix for locale-switch eviction.

func BuildScopePrefixForLogout

func BuildScopePrefixForLogout(parseScope ScopeKey) string

BuildScopePrefixForLogout returns one deterministic scope prefix for logout/session-eviction events.

func BuildScopePrefixForWorkspaceSwitch

func BuildScopePrefixForWorkspaceSwitch(parseScope ScopeKey) string

BuildScopePrefixForWorkspaceSwitch returns one deterministic scope prefix for workspace-switch eviction.

func BuildScopedResourceKey

func BuildScopedResourceKey(parseScopeKey string, parseResourceKey string) string

BuildScopedResourceKey combines one scope key with one resource key for lookups and de-duplication.

func EnforceLocalSecrecyForCacheRecord

func EnforceLocalSecrecyForCacheRecord(parseRecord CacheRecordEnvelope) error

EnforceLocalSecrecyForCacheRecord validates cache-record payloads against local secrecy persistence rules.

func EnforceLocalSecrecyForOutboxRecord

func EnforceLocalSecrecyForOutboxRecord(parseRecord OutboxRecordEnvelope) error

EnforceLocalSecrecyForOutboxRecord validates outbox-record payloads against local secrecy persistence rules.

func EnforceSecurityDecision

func EnforceSecurityDecision(parseDecision SecurityDecision) error

EnforceSecurityDecision returns one error when one security decision denies an action.

Types

type AckReconcileInput

type AckReconcileInput struct {
	QueueKey                  string
	AckKey                    string
	OperationKey              string
	ScopeKey                  string
	ResourceKey               string
	AuthoritativeRecord       CacheRecordEnvelope
	OptimisticScopedResources []string
}

AckReconcileInput describes one queue-ack reconciliation operation.

type AckReconcileResult

type AckReconcileResult struct {
	QueueRemovedCount int
	IsCacheUpdated    bool
}

AckReconcileResult describes one reconciliation outcome.

func ApplyAckReconcile

func ApplyAckReconcile(parseCtx context.Context, parseStorage Storage, parseInput AckReconcileInput) (AckReconcileResult, error)

ApplyAckReconcile clears acked queue writes, merges authoritative records, and removes optimistic placeholders.

type BrowserStorage

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

BrowserStorage stores cache/outbox records in browser localStorage.

func BuildBrowserStorage

func BuildBrowserStorage() (*BrowserStorage, error)

BuildBrowserStorage creates one browser-backed storage implementation.

func (*BrowserStorage) Delete

func (parseStorage *BrowserStorage) Delete(parseCtx context.Context, parseScopedResourceKey string) error

Delete removes one cache record by scoped resource key in localStorage.

func (*BrowserStorage) DeleteByPrefix

func (parseStorage *BrowserStorage) DeleteByPrefix(parseCtx context.Context, parseScopePrefix string) (int, error)

DeleteByPrefix removes all cache records matching one scope-prefix filter in localStorage.

func (*BrowserStorage) Get

func (parseStorage *BrowserStorage) Get(parseCtx context.Context, parseScopedResourceKey string) (CacheRecordEnvelope, bool, error)

Get returns one cache record by scoped resource key from localStorage.

func (*BrowserStorage) List

func (parseStorage *BrowserStorage) List(parseCtx context.Context, parseScopePrefix string) ([]CacheRecordEnvelope, error)

List returns all cache records matching one scope-prefix filter from localStorage.

func (*BrowserStorage) Set

func (parseStorage *BrowserStorage) Set(parseCtx context.Context, parseRecord CacheRecordEnvelope) error

Set stores one normalized cache record in localStorage.

func (*BrowserStorage) UpdateQueueAtomic

func (parseStorage *BrowserStorage) UpdateQueueAtomic(parseCtx context.Context, parseQueueKey string, parseMutate func([]OutboxRecordEnvelope) ([]OutboxRecordEnvelope, error)) ([]OutboxRecordEnvelope, error)

UpdateQueueAtomic applies one queue mutation against one localStorage queue envelope.

type CachePolicy

type CachePolicy struct {
	Class                       PolicyClass
	StaleAfter                  time.Duration
	ExpiresAfter                time.Duration
	CanBackgroundRefresh        bool
	ShouldDisplayOnlyWhenStale  bool
	ShouldRefetchBeforeMutation bool
}

CachePolicy describes freshness, background-refresh, and mutation-gating behavior.

func BuildCachePolicy

func BuildCachePolicy(
	parseClass PolicyClass,
	parseStaleAfter time.Duration,
	parseExpiresAfter time.Duration,
	isParseBackgroundRefreshEnabled bool,
	isParseDisplayOnlyWhenStale bool,
	isParseMustRefetchBeforeMutation bool,
) CachePolicy

BuildCachePolicy builds one normalized cache policy from explicit configuration.

func NormalizeCachePolicy

func NormalizeCachePolicy(parsePolicy CachePolicy) CachePolicy

NormalizeCachePolicy normalizes one policy to valid class/duration bounds.

func ResolveCachePolicyDefaults

func ResolveCachePolicyDefaults(parseClass PolicyClass) CachePolicy

ResolveCachePolicyDefaults returns one default policy for one class.

type CacheRecordEnvelope

type CacheRecordEnvelope struct {
	ScopeKey    string `json:"scope_key"`
	ResourceKey string `json:"resource_key"`
	Version     string `json:"version"`
	ETagOrHash  string `json:"etag_or_hash"`
	FetchedAt   string `json:"fetched_at"`
	StaleAt     string `json:"stale_at"`
	ExpiresAt   string `json:"expires_at"`
	Payload     []byte `json:"parsePayload"`
	Status      string `json:"parseStatus"`
	Error       string `json:"parseError"`
}

CacheRecordEnvelope stores one persistent cache row with canonical persistence shape.

func BuildCacheRecordEnvelope

func BuildCacheRecordEnvelope(
	parseScopeKey string,
	parseResourceKey string,
	parseVersion string,
	parseETagOrHash string,
	parseFetchedAt time.Time,
	parseStaleAfter time.Duration,
	parseExpiresAfter time.Duration,
	parsePayload []byte,
	parseStatus string,
	parseError string,
) CacheRecordEnvelope

BuildCacheRecordEnvelope builds one canonical cache-record envelope using one freshness policy.

func NormalizeCacheRecordEnvelope

func NormalizeCacheRecordEnvelope(parseRecord CacheRecordEnvelope) CacheRecordEnvelope

NormalizeCacheRecordEnvelope normalizes one cache envelope into one canonical contract-safe shape.

func ParseCacheRecordEnvelopeJSON

func ParseCacheRecordEnvelopeJSON(parseRaw []byte) (CacheRecordEnvelope, error)

ParseCacheRecordEnvelopeJSON unmarshals one persisted cache-record envelope JSON payload.

type CachedResourceView

type CachedResourceView struct {
	Record           CacheRecordEnvelope
	IsFound          bool
	IsCached         bool
	IsStale          bool
	Freshness        FreshnessState
	RefreshTriggered bool
}

CachedResourceView stores UI-facing cached-read metadata.

type ConnectivityCoordinator

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

ConnectivityCoordinator tracks connectivity transitions and emits change notifications.

func BuildConnectivityCoordinator

func BuildConnectivityCoordinator(parseInitialState ConnectivityState) *ConnectivityCoordinator

BuildConnectivityCoordinator creates one connectivity coordinator with one initial state.

func (*ConnectivityCoordinator) ApplyAppActiveState

func (parseCoordinator *ConnectivityCoordinator) ApplyAppActiveState(isParseAppActive bool) ConnectivityState

ApplyAppActiveState updates only app-active lifecycle state and emits one normalized state snapshot.

func (*ConnectivityCoordinator) ApplyOnlineState

func (parseCoordinator *ConnectivityCoordinator) ApplyOnlineState(isParseOnline bool) ConnectivityState

ApplyOnlineState updates only online-state and emits one normalized state snapshot.

func (*ConnectivityCoordinator) ApplyState

func (parseCoordinator *ConnectivityCoordinator) ApplyState(parseNextState ConnectivityState) ConnectivityState

ApplyState updates coordinator state and broadcasts hooks when values change.

func (*ConnectivityCoordinator) ApplyTunnelState

func (parseCoordinator *ConnectivityCoordinator) ApplyTunnelState(isParseTunnelReady bool) ConnectivityState

ApplyTunnelState updates only tunnel-readiness state and emits one normalized state snapshot.

func (*ConnectivityCoordinator) DeleteHook

func (parseCoordinator *ConnectivityCoordinator) DeleteHook(parseHookKey string)

DeleteHook removes one named connectivity state hook.

func (*ConnectivityCoordinator) GetState

func (parseCoordinator *ConnectivityCoordinator) GetState() ConnectivityState

GetState returns one snapshot of current connectivity state.

func (*ConnectivityCoordinator) SetHook

func (parseCoordinator *ConnectivityCoordinator) SetHook(parseHookKey string, parseHook ConnectivityHook)

SetHook registers one named connectivity state hook.

func (*ConnectivityCoordinator) ShouldFlushOutbox

func (parseCoordinator *ConnectivityCoordinator) ShouldFlushOutbox() bool

ShouldFlushOutbox reports whether outbox flush work is currently allowed.

func (*ConnectivityCoordinator) ShouldRunBackgroundRefresh

func (parseCoordinator *ConnectivityCoordinator) ShouldRunBackgroundRefresh() bool

ShouldRunBackgroundRefresh reports whether background refresh work is currently allowed.

type ConnectivityHook

type ConnectivityHook func(ConnectivityState)

ConnectivityHook handles one connectivity state transition.

type ConnectivityState

type ConnectivityState struct {
	IsOnline      bool
	IsTunnelReady bool
	IsAppActive   bool
	UpdatedAt     string
}

ConnectivityState stores connectivity and app-lifecycle readiness inputs.

type FlushOperation

type FlushOperation string

FlushOperation identifies one worker-eligible flush operation category.

type FreshnessState

type FreshnessState string

FreshnessState describes one record freshness decision at read time.

const (
	FreshnessMissing FreshnessState = "missing"
	FreshnessFresh   FreshnessState = "fresh"
	FreshnessStale   FreshnessState = "stale"
	FreshnessExpired FreshnessState = "expired"
)

func ResolveFreshnessState

func ResolveFreshnessState(parseRecord CacheRecordEnvelope, parseNow time.Time) FreshnessState

ResolveFreshnessState resolves one freshness state from one record envelope and one read timestamp.

type InMemoryObservabilitySink

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

InMemoryObservabilitySink stores emitted events for tests and diagnostics.

func BuildInMemoryObservabilitySink

func BuildInMemoryObservabilitySink() *InMemoryObservabilitySink

BuildInMemoryObservabilitySink creates one in-memory sink for testing.

func (*InMemoryObservabilitySink) Emit

func (parseSink *InMemoryObservabilitySink) Emit(parseCtx context.Context, parseEvent ObservabilityEvent)

Emit appends one normalized event to in-memory sink state.

func (*InMemoryObservabilitySink) List

func (parseSink *InMemoryObservabilitySink) List() []ObservabilityEvent

List returns one snapshot of emitted in-memory events.

type InvalidationEngine

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

InvalidationEngine applies reason-based cache eviction/downgrade behavior.

func BuildInvalidationEngine

func BuildInvalidationEngine(parseStorage Storage, parseInvalidator *Invalidator) *InvalidationEngine

BuildInvalidationEngine creates one invalidation engine bound to storage and hook dispatcher.

func (*InvalidationEngine) ApplyInvalidation

func (parseEngine *InvalidationEngine) ApplyInvalidation(parseCtx context.Context, parseEvent InvalidationEvent) (int, error)

ApplyInvalidation applies one reason-based invalidation event and returns affected-record count.

type InvalidationEvent

type InvalidationEvent struct {
	Reason         string
	ScopePrefix    string
	ResourcePrefix string
	TriggeredAt    string
}

InvalidationEvent stores one cache invalidation trigger payload.

type InvalidationHook

type InvalidationHook func(InvalidationEvent)

InvalidationHook handles one invalidation event notification.

type Invalidator

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

Invalidator stores named invalidation subscribers for cache and outbox consumers.

func BuildInvalidator

func BuildInvalidator() *Invalidator

BuildInvalidator creates one invalidation dispatcher.

func (*Invalidator) ApplyInvalidation

func (parseInvalidator *Invalidator) ApplyInvalidation(parseEvent InvalidationEvent)

ApplyInvalidation broadcasts one invalidation event to registered hooks.

func (*Invalidator) DeleteHook

func (parseInvalidator *Invalidator) DeleteHook(parseHookKey string)

DeleteHook removes one named invalidation hook.

func (*Invalidator) SetHook

func (parseInvalidator *Invalidator) SetHook(parseHookKey string, parseHook InvalidationHook)

SetHook registers one named invalidation hook.

type MemoryStorage

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

MemoryStorage stores cache/outbox records in-process for tests and non-persistent runtimes.

func BuildMemoryStorage

func BuildMemoryStorage() *MemoryStorage

BuildMemoryStorage creates one in-memory cache/outbox storage implementation.

func (*MemoryStorage) Delete

func (parseStorage *MemoryStorage) Delete(parseCtx context.Context, parseScopedResourceKey string) error

Delete removes one cache record by scoped resource key.

func (*MemoryStorage) DeleteByPrefix

func (parseStorage *MemoryStorage) DeleteByPrefix(parseCtx context.Context, parseScopePrefix string) (int, error)

DeleteByPrefix removes all cache records matching one scoped-prefix filter.

func (*MemoryStorage) Get

func (parseStorage *MemoryStorage) Get(parseCtx context.Context, parseScopedResourceKey string) (CacheRecordEnvelope, bool, error)

Get returns one cache record by scoped resource key.

func (*MemoryStorage) List

func (parseStorage *MemoryStorage) List(parseCtx context.Context, parseScopePrefix string) ([]CacheRecordEnvelope, error)

List returns all cache records matching one scope-prefix filter.

func (*MemoryStorage) Set

func (parseStorage *MemoryStorage) Set(parseCtx context.Context, parseRecord CacheRecordEnvelope) error

Set stores one normalized cache record.

func (*MemoryStorage) UpdateQueueAtomic

func (parseStorage *MemoryStorage) UpdateQueueAtomic(parseCtx context.Context, parseQueueKey string, parseMutate func([]OutboxRecordEnvelope) ([]OutboxRecordEnvelope, error)) ([]OutboxRecordEnvelope, error)

UpdateQueueAtomic applies one atomic queue mutation and returns the final queue snapshot.

type ObservabilityEmitter

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

ObservabilityEmitter emits normalized observability events to one sink.

func BuildObservabilityEmitter

func BuildObservabilityEmitter(parseSink ObservabilitySink) *ObservabilityEmitter

BuildObservabilityEmitter creates one event emitter bound to one sink.

func (*ObservabilityEmitter) Emit

func (parseEmitter *ObservabilityEmitter) Emit(parseCtx context.Context, parseEvent ObservabilityEvent)

Emit sends one normalized observability event to the configured sink.

type ObservabilityEvent

type ObservabilityEvent struct {
	EventType    ObservabilityEventType
	ScopeKey     string
	ResourceKey  string
	QueueKey     string
	Reason       string
	ErrorCode    string
	AttemptCount int
	IsStale      bool
	EmittedAt    string
}

ObservabilityEvent stores one payload-safe diagnostics event.

type ObservabilityEventType

type ObservabilityEventType string

ObservabilityEventType identifies one cache/outbox lifecycle telemetry event.

const (
	ObservabilityEventCacheHit         ObservabilityEventType = "cache_hit"
	ObservabilityEventCacheMiss        ObservabilityEventType = "cache_miss"
	ObservabilityEventCacheStaleReturn ObservabilityEventType = "cache_stale_return"
	ObservabilityEventRefreshStart     ObservabilityEventType = "refresh_start"
	ObservabilityEventRefreshFailure   ObservabilityEventType = "refresh_failure"
	ObservabilityEventQueueEnqueue     ObservabilityEventType = "queue_enqueue"
	ObservabilityEventQueueAck         ObservabilityEventType = "queue_ack"
	ObservabilityEventQueueDrop        ObservabilityEventType = "queue_drop"
	ObservabilityEventEviction         ObservabilityEventType = "eviction"
)

type ObservabilitySink

type ObservabilitySink interface {
	Emit(context.Context, ObservabilityEvent)
}

ObservabilitySink receives payload-safe observability events.

type OutboxRecordEnvelope

type OutboxRecordEnvelope struct {
	QueueKey      string `json:"queue_key"`
	ResourceKey   string `json:"resource_key"`
	OperationKey  string `json:"operation_key"`
	CreatedAt     string `json:"created_at"`
	LastAttemptAt string `json:"last_attempt_at"`
	AttemptCount  int    `json:"attempt_count"`
	NextRetryAt   string `json:"next_retry_at"`
	Payload       []byte `json:"parsePayload"`
	Status        string `json:"parseStatus"`
	AckKey        string `json:"parseAckKey"`
	LastError     string `json:"parseLastError"`
}

OutboxRecordEnvelope stores one queued-write row for retryable mutation delivery.

func BuildOutboxRecordEnvelope

func BuildOutboxRecordEnvelope(
	parseQueueKey string,
	parseResourceKey string,
	parseOperationKey string,
	parseCreatedAt time.Time,
	parseNextRetryAt time.Time,
	parsePayload []byte,
	parseStatus string,
	parseAckKey string,
	parseLastError string,
) OutboxRecordEnvelope

BuildOutboxRecordEnvelope builds one canonical queued-write envelope for retry orchestration.

func NormalizeOutboxRecordEnvelope

func NormalizeOutboxRecordEnvelope(parseRecord OutboxRecordEnvelope) OutboxRecordEnvelope

NormalizeOutboxRecordEnvelope normalizes one outbox envelope into one canonical contract-safe shape.

func ParseOutboxRecordEnvelopeJSON

func ParseOutboxRecordEnvelopeJSON(parseRaw []byte) (OutboxRecordEnvelope, error)

ParseOutboxRecordEnvelopeJSON unmarshals one persisted outbox-record envelope JSON payload.

type OutboxRetryPolicy

type OutboxRetryPolicy struct {
	InitialDelay time.Duration
	MaxDelay     time.Duration
	JitterRatio  float64
	MaxAttempts  int
}

OutboxRetryPolicy stores retry-engine controls for queued-write delivery.

func BuildOutboxRetryPolicyDefaults

func BuildOutboxRetryPolicyDefaults() OutboxRetryPolicy

BuildOutboxRetryPolicyDefaults returns one conservative retry policy for queued writes.

func NormalizeOutboxRetryPolicy

func NormalizeOutboxRetryPolicy(parsePolicy OutboxRetryPolicy) OutboxRetryPolicy

NormalizeOutboxRetryPolicy normalizes retry policy bounds.

type OwnershipActor

type OwnershipActor string

OwnershipActor identifies whether work belongs to the main thread or background worker.

const (
	OwnershipActorMainThread OwnershipActor = "main_thread"
	OwnershipActorWorker     OwnershipActor = "background_worker"
)

type OwnershipDecision

type OwnershipDecision struct {
	Actor  OwnershipActor
	Reason string
}

OwnershipDecision stores one ownership rule resolution.

func ResolveOwnershipDecision

func ResolveOwnershipDecision(parseTask OwnershipTask) OwnershipDecision

ResolveOwnershipDecision resolves one canonical ownership actor for one cache/outbox task.

type OwnershipTask

type OwnershipTask string

OwnershipTask identifies cache/outbox lifecycle responsibilities.

const (
	OwnershipTaskHotRead           OwnershipTask = "hot_ui_read"
	OwnershipTaskOptimisticState   OwnershipTask = "optimistic_state"
	OwnershipTaskInvalidationSweep OwnershipTask = "invalidation_sweep"
	OwnershipTaskTTLScan           OwnershipTask = "ttl_scan"
	OwnershipTaskRetryScheduling   OwnershipTask = "retry_scheduling"
	OwnershipTaskQueuedLogFlush    OwnershipTask = "queued_log_flush"
	OwnershipTaskUnsentResend      OwnershipTask = "unsent_message_resend"
)

type PolicyClass

type PolicyClass string

PolicyClass identifies one cache policy profile category.

const (
	PolicyClassStatic   PolicyClass = "static"
	PolicyClassSession  PolicyClass = "session"
	PolicyClassVolatile PolicyClass = "volatile"
	PolicyClassQueued   PolicyClass = "queued"
)

type PolicyReadDecision

type PolicyReadDecision struct {
	CanReturnCached             bool
	IsStale                     bool
	ShouldRefreshInBackground   bool
	ShouldRefetchBeforeMutation bool
}

PolicyReadDecision describes one read-path decision after applying one cache policy.

func ResolvePolicyReadDecision

func ResolvePolicyReadDecision(parsePolicy CachePolicy, parseState FreshnessState) PolicyReadDecision

ResolvePolicyReadDecision applies one cache policy to one freshness state.

type QueuedMutationView

type QueuedMutationView struct {
	QueueKey     string
	PendingCount int
	NextRetryAt  string
	IsPending    bool
}

QueuedMutationView stores UI-facing queue-state metadata.

type RetryDecision

type RetryDecision struct {
	ShouldRetry bool
	IsTerminal  bool
	NextRecord  OutboxRecordEnvelope
}

RetryDecision stores retry/terminal outcomes for one queued-write attempt.

func ResolveOutboxRetryDecision

func ResolveOutboxRetryDecision(parseRecord OutboxRecordEnvelope, parseNow time.Time, parsePolicy OutboxRetryPolicy, parseRandomFloat func() float64) RetryDecision

ResolveOutboxRetryDecision applies retry policy to one outbox record and returns the next retry decision.

type SWRCoordinator

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

SWRCoordinator coordinates stale-while-revalidate refresh de-duplication.

func BuildSWRCoordinator

func BuildSWRCoordinator() *SWRCoordinator

BuildSWRCoordinator creates one stale-while-revalidate refresh coordinator.

func (*SWRCoordinator) StartRefresh

func (parseCoordinator *SWRCoordinator) StartRefresh(parseScopeKey string, parseResourceKey string) (func(), bool)

StartRefresh registers one refresh key and returns one release callback when start succeeds.

type SWRReadResult

type SWRReadResult struct {
	Record           CacheRecordEnvelope
	IsFound          bool
	IsCached         bool
	IsStale          bool
	Freshness        FreshnessState
	RefreshTriggered bool
}

SWRReadResult stores one stale-while-revalidate read result and metadata.

func ReadWithSWR

func ReadWithSWR(
	parseCtx context.Context,
	parseStorage Storage,
	parseCoordinator *SWRCoordinator,
	parsePolicy CachePolicy,
	parseScopeKey string,
	parseResourceKey string,
	parseRefresh func(context.Context, string, string) (CacheRecordEnvelope, error),
) (SWRReadResult, error)

ReadWithSWR reads one scoped resource from cache and triggers one background refresh when policy allows.

type ScopeKey

type ScopeKey struct {
	AppVersion string
	SessionID  string
	UserID     string
	Workspace  string
	Locale     string
	RouteKey   string
	ThreadKey  string
}

ScopeKey stores domain-agnostic scope dimensions for cache isolation.

type SecurityDecision

type SecurityDecision struct {
	IsAllowed                      bool
	IsDisplayOnly                  bool
	IsQueueWriteAllowed            bool
	MustUseServerAuthorizationGate bool
	Reason                         string
}

SecurityDecision stores one evaluated decision for one resource+intent.

func ResolveSecurityDecision

func ResolveSecurityDecision(parseResourceKey string, parseIntent SecurityIntent, parseRules []SecurityRule) SecurityDecision

ResolveSecurityDecision evaluates cache security behavior for one resource and intent.

type SecurityIntent

type SecurityIntent string

SecurityIntent identifies one cache action under security policy evaluation.

const (
	SecurityIntentDisplayRead SecurityIntent = "display_read"
	SecurityIntentCacheWrite  SecurityIntent = "cache_write"
	SecurityIntentQueueWrite  SecurityIntent = "queue_write"
)

type SecurityRule

type SecurityRule struct {
	ResourcePrefix                 string
	IsDisplayOnly                  bool
	IsQueueWriteAllowed            bool
	MustUseServerAuthorizationGate bool
}

SecurityRule stores one resource-prefix security rule.

func BuildDefaultSecurityRules

func BuildDefaultSecurityRules() []SecurityRule

BuildDefaultSecurityRules returns default security rules for sensitive display-only resources.

type SnapshotStore

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

SnapshotStore stores one main-thread mirror of cache records for synchronous render reads.

func BuildSnapshotStore

func BuildSnapshotStore() *SnapshotStore

BuildSnapshotStore creates one main-thread snapshot store.

func (*SnapshotStore) ApplyFromStorage

func (parseStore *SnapshotStore) ApplyFromStorage(parseCtx context.Context, parseStorage Storage, parseScopePrefix string) error

ApplyFromStorage mirrors records from one storage implementation into snapshot state.

func (*SnapshotStore) DeleteSync

func (parseStore *SnapshotStore) DeleteSync(parseScopeKey string, parseResourceKey string)

DeleteSync removes one mirrored cache record synchronously.

func (*SnapshotStore) GetSync

func (parseStore *SnapshotStore) GetSync(parseScopeKey string, parseResourceKey string) (CacheRecordEnvelope, bool)

GetSync returns one mirrored cache record synchronously for one scoped resource key.

func (*SnapshotStore) ListSync

func (parseStore *SnapshotStore) ListSync(parseScopePrefix string) []CacheRecordEnvelope

ListSync returns one snapshot list for one scope prefix synchronously.

func (*SnapshotStore) SetSync

func (parseStore *SnapshotStore) SetSync(parseRecord CacheRecordEnvelope)

SetSync writes one mirrored cache record synchronously.

type Storage

type Storage interface {
	Get(parseCtx context.Context, parseScopedResourceKey string) (CacheRecordEnvelope, bool, error)
	List(parseCtx context.Context, parseScopePrefix string) ([]CacheRecordEnvelope, error)
	Set(parseCtx context.Context, parseRecord CacheRecordEnvelope) error
	Delete(parseCtx context.Context, parseScopedResourceKey string) error
	DeleteByPrefix(parseCtx context.Context, parseScopePrefix string) (int, error)
	UpdateQueueAtomic(parseCtx context.Context, parseQueueKey string, parseMutate func([]OutboxRecordEnvelope) ([]OutboxRecordEnvelope, error)) ([]OutboxRecordEnvelope, error)
}

Storage defines the shared cache/outbox persistence contract for client runtimes.

type UIAPI

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

UIAPI provides reusable UI-facing cache/outbox helpers over core runtime primitives.

func BuildUIAPI

func BuildUIAPI(parseStorage Storage, parseCoordinator *SWRCoordinator, parseInvalidation *InvalidationEngine) *UIAPI

BuildUIAPI creates one UI helper API wrapper for cache-core primitives.

func BuildUIAPIWithSnapshot

func BuildUIAPIWithSnapshot(parseStorage Storage, parseSnapshot *SnapshotStore, parseCoordinator *SWRCoordinator, parseInvalidation *InvalidationEngine) *UIAPI

BuildUIAPIWithSnapshot creates one UI helper API wrapper with one main-thread snapshot mirror for render-safe reads.

func (*UIAPI) ApplyOptimisticPatch

func (parseAPI *UIAPI) ApplyOptimisticPatch(
	parseCtx context.Context,
	parseScopeKey string,
	parseResourceKey string,
	parsePatch func(CacheRecordEnvelope) CacheRecordEnvelope,
) error

ApplyOptimisticPatch reads one resource and writes one patched optimistic snapshot.

func (*UIAPI) InvalidateResources

func (parseAPI *UIAPI) InvalidateResources(parseCtx context.Context, parseReason string, parseScopePrefix string, parseResourcePrefix string) (int, error)

InvalidateResources triggers reason-based invalidation through the configured engine.

func (*UIAPI) ReadCachedResource

func (parseAPI *UIAPI) ReadCachedResource(
	parseCtx context.Context,
	parseScopeKey string,
	parseResourceKey string,
	parsePolicy CachePolicy,
	parseRefresh func(context.Context, string, string) (CacheRecordEnvelope, error),
) (CachedResourceView, error)

ReadCachedResource reads one cached resource with stale-while-revalidate semantics.

func (*UIAPI) ReadQueuedMutationState

func (parseAPI *UIAPI) ReadQueuedMutationState(parseCtx context.Context, parseQueueKey string) (QueuedMutationView, error)

ReadQueuedMutationState reads one queued mutation status snapshot for one queue key.

func (*UIAPI) RefreshResource

func (parseAPI *UIAPI) RefreshResource(
	parseCtx context.Context,
	parseScopeKey string,
	parseResourceKey string,
	parseRefresh func(context.Context, string, string) (CacheRecordEnvelope, error),
) error

RefreshResource forces one authoritative refresh and stores the returned cache record.

func (*UIAPI) SetSnapshotStore

func (parseAPI *UIAPI) SetSnapshotStore(parseSnapshot *SnapshotStore)

SetSnapshotStore sets one main-thread snapshot mirror for render-safe cached reads.

type WorkerBatchRule

type WorkerBatchRule struct {
	MaxDeltasPerBatch int
}

WorkerBatchRule defines one deterministic worker communication batching policy.

type WorkerBatcher

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

WorkerBatcher batches worker-maintenance deltas before cross-thread transfer.

func BuildWorkerBatcher

func BuildWorkerBatcher(parseRule WorkerBatchRule) *WorkerBatcher

BuildWorkerBatcher creates one worker batching controller.

func (*WorkerBatcher) ApplyDelta

func (parseBatcher *WorkerBatcher) ApplyDelta(parseDelta WorkerDelta)

ApplyDelta appends one normalized maintenance delta into pending batching state.

func (*WorkerBatcher) GetBatches

func (parseBatcher *WorkerBatcher) GetBatches() []WorkerMessageBatch

GetBatches returns grouped/chunked worker deltas and clears pending state.

type WorkerDelta

type WorkerDelta struct {
	DeltaType    WorkerDeltaType
	ScopeKey     string
	ResourceKey  string
	QueueKey     string
	OperationKey string
	Reason       string
	UpdatedAt    string
}

WorkerDelta stores one payload-agnostic maintenance delta.

type WorkerDeltaType

type WorkerDeltaType string

WorkerDeltaType identifies one worker-maintenance delta class.

const (
	WorkerDeltaInvalidationScan WorkerDeltaType = "invalidation_scan"
	WorkerDeltaQueueFlush       WorkerDeltaType = "queue_flush"
	WorkerDeltaBackgroundWrite  WorkerDeltaType = "background_write"
)

type WorkerEvent

type WorkerEvent struct {
	EventType    WorkerEventType
	ScopeKey     string
	ResourceKey  string
	QueueKey     string
	OperationKey string
	Reason       string
	ErrorCode    string
	UpdatedAt    string
}

WorkerEvent stores one payload-agnostic maintenance event.

type WorkerEventBus

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

WorkerEventBus provides one in-process worker event contract implementation.

func BuildWorkerEventBus

func BuildWorkerEventBus() *WorkerEventBus

BuildWorkerEventBus creates one worker event bus.

func (*WorkerEventBus) Publish

func (parseBus *WorkerEventBus) Publish(parseCtx context.Context, parseEvent WorkerEvent)

Publish emits one normalized worker event to all subscribers.

func (*WorkerEventBus) Subscribe

func (parseBus *WorkerEventBus) Subscribe(parseHandlerKey string, parseHandler WorkerEventHandler)

Subscribe registers one named worker event handler.

func (*WorkerEventBus) Unsubscribe

func (parseBus *WorkerEventBus) Unsubscribe(parseHandlerKey string)

Unsubscribe removes one named worker event handler.

type WorkerEventContract

type WorkerEventContract interface {
	Publish(context.Context, WorkerEvent)
	Subscribe(string, WorkerEventHandler)
	Unsubscribe(string)
}

WorkerEventContract defines the worker event publish/subscribe API.

type WorkerEventHandler

type WorkerEventHandler func(context.Context, WorkerEvent)

WorkerEventHandler handles one worker maintenance event callback.

type WorkerEventType

type WorkerEventType string

WorkerEventType identifies one worker-to-main cache/outbox maintenance signal.

const (
	WorkerEventUpdated        WorkerEventType = "updated"
	WorkerEventStale          WorkerEventType = "stale"
	WorkerEventRefreshing     WorkerEventType = "refreshing"
	WorkerEventAcked          WorkerEventType = "acked"
	WorkerEventRetryScheduled WorkerEventType = "retry_scheduled"
	WorkerEventFailed         WorkerEventType = "failed"
	WorkerEventEvicted        WorkerEventType = "evicted"
)

type WorkerFlushContract

type WorkerFlushContract interface {
	Enqueue(context.Context, WorkerFlushTask) error
	DequeueBatch(context.Context, int) ([]WorkerFlushTask, error)
	Ack(context.Context, []string) error
}

WorkerFlushContract defines a worker-friendly flush queue API.

type WorkerFlushQueue

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

WorkerFlushQueue provides one in-process implementation of WorkerFlushContract.

func BuildWorkerFlushQueue

func BuildWorkerFlushQueue() *WorkerFlushQueue

BuildWorkerFlushQueue creates one worker-friendly in-memory flush queue.

func (*WorkerFlushQueue) Ack

func (parseQueue *WorkerFlushQueue) Ack(parseCtx context.Context, parseTaskKeys []string) error

Ack removes tasks that match one or more acknowledged task keys.

func (*WorkerFlushQueue) DequeueBatch

func (parseQueue *WorkerFlushQueue) DequeueBatch(parseCtx context.Context, parseMaxTasks int) ([]WorkerFlushTask, error)

DequeueBatch returns up to one batch of pending flush tasks without removing them.

func (*WorkerFlushQueue) Enqueue

func (parseQueue *WorkerFlushQueue) Enqueue(parseCtx context.Context, parseTask WorkerFlushTask) error

Enqueue appends one normalized flush task.

type WorkerFlushTask

type WorkerFlushTask struct {
	TaskKey   string
	Operation FlushOperation
	ScopeKey  string
	QueueKey  string
	Payload   []byte
	CreatedAt string
}

WorkerFlushTask stores one worker-friendly flush request envelope.

func BuildWorkerFlushTask

func BuildWorkerFlushTask(parseTaskKey string, parseOperation FlushOperation, parseScopeKey string, parseQueueKey string, parsePayload []byte) WorkerFlushTask

BuildWorkerFlushTask builds one normalized worker flush task.

type WorkerMessageBatch

type WorkerMessageBatch struct {
	BatchType WorkerDeltaType
	ScopeKey  string
	QueueKey  string
	BatchedAt string
	Deltas    []WorkerDelta
}

WorkerMessageBatch stores one grouped worker-maintenance delta batch.

type WorkerSnapshotReconcileInput

type WorkerSnapshotReconcileInput struct {
	Event                    WorkerEvent
	Record                   CacheRecordEnvelope
	AckQueueKey              string
	AckKey                   string
	AckOperationKey          string
	InvalidatedScopedRecords []string
}

WorkerSnapshotReconcileInput describes one worker->snapshot reconciliation update.

type WorkerSnapshotReconcileResult

type WorkerSnapshotReconcileResult struct {
	IsApplied         bool
	IsDuplicate       bool
	IsOutOfOrder      bool
	IsRecordUpdated   bool
	DeletedCount      int
	QueueRemovedCount int
}

WorkerSnapshotReconcileResult describes one reconciliation application outcome.

type WorkerSnapshotReconciler

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

WorkerSnapshotReconciler merges worker maintenance results into storage plus snapshot state deterministically.

func BuildWorkerSnapshotReconciler

func BuildWorkerSnapshotReconciler(parseStorage Storage, parseSnapshot *SnapshotStore) *WorkerSnapshotReconciler

BuildWorkerSnapshotReconciler creates one deterministic worker->snapshot reconciliation path.

func (*WorkerSnapshotReconciler) ApplyEvent

func (parseReconciler *WorkerSnapshotReconciler) ApplyEvent(parseCtx context.Context, parseInput WorkerSnapshotReconcileInput) (WorkerSnapshotReconcileResult, error)

ApplyEvent applies one worker maintenance result into storage plus snapshot state.

Jump to

Keyboard shortcuts

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