package output

import (
	"context"
	"errors"
	"time"
)

var ErrBackendClosed = errors.New("backend already closed")

// IQSample is a normalized interleaved I/Q sample pair.
type IQSample struct {
	I float32
	Q float32
}

// CompositeFrame carries a block of MPX/IQ samples along with timing metadata.
type CompositeFrame struct {
	Samples       []IQSample
	SampleRateHz  float64
	Timestamp     time.Time
	GeneratedAt   time.Time
	EnqueuedAt    time.Time
	DequeuedAt    time.Time
	WriteStartedAt time.Time
	Sequence      uint64
}

// BackendConfig describes the properties for a backend instance.
type BackendConfig struct {
	SampleRateHz float64
	Channels     int
	IQLevel      float32
	Metadata     map[string]string
}

// BackendCapabilities advertise what a backend can do.
type BackendCapabilities struct {
	SupportsComposite  bool
	FixedRate          bool
	MaxSamplesPerWrite int
}

// BackendInfo exposes runtime metadata about a backend.
type BackendInfo struct {
	Name         string
	Description  string
	Capabilities BackendCapabilities
}

// Backend defines the contract that all output backends must satisfy.
type Backend interface {
	Configure(ctx context.Context, cfg BackendConfig) error
	Write(ctx context.Context, frame *CompositeFrame) (int, error)
	Flush(ctx context.Context) error
	Close(ctx context.Context) error
	Info() BackendInfo
}