sync

package
v0.11.0-beta.1 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: Apache-2.0, MIT Imports: 25 Imported by: 0

Documentation

Overview

Package sync ships local Overkill sessions to a remote backend so the user can switch machines and resume. Three backends are provided:

  • file: copy to a shared filesystem path (NFS, syncthing, dropbox)
  • s3: any S3-compatible bucket (AWS, R2, B2, MinIO)
  • git: push session blobs to a git remote

Sessions are exported as gzipped JSON containing the full Session struct (messages, settings, ledger). Conflict resolution is last-write-wins on UpdatedAt with the loser preserved as `<id>_conflict-<ts>`.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("sync: session not found on backend")

ErrNotFound is returned by Pull/Delete when a session is absent.

Functions

func AutoPushIfEnabled 

func AutoPushIfEnabled(cfg *config.Config, mgr *Manager, sessionID string, logFn func(error))

AutoPushIfEnabled queues the latest persisted state of a session. One worker belongs to each manager; a slow upload cannot silently discard the next turn or prevent a different application's manager from uploading.

func DecodeSession 

func DecodeSession(data []byte) (*session.Session, error)

DecodeSession reverses EncodeSession.

func EncodeSession 

func EncodeSession(s *session.Session) ([]byte, error)

EncodeSession marshals + gzips a session for transport.

func SetPushTimeout 

func SetPushTimeout(sec int)

Types

type Backend 

type Backend interface {
	// Push uploads a single session blob + metadata.
	Push(ctx context.Context, sessionID string, data []byte, meta SessionMeta) error
	// Pull fetches a single session blob + metadata.
	Pull(ctx context.Context, sessionID string) ([]byte, SessionMeta, error)
	// List enumerates all session metadata records on the backend.
	List(ctx context.Context) ([]SessionMeta, error)
	// Delete removes both blob and metadata for a session.
	Delete(ctx context.Context, sessionID string) error
	// Name identifies the backend type (file/s3/git) for status output.
	Name() string
}

Backend is the abstract sync target. All operations should respect the supplied context for cancellation/timeout.

func NewBackend 

func NewBackend(cfg config.SyncConfig) (Backend, error)

NewBackend constructs a Backend from config. Returns (nil, nil) if sync is disabled (cfg.Backend == "").

type FileBackend 

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

FileBackend stores blobs/meta on a shared filesystem path. Each session is two files: <id>.json.gz (blob) and <id>.meta.json (metadata).

func NewFileBackend 

func NewFileBackend(cfg config.SyncFileConfig) (*FileBackend, error)

func (*FileBackend) Delete 

func (f *FileBackend) Delete(ctx context.Context, id string) error

func (*FileBackend) List 

func (f *FileBackend) List(ctx context.Context) ([]SessionMeta, error)

func (*FileBackend) Name 

func (f *FileBackend) Name() string

func (*FileBackend) Pull 

func (f *FileBackend) Pull(ctx context.Context, id string) ([]byte, SessionMeta, error)

func (*FileBackend) Push 

func (f *FileBackend) Push(ctx context.Context, id string, data []byte, meta SessionMeta) error

type GitBackend 

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

GitBackend stores blobs in a local git repo and pushes to a remote on every push. Uses the system `git` binary so we don't pull in go-git.

func NewGitBackend 

func NewGitBackend(cfg config.SyncGitConfig) (*GitBackend, error)

func (*GitBackend) Delete 

func (g *GitBackend) Delete(ctx context.Context, id string) error

func (*GitBackend) List 

func (g *GitBackend) List(ctx context.Context) ([]SessionMeta, error)

func (*GitBackend) Name 

func (g *GitBackend) Name() string

func (*GitBackend) Pull 

func (g *GitBackend) Pull(ctx context.Context, id string) ([]byte, SessionMeta, error)

func (*GitBackend) Push 

func (g *GitBackend) Push(ctx context.Context, id string, data []byte, meta SessionMeta) error

type Manager 

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

Manager couples a session.Store with a Backend and provides high-level push/pull/status operations. All methods are safe for concurrent use.

func NewManager 

func NewManager(store session.Store, backend Backend) *Manager

func (*Manager) Backend 

func (m *Manager) Backend() Backend

Backend exposes the underlying backend (nil when sync is disabled).

func (*Manager) CloseAutoPush 

func (m *Manager) CloseAutoPush(ctx context.Context) error

CloseAutoPush stops admission and drains already queued uploads. On expiry it cancels the worker and joins it before the owner closes its session store. Backends must honor context cancellation, as required by Backend's contract.

func (*Manager) PullAll 

func (m *Manager) PullAll(ctx context.Context) (int, error)

func (*Manager) PullOne 

func (m *Manager) PullOne(ctx context.Context, id string) error

func (*Manager) PushAll 

func (m *Manager) PushAll(ctx context.Context) (int, error)

func (*Manager) PushOne 

func (m *Manager) PushOne(ctx context.Context, id string) error

func (*Manager) Resolve 

func (m *Manager) Resolve(local, remote *session.Session) (winner, loser *session.Session)

Resolve picks the winner between local and remote with last-write-wins on UpdatedAt. Identical content needs no conflict copy. Divergent revisions get a content-addressed copy so pulling one revision repeatedly is idempotent.

func (*Manager) Status 

func (m *Manager) Status(ctx context.Context) (Status, error)

type S3Backend 

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

S3Backend speaks S3 through minio-go, which works against AWS S3, R2, B2, MinIO and any other S3-compatible store.

func NewS3Backend 

func NewS3Backend(cfg config.SyncS3Config) (*S3Backend, error)

func (*S3Backend) Delete 

func (s *S3Backend) Delete(ctx context.Context, id string) error

func (*S3Backend) List 

func (s *S3Backend) List(ctx context.Context) ([]SessionMeta, error)

func (*S3Backend) Name 

func (s *S3Backend) Name() string

func (*S3Backend) Pull 

func (s *S3Backend) Pull(ctx context.Context, id string) ([]byte, SessionMeta, error)

func (*S3Backend) Push 

func (s *S3Backend) Push(ctx context.Context, id string, data []byte, meta SessionMeta) error

type SessionMeta 

type SessionMeta struct {
	ID           string    `json:"id"`
	Title        string    `json:"title"`
	UpdatedAt    time.Time `json:"updated_at"`
	MessageCount int       `json:"message_count"`
	OriginHost   string    `json:"origin_host"`
	Size         int       `json:"size,omitempty"`
}

SessionMeta is the lightweight descriptor stored alongside each blob.

type Status 

type Status struct {
	Backend  string    `json:"backend"`
	LastPush time.Time `json:"last_push"`
	LastPull time.Time `json:"last_pull"`
	Local    int       `json:"local"`
	Remote   int       `json:"remote"`
}

Status is a snapshot of last push/pull times for the /sync UI.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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