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
- func BuildCacheRecordEnvelopeJSON(parseRecord CacheRecordEnvelope) ([]byte, error)
- func BuildFreshnessWindow(parseFetchedAt time.Time, parseStaleAfter time.Duration, ...) (string, string, string)
- func BuildOutboxRecordEnvelopeJSON(parseRecord OutboxRecordEnvelope) ([]byte, error)
- func BuildScopeKey(parseScope ScopeKey) string
- func BuildScopePrefixForAccountSwitch(parseScope ScopeKey) string
- func BuildScopePrefixForLocaleSwitch(parseScope ScopeKey) string
- func BuildScopePrefixForLogout(parseScope ScopeKey) string
- func BuildScopePrefixForWorkspaceSwitch(parseScope ScopeKey) string
- func BuildScopedResourceKey(parseScopeKey string, parseResourceKey string) string
- func EnforceLocalSecrecyForCacheRecord(parseRecord CacheRecordEnvelope) error
- func EnforceLocalSecrecyForOutboxRecord(parseRecord OutboxRecordEnvelope) error
- func EnforceSecurityDecision(parseDecision SecurityDecision) error
- type AckReconcileInput
- type AckReconcileResult
- type BrowserStorage
- type CachePolicy
- type CacheRecordEnvelope
- type CachedResourceView
- type ConnectivityCoordinator
- func (parseCoordinator *ConnectivityCoordinator) ApplyAppActiveState(isParseAppActive bool) ConnectivityState
- func (parseCoordinator *ConnectivityCoordinator) ApplyOnlineState(isParseOnline bool) ConnectivityState
- func (parseCoordinator *ConnectivityCoordinator) ApplyState(parseNextState ConnectivityState) ConnectivityState
- func (parseCoordinator *ConnectivityCoordinator) ApplyTunnelState(isParseTunnelReady bool) ConnectivityState
- func (parseCoordinator *ConnectivityCoordinator) DeleteHook(parseHookKey string)
- func (parseCoordinator *ConnectivityCoordinator) GetState() ConnectivityState
- func (parseCoordinator *ConnectivityCoordinator) SetHook(parseHookKey string, parseHook ConnectivityHook)
- func (parseCoordinator *ConnectivityCoordinator) ShouldFlushOutbox() bool
- func (parseCoordinator *ConnectivityCoordinator) ShouldRunBackgroundRefresh() bool
- type ConnectivityHook
- type ConnectivityState
- type FlushOperation
- type FreshnessState
- type InMemoryObservabilitySink
- type InvalidationEngine
- type InvalidationEvent
- type InvalidationHook
- type Invalidator
- type MemoryStorage
- func (parseStorage *MemoryStorage) Delete(parseCtx context.Context, parseScopedResourceKey string) error
- func (parseStorage *MemoryStorage) DeleteByPrefix(parseCtx context.Context, parseScopePrefix string) (int, error)
- func (parseStorage *MemoryStorage) Get(parseCtx context.Context, parseScopedResourceKey string) (CacheRecordEnvelope, bool, error)
- func (parseStorage *MemoryStorage) List(parseCtx context.Context, parseScopePrefix string) ([]CacheRecordEnvelope, error)
- func (parseStorage *MemoryStorage) Set(parseCtx context.Context, parseRecord CacheRecordEnvelope) error
- func (parseStorage *MemoryStorage) UpdateQueueAtomic(parseCtx context.Context, parseQueueKey string, ...) ([]OutboxRecordEnvelope, error)
- type ObservabilityEmitter
- type ObservabilityEvent
- type ObservabilityEventType
- type ObservabilitySink
- type OutboxRecordEnvelope
- func BuildOutboxRecordEnvelope(parseQueueKey string, parseResourceKey string, parseOperationKey string, ...) OutboxRecordEnvelope
- func NormalizeOutboxRecordEnvelope(parseRecord OutboxRecordEnvelope) OutboxRecordEnvelope
- func ParseOutboxRecordEnvelopeJSON(parseRaw []byte) (OutboxRecordEnvelope, error)
- type OutboxRetryPolicy
- type OwnershipActor
- type OwnershipDecision
- type OwnershipTask
- type PolicyClass
- type PolicyReadDecision
- type QueuedMutationView
- type RetryDecision
- type SWRCoordinator
- type SWRReadResult
- type ScopeKey
- type SecurityDecision
- type SecurityIntent
- type SecurityRule
- type SnapshotStore
- func (parseStore *SnapshotStore) ApplyFromStorage(parseCtx context.Context, parseStorage Storage, parseScopePrefix string) error
- func (parseStore *SnapshotStore) DeleteSync(parseScopeKey string, parseResourceKey string)
- func (parseStore *SnapshotStore) GetSync(parseScopeKey string, parseResourceKey string) (CacheRecordEnvelope, bool)
- func (parseStore *SnapshotStore) ListSync(parseScopePrefix string) []CacheRecordEnvelope
- func (parseStore *SnapshotStore) SetSync(parseRecord CacheRecordEnvelope)
- type Storage
- type UIAPI
- func (parseAPI *UIAPI) ApplyOptimisticPatch(parseCtx context.Context, parseScopeKey string, parseResourceKey string, ...) error
- func (parseAPI *UIAPI) InvalidateResources(parseCtx context.Context, parseReason string, parseScopePrefix string, ...) (int, error)
- func (parseAPI *UIAPI) ReadCachedResource(parseCtx context.Context, parseScopeKey string, parseResourceKey string, ...) (CachedResourceView, error)
- func (parseAPI *UIAPI) ReadQueuedMutationState(parseCtx context.Context, parseQueueKey string) (QueuedMutationView, error)
- func (parseAPI *UIAPI) RefreshResource(parseCtx context.Context, parseScopeKey string, parseResourceKey string, ...) error
- func (parseAPI *UIAPI) SetSnapshotStore(parseSnapshot *SnapshotStore)
- type WorkerBatchRule
- type WorkerBatcher
- type WorkerDelta
- type WorkerDeltaType
- type WorkerEvent
- type WorkerEventBus
- type WorkerEventContract
- type WorkerEventHandler
- type WorkerEventType
- type WorkerFlushContract
- type WorkerFlushQueue
- func (parseQueue *WorkerFlushQueue) Ack(parseCtx context.Context, parseTaskKeys []string) error
- func (parseQueue *WorkerFlushQueue) DequeueBatch(parseCtx context.Context, parseMaxTasks int) ([]WorkerFlushTask, error)
- func (parseQueue *WorkerFlushQueue) Enqueue(parseCtx context.Context, parseTask WorkerFlushTask) error
- type WorkerFlushTask
- type WorkerMessageBatch
- type WorkerSnapshotReconcileInput
- type WorkerSnapshotReconcileResult
- type WorkerSnapshotReconciler
Constants ¶
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" )
const ( CacheStatusReady = "ready" CacheStatusStale = "stale" CacheStatusError = "error" )
const ( OutboxStatusQueued = "queued" OutboxStatusSending = "sending" OutboxStatusAcked = "acked" OutboxStatusFailed = "failed" )
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 ¶
BuildScopeKey formats one stable scope key for cache and outbox records.
func BuildScopePrefixForAccountSwitch ¶
BuildScopePrefixForAccountSwitch returns one deterministic scope prefix for account-switch eviction.
func BuildScopePrefixForLocaleSwitch ¶
BuildScopePrefixForLocaleSwitch returns one deterministic scope prefix for locale-switch eviction.
func BuildScopePrefixForLogout ¶
BuildScopePrefixForLogout returns one deterministic scope prefix for logout/session-eviction events.
func BuildScopePrefixForWorkspaceSwitch ¶
BuildScopePrefixForWorkspaceSwitch returns one deterministic scope prefix for workspace-switch eviction.
func BuildScopedResourceKey ¶
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 ¶
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{}
BrowserStorage is unavailable outside js/wasm builds.
func BuildBrowserStorage ¶
func BuildBrowserStorage() (*BrowserStorage, error)
BuildBrowserStorage returns one unsupported error outside browser runtimes.
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.
Source Files
¶
- connectivity.go
- coordinator.go
- doc.go
- freshness.go
- invalidation_engine.go
- key.go
- observability.go
- ownership_rules.go
- policy.go
- reconcile.go
- record.go
- retry.go
- secrecy_rules.go
- security_rules.go
- snapshot_store.go
- storage.go
- storage_browser_stub.go
- swr.go
- ui_api.go
- worker_batching.go
- worker_contract.go
- worker_events.go
- worker_reconciliation.go