Documentation
¶
Overview ¶
Package autosync implements a lease-guarded background sync manager for Engram's local-first cloud replication.
The manager runs in long-lived local processes (serve, mcp) and:
- Acquires a SQLite-backed lease to prevent duplicate workers.
- Pushes pending local mutations to the cloud server.
- Pulls remote mutations by cursor and applies them locally.
- Supports debounced wake on dirty state and periodic freshness checks.
- Uses exponential backoff with jitter on failures, bounded by max retries.
- Tracks degraded state (phase, last error, backoff timing).
- Shuts down gracefully via context cancellation.
Index ¶
Constants ¶
const ( PhaseIdle = "idle" PhasePushing = "pushing" PhasePulling = "pulling" PhasePushFailed = "push_failed" PhasePullFailed = "pull_failed" PhaseBackoff = "backoff" PhaseHealthy = "healthy" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CloudTransport ¶
type CloudTransport interface {
PushMutations(mutations []remote.MutationEntry) (*remote.PushMutationsResult, error)
PullMutations(sinceSeq int64, limit int) (*remote.PullMutationsResponse, error)
}
CloudTransport is the subset of remote.RemoteTransport methods the manager needs.
type Config ¶
type Config struct {
TargetKey string // sync_state target key (default: "cloud")
LeaseOwner string // unique owner identity for lease
LeaseInterval time.Duration // how long to hold the lease each cycle
DebounceDuration time.Duration // debounce window for dirty notifications
PollInterval time.Duration // periodic freshness check while idle
PushBatchSize int // max mutations per push request
PullBatchSize int // max mutations per pull request
MaxConsecutiveFailures int // stop retrying after this many consecutive failures
BaseBackoff time.Duration // base duration for exponential backoff
MaxBackoff time.Duration // ceiling for backoff duration
}
Config holds tuning parameters for the background sync manager.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns sensible production defaults.
type LocalStore ¶
type LocalStore interface {
GetSyncState(targetKey string) (*store.SyncState, error)
ListPendingSyncMutations(targetKey string, limit int) ([]store.SyncMutation, error)
AckSyncMutations(targetKey string, lastAckedSeq int64) error
AckSyncMutationSeqs(targetKey string, seqs []int64) error
SkipAckNonEnrolledMutations(targetKey string) (int64, error)
AcquireSyncLease(targetKey, owner string, ttl time.Duration, now time.Time) (bool, error)
ReleaseSyncLease(targetKey, owner string) error
ApplyPulledMutation(targetKey string, mutation store.SyncMutation) error
MarkSyncFailure(targetKey, message string, backoffUntil time.Time) error
MarkSyncHealthy(targetKey string) error
}
LocalStore is the subset of store.Store methods the manager needs.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager coordinates background push/pull sync between local SQLite and the cloud server. It is safe for concurrent use.
func New ¶
func New(localStore LocalStore, transport CloudTransport, cfg Config) *Manager
New creates a new background sync manager.
func (*Manager) NotifyDirty ¶
func (m *Manager) NotifyDirty()
NotifyDirty signals the manager that local state has changed. Non-blocking; coalesces multiple calls via a buffered channel.
func (*Manager) Run ¶
Run is the main loop. It blocks until the context is cancelled. On shutdown it releases the lease and returns.
func (*Manager) SyncStatus ¶
SyncStatus returns a server-compatible status snapshot. This method satisfies the server.SyncStatusProvider interface via structural typing.
type Status ¶
type Status struct {
Phase string `json:"phase"`
LastError string `json:"last_error,omitempty"`
ConsecutiveFailures int `json:"consecutive_failures"`
BackoffUntil *time.Time `json:"backoff_until,omitempty"`
LastSyncAt *time.Time `json:"last_sync_at,omitempty"`
}
Status represents the current degraded-state snapshot of the manager.
Source Files