sync

type Authorizer interface {
	Permits(ctx context.Context, actor appshared.ActorContext, request access.Request) (bool, error)
}

type Batch struct {
	// Records are the entries to send, oldest first. Empty is an ordinary answer - the log moved
	// and none of it concerned this caller.
	Records []Record
	// Cursor is where the walk stands *after* this batch, whether or not anything survived the
	// filter. Advancing past records the caller may not see is the point: a cursor that stalled on
	// a container somebody lost access to would re-read it forever.
	Cursor Position
	// More says the log had at least a full batch left. The caller comes straight back rather than
	// waiting to be woken.
	More bool
}

type Catalogue interface {
	Invoke(ctx context.Context, name string, actor appshared.ActorContext, in usecase.Input) (usecase.Output, error)
}

type ConflictDetail struct {
	Field              string
	Mine               any
	Theirs             any
	PreservedCommentID shared.ID
}

type Containers interface {
	Find(ctx context.Context, id shared.ID) (work.Container, error)
}

type Cursors interface {
	Encode(position Position) string
	Decode(cursor string) (Position, error)
}

type Depth string

type DeviceWriter struct {
	Devices    repository.Devices
	Sessions   SessionRevoker
	Cursors    Cursors
	Audit      audit.Sink
	UnitOfWork persistence.UnitOfWork
	Clock      clock.Clock
}

type DisplacedFiler interface {
	FileDisplaced(ctx context.Context, actor appshared.ActorContext, itemID shared.ID, body string,
		params map[string]string) (work.Comment, error)
}

type FieldChange struct {
	Value any
	HLC   string
}

type ForgetSyncDevice struct{ Writer DeviceWriter }

type ListSyncDevices struct{ Writer DeviceWriter }

type Mutation struct {
	OpID        shared.ID
	Kind        domain.MutationKind
	ItemID      shared.ID
	BaseVersion *int
	// Fields are per-field changes, each under its own clock (ITEM_PATCH).
	Fields map[string]FieldChange
	// Set and Element name a set change (SET_ADD, SET_REMOVE); HLC is its tag, and a creation's
	// or a deletion's reading.
	Set     string
	Element shared.ID
	HLC     string
	Payload map[string]any
}

type Page struct {
	Records    []Record
	Cursor     Position
	More       bool
	ServerTime time.Time
	Window     time.Duration
}

type Position struct {
	Seq      int64
	IssuedAt time.Time
	// Epoch is the workspace's synchronisation epoch the position was minted under
	// (backup-restore.md §12 B-5). A restore into the workspace advances the epoch, and a
	// cursor from an older one is refused as too old: the rows a restore wrote are in no change
	// log entry, so a delta past them would leave the device believing itself current.
	Epoch int64
	// Kind and After are where an initial synchronisation stands: the kind being walked
	// and the key of the last row handed out. Both empty is a delta position, the only kind the
	// stream resumes from.
	Kind  string
	After string
}

type PullChanges struct {
	Stream StreamChanges
	// Devices registers the device on its first contact and records every one after.
	// Nil registers nothing, which is a test's convenience and not an installation's.
	Devices repository.Devices
	// Snapshot reads the current state for an initial synchronisation. Nil means this
	// installation does not serve one, and a device with no cursor is told so.
	Snapshot repository.Snapshot
	// Structure resolves each container's structure in force onto its record in the initial
	// synchronisation, as every read of a container answers it (domain-model.md §2).
	Structure workservice.StructureResolver
}

type PullRequest struct {
	DeviceID shared.ID
	// Platform and DisplayName are what the device says about itself, both optional.
	Platform    string
	DisplayName string
	// Cursor is empty for an initial synchronisation.
	Cursor string
	Scopes []Scope
	// Limit is the page size. Zero means the contract's default; more than the maximum is refused
	// rather than clamped, because a client that asked for more than the contract allows has a
	// defect worth hearing about.
	Limit int
}

type PushChanges struct {
	Stream     StreamChanges
	Devices    repository.Devices
	Ops        repository.OpLog
	Tombstones repository.Tombstones
	// Clocks is the server's clock per field, which ITEM_PATCH decides against.
	Clocks    repository.FieldClocks
	Catalogue Catalogue
	// IDs mints the push's own identity: every event a mutation of this push raises names
	// it, which is what the webhook fan-out collapses the deliveries of one push on
	// (offline-sync.md §8).
	IDs clock.IDGenerator
	// Activity writes the two steps a merge owes the history - a change with meaning that lost,
	// and a merge that displaced free text. Nil writes neither, a test's convenience.
	Activity StepRecorder
	// Displaced files the version of a free-text field that lost as a comment (§5). Nil files
	// nothing, and the conflict still carries both values.
	Displaced DisplacedFiler
	// Sets is where each set's tags are read for the OR-set merge.
	Sets Sets
	// Skew is how far a device's clock may stand from the server's before its readings are
	// replaced by server readings (offline-sync.md §4.1). Zero means the contract's five minutes.
	Skew time.Duration
}

type PushRequest struct {
	DeviceID    shared.ID
	Platform    string
	DisplayName string
	Mutations   []Mutation
}

type PushResponse struct {
	Results    []Result
	Cursor     Position
	ServerTime time.Time
}

type Record struct {
	repository.Recorded
	// Cursor is the position after this record. What the stream sends as the event's `id`, and what
	// a client sends back as `Last-Event-ID` - so a client that received half a batch resumes in
	// the middle of it rather than at its start.
	Cursor Position
}

type Result struct {
	OpID     shared.ID
	Result   domain.ResultKind
	EntityID shared.ID
	// ServerState is the object as the server holds it after the mutation, on APPLIED and
	// MERGED, so that a client adopts the server's answer (offline-sync.md §9, requirement 5).
	ServerState map[string]any
	Conflict    *ConflictDetail
	Error       *ResultError
}

type ResultError struct {
	Code        string
	MessageCode string
}

type Scope struct {
	ContainerID shared.ID
	Depth       Depth
}

type SessionRevoker interface {
	Revoke(ctx context.Context, sessionID, accountID shared.ID, at time.Time) (bool, error)
}

type SetElements interface {
	Elements(ctx context.Context, itemID shared.ID) ([]work.SetElement, error)
}

type Sets struct {
	Labels      SetElements
	Members     SetElements
	Attachments SetElements
}

type SnapshotRequest struct {
	DeviceID    shared.ID
	Platform    string
	DisplayName string
	Scopes      []Scope
}

type StepRecorder interface {
	RecordStep(ctx context.Context, actor appshared.ActorContext, tenantID, itemID, collectionID shared.ID,
		verb activity.Verb, changeSet map[string]any, at time.Time) error
}

type StreamChanges struct {
	Changes    repository.Changes
	Containers Containers
	Authorizer Authorizer
	UnitOfWork persistence.UnitOfWork
	Cursors    Cursors
	// Epochs is the workspace's synchronisation epoch: every position is minted under the
	// current one, and a cursor from an older one is refused.
	Epochs repository.Epochs
	Clock  clock.Clock
	// Window is how far back a cursor may reach: the maximum offline window, which is also the
	// minimum tombstone period (offline-sync.md §7). Beyond it the log no longer holds everything
	// that happened, so a delta would be silently wrong.
	Window time.Duration
	// Batch is how many entries one round reads. A bound rather than a tuning knob: a round is a
	// read inside one transaction, and an unbounded one would hold it open across a backlog.
	Batch int
}