s3

type Config[T any] struct {
	// Client is an SDK v2 S3 client. The Source does not own its
	// lifecycle.
	Client *awss3.Client

	// Bucket is the S3 bucket to scan.
	Bucket string

	// Prefix narrows the scan (e.g. "events/year=2026/month=05/").
	// Empty means the entire bucket — usually undesirable.
	Prefix string

	// Decode is the per-line JSON-Lines decoder. Defaults to
	// jsonl.DefaultDecoder[T].
	Decode jsonl.Decoder[T]

	// EventID derives the dedup key per record. Receives the source
	// object key + line number for context. Default: "<key>:<line>".
	EventID func(decoded T, key string, lineNum int) string

	// EventTime, when non-nil, derives the per-record EventTime used
	// for window bucket assignment. Defaults to time.Now() when unset;
	// backfill of windowed counters must wire this to the record's
	// source-of-truth timestamp (e.g., the bucket-mid `occurred_at`
	// field on a Spark-aggregated row) or every row will land in the
	// same bucket.
	EventTime func(decoded T) time.Time

	// KeyFilter, when non-nil, is called for every listed object key
	// and must return true for keys that should be scanned. Use this
	// to skip non-data objects (manifests, _SUCCESS markers) or to
	// restrict the scan to a date range without changing the prefix.
	KeyFilter func(key string) bool

	// OnDecodeError is forwarded to the underlying jsonl source.
	OnDecodeError func(key string, lineNum int, line []byte, err error)

	// HandoffToken is what CaptureHandoff returns. Same caller-supplied
	// pattern as jsonl: the live-source resume position is captured
	// externally (e.g., when generating the S3 archive).
	HandoffToken snapshot.HandoffToken

	// MaxLineSize is forwarded to the jsonl source. Defaults to 1 MB.
	MaxLineSize int

	// OpenObject, when non-nil, overrides the default GetObject + gzip
	// handling. Use for custom compression (snappy, zstd) or for tests
	// that want to inject a static body. The returned Closer is closed
	// after the per-object scan completes.
	OpenObject func(ctx context.Context, key string) (io.ReadCloser, error)

	// ListKeys, when non-nil, overrides the default ListObjectsV2 paged
	// scan. Use for tests that want a fixed key set, or for callers
	// that maintain an external manifest of archive keys (e.g., a
	// `_manifest.json` written alongside the data files). When nil,
	// the source uses Client.ListObjectsV2 paged over the configured
	// Bucket + Prefix.
	ListKeys func(ctx context.Context) ([]string, error)

	// Concurrency bounds the number of objects fetched and decoded in
	// parallel. Default 1 (sequential, preserves lexicographic key
	// order for the emitted records). Set higher (typically 4–16) when
	// the prefix contains many small objects and the per-object
	// `GetObject` latency dominates. With Concurrency > 1 the record
	// emission order is non-deterministic across keys; per-record
	// EventID derivation handles dedup so this is safe under the
	// at-least-once contract.
	Concurrency int
}

type Source[T any] struct {
	// contains filtered or unexported fields
}