bundle

type Applier interface {
	// ApplyChunk applies one chunk's records, in one transaction. It must
	// return any error of c.Records and then not commit. A database applier
	// should also persist next in that transaction (exactly-once); the
	// consumer then saves next through the Checkpoint as well.
	//
	// Upserts are keyed by record id and must not replace a record stored
	// by a newer sequence than c.Manifest.Sequence: a chunk may be applied
	// twice after a crash.
	ApplyChunk(ctx context.Context, c *Chunk, next State) error
	// Complete finishes the bundle after its last chunk (for a snapshot:
	// remove what the snapshot no longer holds). It may be called again
	// after a crash and must be idempotent.
	Complete(ctx context.Context, m *Manifest, next State) error
}

type Checkpoint interface {
	Load(ctx context.Context) (State, error)
	Save(ctx context.Context, s State) error
}

type Chunk struct {
	Manifest *Manifest
	Located
	// contains filtered or unexported fields
}

type ChunkRef struct {
	SHA256       string `json:"sha256"`
	Size         int64  `json:"size"`
	Uncompressed int64  `json:"uncompressed"`
	Records      int    `json:"records"`
	FirstID      string `json:"first_id"`
	LastID       string `json:"last_id"`
}

type Config struct {
	Feed    string
	Fetcher *transfer.Fetcher
	// Trust builds the verifier from the release's key set (KeySetFile),
	// checking it against the pinned root. Nil: Verifier is used and no key
	// set is fetched.
	Trust    func(ctx context.Context, keySet []byte) (Verifier, error)
	Verifier Verifier

	Checkpoint Checkpoint
	Applier    Applier
	Limits     Limits
	// KeepCache keeps chunks of earlier bundles in the fetcher's cache
	// (default: only the applied bundle's chunks are kept, for reuse by the
	// next release).
	KeepCache bool
	Logger    *slog.Logger
	Now       func() time.Time
}

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

type ConsumerStats struct {
	Runs, Completed, Resumes, ChunksApplied, ChunksFailed, Records, Refused uint64
}

type Ed25519Signer struct{ Key ed25519.PrivateKey }

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

type FileCheckpoint struct{ Path string }

type FileRef struct {
	Name   string `json:"name"`
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

type Limits struct {
	MaxPointerBytes      int64         // default 64 KiB
	MaxKeySetBytes       int64         // default 64 KiB
	MaxManifestBytes     int64         // default 8 MiB
	MaxChunks            int           // per manifest, default 8192
	MaxChunkBytes        int64         // compressed, default 32 MiB
	MaxChunkUncompressed int64         // default 256 MiB
	MaxChunkRecords      int           // default 1 000 000
	MaxRecordBytes       int           // one JSON line, default 4 MiB
	MaxTotalBytes        int64         // compressed sum of a manifest, default 8 GiB
	MaxValidity          time.Duration // expires_at - created_at, default 8 days
	ClockSkew            time.Duration // tolerated future created_at, default 10 min
}

type Located struct {
	Stream string
	Index  int
	Ref    ChunkRef
}

type Manifest struct {
	Schema       string    `json:"schema"`
	Feed         string    `json:"feed"`
	Sequence     uint64    `json:"sequence"`
	Kind         string    `json:"kind"`
	BaseSequence uint64    `json:"base_sequence,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	ExpiresAt    time.Time `json:"expires_at"`
	Streams      []Stream  `json:"streams"`
	// Meta is the feed's own signed metadata (sources, licenses, stats,
	// collector build). The SDK does not interpret it.
	Meta json.RawMessage `json:"meta,omitempty"`
}

type Pointer struct {
	Schema       string    `json:"schema"`
	Feed         string    `json:"feed"`
	Sequence     uint64    `json:"sequence"`
	Snapshot     FileRef   `json:"snapshot"`
	Delta        *FileRef  `json:"delta,omitempty"`
	BaseSequence uint64    `json:"base_sequence,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	ExpiresAt    time.Time `json:"expires_at"`
}

type Result struct {
	UpToDate      bool
	Sequence      uint64
	Kind          string
	Resumed       bool
	ChunksApplied int
	Records       int
}

type Signer interface {
	Sign(payloadType string, payload []byte) ([]byte, error)
}

type State struct {
	Feed string `json:"feed"`
	// Applied is the last sequence applied completely (0: none).
	Applied uint64 `json:"applied"`
	// InProgress is the sequence being applied (0: none). It is never
	// reported as applied until every chunk and Complete succeeded.
	InProgress uint64 `json:"in_progress,omitempty"`
	// Kind and Manifest (sha256 of the manifest envelope) identify the
	// bundle in progress: a resume continues only the same manifest.
	Kind     string `json:"kind,omitempty"`
	Manifest string `json:"manifest,omitempty"`
	// NextChunk is the apply-order index of the next chunk to apply.
	NextChunk int       `json:"next_chunk,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

type Stream struct {
	Name    string     `json:"name"`
	Records int        `json:"records"`
	Chunks  []ChunkRef `json:"chunks"`
}

type Verifier interface {
	Verify(envelope []byte, payloadType string) ([]byte, error)
}

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

type WriterOptions struct {
	Feed         string
	Sequence     uint64
	Kind         string // KindSnapshot or KindDelta
	BaseSequence uint64 // a delta's base
	// TargetRecords is the average records per chunk (content-defined
	// boundary); MaxRecords (default 4x TargetRecords) and MaxUncompressed
	// are hard caps. A chunk holds at least TargetRecords/4 records unless
	// a cap or the stream's end cuts it.
	TargetRecords   int
	MaxRecords      int
	MaxUncompressed int64
}