synchro

type AcceptedRecord struct {
	ID        string
	TableName string
	Operation Operation
}

type BucketUpdate struct {
	Added   []string `json:"added,omitempty"`
	Removed []string `json:"removed,omitempty"`
}

type ChangelogEntry struct {
	Seq       int64     `json:"seq"`
	BucketID  string    `json:"bucket_id"`
	TableName string    `json:"table_name"`
	RecordID  string    `json:"record_id"`
	Operation Operation `json:"operation"`
	CreatedAt time.Time `json:"created_at"`
}

type Client struct {
	ID          string     `json:"id"`
	UserID      string     `json:"user_id"`
	ClientID    string     `json:"client_id"`
	ClientName  *string    `json:"client_name,omitempty"`
	Platform    string     `json:"platform"`
	AppVersion  string     `json:"app_version"`
	BucketSubs  []string   `json:"bucket_subs,omitempty"`
	LastSyncAt  *time.Time `json:"last_sync_at,omitempty"`
	LastPullAt  *time.Time `json:"last_pull_at,omitempty"`
	LastPushAt  *time.Time `json:"last_push_at,omitempty"`
	LastPullSeq *int64     `json:"last_pull_seq,omitempty"`
	IsActive    bool       `json:"is_active"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
}

type CompactResult struct {
	DeactivatedClients int64
	SafeSeq            int64
	DeletedEntries     int64
}

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

type CompactorConfig struct {
	// StaleThreshold is how long since last sync before a client is deactivated.
	// Default: 7 days.
	StaleThreshold time.Duration

	// BatchSize is the maximum rows deleted per batch. Default: 10000.
	BatchSize int

	// Logger for compaction operations. Falls back to slog.Default().
	Logger *slog.Logger
}

type Config struct {
	// DB is the database connection pool.
	DB *sql.DB

	// Registry holds table configurations.
	Registry *Registry

	// Hooks for lifecycle callbacks.
	Hooks Hooks

	// ConflictResolver resolves push conflicts. Defaults to LWW.
	ConflictResolver ConflictResolver

	// Ownership resolves record ownership for bucketing. Defaults to JoinResolver.
	Ownership OwnershipResolver

	// MinClientVersion is the minimum supported client version (semver).
	MinClientVersion string

	// ClockSkewTolerance is added to client timestamps during LWW comparison.
	ClockSkewTolerance time.Duration

	// Compactor configures changelog compaction. Optional.
	Compactor *CompactorConfig

	// Logger for sync operations. Defaults to slog.Default().
	Logger *slog.Logger
}

type Conflict struct {
	Table       string
	RecordID    string
	ClientID    string
	UserID      string
	ClientData  json.RawMessage
	ServerData  json.RawMessage
	ClientTime  time.Time
	ServerTime  time.Time
	BaseVersion *time.Time
}

type ConflictResolver interface {
	Resolve(ctx context.Context, conflict Conflict) (Resolution, error)
}

type DB interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

type DeleteEntry struct {
	ID        string `json:"id"`
	TableName string `json:"table_name"`
}

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

type Hooks struct {
	// OnPushAccepted is called within the push transaction after records are applied.
	// Use this for side effects like rebuilding search indexes.
	OnPushAccepted func(ctx context.Context, tx *sql.Tx, accepted []AcceptedRecord) error

	// OnConflict is called when a conflict is detected and resolved.
	// This is informational — it cannot change the resolution.
	OnConflict func(ctx context.Context, conflict Conflict, resolution Resolution)

	// OnPullComplete is called after a successful pull operation.
	OnPullComplete func(ctx context.Context, clientID string, checkpoint int64, count int)

	// OnSchemaIncompatible is called when a client's version is below minimum.
	OnSchemaIncompatible func(ctx context.Context, clientID string, clientVer string, minVer string)

	// OnStaleClient is called when a client hasn't synced recently.
	// Return true to allow the sync, false to reject with ErrStaleClient.
	OnStaleClient func(ctx context.Context, clientID string, lastSync time.Time) bool

	// OnCompaction is called after a successful compaction run.
	OnCompaction func(ctx context.Context, result CompactResult)

	// OnSnapshotRequired is called when a client must rebuild from a full snapshot.
	OnSnapshotRequired func(ctx context.Context, clientID string, checkpoint int64, minSeq int64, reason string)
}

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

type LWWResolver struct {
	ClockSkewTolerance time.Duration
}

type Operation int

type OwnershipResolver interface {
	ResolveOwner(ctx context.Context, db DB, table string, recordID string, data map[string]any) ([]string, error)
}

type PullRequest struct {
	ClientID      string   `json:"client_id"`
	Checkpoint    int64    `json:"checkpoint"`
	Tables        []string `json:"tables,omitempty"`
	Limit         int      `json:"limit,omitempty"`
	KnownBuckets  []string `json:"known_buckets,omitempty"`
	SchemaVersion int64    `json:"schema_version,omitempty"`
	SchemaHash    string   `json:"schema_hash,omitempty"`
}

type PullResponse struct {
	Changes          []Record      `json:"changes"`
	Deletes          []DeleteEntry `json:"deletes"`
	Checkpoint       int64         `json:"checkpoint"`
	HasMore          bool          `json:"has_more"`
	SnapshotRequired bool          `json:"snapshot_required,omitempty"`
	SnapshotReason   string        `json:"snapshot_reason,omitempty"`
	BucketUpdates    *BucketUpdate `json:"bucket_updates,omitempty"`
	SchemaVersion    int64         `json:"schema_version"`
	SchemaHash       string        `json:"schema_hash"`
}

type PushPolicy string

type PushRecord struct {
	ID              string          `json:"id"`
	TableName       string          `json:"table_name"`
	Operation       string          `json:"operation"`
	Data            json.RawMessage `json:"data,omitempty"`
	ClientUpdatedAt time.Time       `json:"client_updated_at"`
	BaseUpdatedAt   *time.Time      `json:"base_updated_at,omitempty"`
}

type PushRequest struct {
	ClientID      string       `json:"client_id"`
	Changes       []PushRecord `json:"changes"`
	SchemaVersion int64        `json:"schema_version,omitempty"`
	SchemaHash    string       `json:"schema_hash,omitempty"`
}

type PushResponse struct {
	Accepted      []PushResult `json:"accepted"`
	Rejected      []PushResult `json:"rejected"`
	Checkpoint    int64        `json:"checkpoint"`
	ServerTime    time.Time    `json:"server_time"`
	SchemaVersion int64        `json:"schema_version"`
	SchemaHash    string       `json:"schema_hash"`
}

type PushResult struct {
	ID              string     `json:"id"`
	TableName       string     `json:"table_name"`
	Operation       string     `json:"operation"`
	Status          string     `json:"status"`
	ReasonCode      string     `json:"reason_code,omitempty"`
	Message         string     `json:"message,omitempty"`
	ServerVersion   *Record    `json:"server_version,omitempty"`
	ServerUpdatedAt *time.Time `json:"server_updated_at,omitempty"`
	ServerDeletedAt *time.Time `json:"server_deleted_at,omitempty"`
}

type Record struct {
	ID        string          `json:"id"`
	TableName string          `json:"table_name"`
	Data      json.RawMessage `json:"data"`
	UpdatedAt time.Time       `json:"updated_at"`
	DeletedAt *time.Time      `json:"deleted_at,omitempty"`
}

type RegisterRequest struct {
	ClientID      string  `json:"client_id"`
	ClientName    *string `json:"client_name,omitempty"`
	Platform      string  `json:"platform"`
	AppVersion    string  `json:"app_version"`
	SchemaVersion int64   `json:"schema_version,omitempty"`
	SchemaHash    string  `json:"schema_hash,omitempty"`
}

type RegisterResponse struct {
	ID            string     `json:"id"`
	ServerTime    time.Time  `json:"server_time"`
	LastSyncAt    *time.Time `json:"last_sync_at,omitempty"`
	Checkpoint    int64      `json:"checkpoint"`
	SchemaVersion int64      `json:"schema_version"`
	SchemaHash    string     `json:"schema_hash"`
}

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

type Resolution struct {
	// Winner is "client" or "server".
	Winner string
	// Reason explains the resolution.
	Reason string
}

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

type SQLBucketResolverConfig struct {
	// DB is used for SQL rule execution and optional fallback lookups.
	DB DB

	// Registry provides table config and default ownership metadata.
	Registry *Registry

	// GlobalFunction is the SQL resolver function used when a table does not
	// define TableConfig.BucketFunction.
	// Signature: (table_name text, operation text, new_row jsonb, old_row jsonb) -> setof text.
	GlobalFunction string

	// EnableGoFallback allows fallback to OwnershipResolver when SQL rule execution fails.
	// Default false for strict SQL-only operation.
	EnableGoFallback bool

	// GoFallback is used only when EnableGoFallback is true.
	// Defaults to JoinResolver.
	GoFallback OwnershipResolver

	// MaxBucketsPerEvent bounds fanout for a single row change. 0 means unlimited.
	MaxBucketsPerEvent int

	// Logger receives fallback warnings.
	Logger *slog.Logger
}

type SchemaColumn struct {
	Name             string `json:"name"`
	DBType           string `json:"db_type"`
	LogicalType      string `json:"logical_type"`
	Nullable         bool   `json:"nullable"`
	DefaultSQL       string `json:"default_sql,omitempty"`
	DefaultKind      string `json:"default_kind"`
	SQLiteDefaultSQL string `json:"sqlite_default_sql,omitempty"`
	IsPrimaryKey     bool   `json:"is_primary_key"`
}

type SchemaManifestEntry struct {
	SchemaVersion int64     `json:"schema_version"`
	SchemaHash    string    `json:"schema_hash"`
	CreatedAt     time.Time `json:"created_at"`
}

type SchemaResponse struct {
	SchemaVersion int64         `json:"schema_version"`
	SchemaHash    string        `json:"schema_hash"`
	ServerTime    time.Time     `json:"server_time"`
	Tables        []SchemaTable `json:"tables"`
}

type SchemaTable struct {
	TableName            string         `json:"table_name"`
	PushPolicy           string         `json:"push_policy"`
	ParentTable          string         `json:"parent_table,omitempty"`
	ParentFKCol          string         `json:"parent_fk_col,omitempty"`
	Dependencies         []string       `json:"dependencies,omitempty"`
	UpdatedAtColumn      string         `json:"updated_at_column"`
	DeletedAtColumn      string         `json:"deleted_at_column"`
	PrimaryKey           []string       `json:"primary_key"`
	BucketByColumn       string         `json:"bucket_by_column,omitempty"`
	BucketPrefix         string         `json:"bucket_prefix,omitempty"`
	GlobalWhenBucketNull bool           `json:"global_when_bucket_null,omitempty"`
	AllowGlobalRead      bool           `json:"allow_global_read,omitempty"`
	BucketFunction       string         `json:"bucket_function,omitempty"`
	Columns              []SchemaColumn `json:"columns"`
}

type ServerWinsResolver struct{}

type SnapshotCursor struct {
	Checkpoint int64  `json:"checkpoint"`
	TableIndex int    `json:"table_idx"`
	AfterID    string `json:"after_id"`
}

type SnapshotRequest struct {
	ClientID      string          `json:"client_id"`
	Cursor        *SnapshotCursor `json:"cursor,omitempty"`
	Limit         int             `json:"limit,omitempty"`
	SchemaVersion int64           `json:"schema_version,omitempty"`
	SchemaHash    string          `json:"schema_hash,omitempty"`
}

type SnapshotResponse struct {
	Records       []Record        `json:"records"`
	Cursor        *SnapshotCursor `json:"cursor,omitempty"`
	Checkpoint    int64           `json:"checkpoint"`
	HasMore       bool            `json:"has_more"`
	SchemaVersion int64           `json:"schema_version"`
	SchemaHash    string          `json:"schema_hash"`
}

type TableConfig struct {
	// TableName is the database table name.
	TableName string

	// PushPolicy controls whether pushes are accepted for this table.
	// Default: owner_only when OwnerColumn/ParentTable is set, otherwise disabled.
	PushPolicy PushPolicy

	// OwnerColumn is the column name for user ownership.
	OwnerColumn string

	// ParentTable is the parent table name for child tables.
	ParentTable string

	// ParentFKCol is the foreign key column pointing to the parent table.
	ParentFKCol string

	// SyncColumns specifies which columns to include in pull responses (nil = all columns).
	SyncColumns []string

	// Dependencies lists tables that must sync first (for push ordering).
	Dependencies []string

	// IDColumn is the primary key column name (defaults to "id").
	IDColumn string

	// UpdatedAtColumn is the timestamp column for change tracking (defaults to "updated_at").
	UpdatedAtColumn string

	// DeletedAtColumn is the soft delete column (defaults to "deleted_at").
	DeletedAtColumn string

	// ProtectedColumns are additional columns (beyond defaults) that clients may not write.
	// Default protected: id, created_at, updated_at, deleted_at, OwnerColumn.
	ProtectedColumns []string

	// BucketByColumn enables fast-path bucketing without SQL function execution.
	// Bucket ID is formed as BucketPrefix + value(column).
	BucketByColumn string

	// BucketPrefix prefixes fast-path bucket values. Default "user:".
	BucketPrefix string

	// GlobalWhenBucketNull emits "global" when BucketByColumn value is NULL/empty.
	GlobalWhenBucketNull bool

	// AllowGlobalRead enables NULL-owner rows to be readable by all users via RLS.
	// Default false.
	AllowGlobalRead bool

	// BucketFunction optionally overrides the global SQL bucket resolver function
	// for this table. Signature:
	//   (table_name text, operation text, new_row jsonb, old_row jsonb) -> setof text.
	BucketFunction string
	// contains filtered or unexported fields
}

type TableMeta struct {
	TableName            string   `json:"table_name"`
	PushPolicy           string   `json:"push_policy"`
	Dependencies         []string `json:"dependencies"`
	ParentTable          string   `json:"parent_table,omitempty"`
	ParentFKCol          string   `json:"parent_fk_col,omitempty"`
	UpdatedAtColumn      string   `json:"updated_at_column,omitempty"`
	DeletedAtColumn      string   `json:"deleted_at_column,omitempty"`
	BucketByColumn       string   `json:"bucket_by_column,omitempty"`
	BucketPrefix         string   `json:"bucket_prefix,omitempty"`
	GlobalWhenBucketNull bool     `json:"global_when_bucket_null,omitempty"`
	AllowGlobalRead      bool     `json:"allow_global_read,omitempty"`
	BucketFunction       string   `json:"bucket_function,omitempty"`
}

type TableMetaResponse struct {
	Tables        []TableMeta `json:"tables"`
	ServerTime    time.Time   `json:"server_time"`
	SchemaVersion int64       `json:"schema_version"`
	SchemaHash    string      `json:"schema_hash"`
}

type TxBeginner interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
}