dataflow

type BaseProcessor[T any] struct{}

type Closer interface {
	Close() error
}

type ComponentInfo struct {
	// FlowName is the name of the flow
	FlowName string
	// ComponentName is the component name (e.g., "source", "processor[0]", "sink")
	ComponentName string
	// ComponentType is the component type: "source", "processor", or "sink"
	ComponentType string
}

type ComponentSpec struct {
	// Name is the component name used for Registry lookup.
	Name string `yaml:"name" json:"name"`
	// Concurrency is the optional concurrency override for processors.
	// Only applies to processors that declare concurrency support.
	//   - nil or not set: use the component's declared default
	//   - 1: force single goroutine (disable concurrency)
	//   - N > 1: use N workers (no upper limit, user decides)
	// Recommended: set based on CPU cores and whether the component is I/O bound.
	// Ignored for source and sink.
	Concurrency *int `yaml:"concurrency" json:"concurrency"`
	// Config is the component-specific configuration passed to Init.
	Config map[string]interface{} `yaml:"config" json:"config"`
}

type ConcurrencyCap struct {
	// Supported indicates whether the component supports concurrent processing
	Supported bool
	// SuggestedMax is the suggested maximum concurrency (0 = no limit)
	SuggestedMax int
	// IsStateful indicates whether the component has internal state
	IsStateful bool
}

type ConcurrencyCapable interface {
	ConcurrencyCap() ConcurrencyCap
}

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

type FlowConfig struct {
	// Name is the flow name used for logging and monitoring.
	Name string `yaml:"name" json:"name"`
	// BufferSize is the channel buffer size between components.
	BufferSize int `yaml:"buffer_size" json:"buffer_size"`
	// Source is the source component configuration.
	Source ComponentSpec `yaml:"source" json:"source"`
	// Processors is the list of processor configurations (executed in order).
	Processors []ComponentSpec `yaml:"processors" json:"processors"`
	// Sink is the sink component configuration.
	Sink ComponentSpec `yaml:"sink" json:"sink"`
}

type MetricsRecorderAware interface {
	SetMetricsRecorder(recorder metrics.Recorder, info ComponentInfo)
}

type Processor[T any] interface {
	// Init initializes the component with JSON configuration.
	// Returns an error if config parsing or validation fails.
	Init(config []byte) error

	// Process reads data from input channel, processes it, and sends to output channel.
	// ctx: context for cancellation and timeout
	// in: input channel to read from (upstream writes to this)
	// out: output channel to write to (downstream reads from this)
	// Returns: error if any
	//
	// Implementation guidelines:
	// - Use for data := range in { ... } to iterate input channel
	// - Can filter data (not send to out)
	// - Can transform 1 record to N records (1:N)
	// - Can merge N records to 1 record (N:1)
	// - DO NOT close out channel (managed by framework)
	// - Return when in channel is closed and all data is processed
	Process(ctx context.Context, in <-chan T, out chan<- T) error
}

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

type Sink[T any] interface {
	// Init initializes the component with JSON configuration.
	// Returns an error if config parsing or validation fails.
	Init(config []byte) error

	// Consume reads data from input channel and writes to external system.
	// ctx: context for cancellation and timeout
	// in: input channel to read from
	// Returns: error if any
	//
	// Implementation guidelines:
	// - Use for data := range in { ... } to iterate input channel
	// - Implement batch writing for better performance
	// - Implement periodic flush to avoid data accumulation
	// - Return when in channel is closed and all data is written
	// - Handle write failures (retry or log error)
	Consume(ctx context.Context, in <-chan T) error
}

type Source[T any] interface {
	// Init initializes the component with JSON configuration.
	// This method only parses config, does NOT establish connections.
	// Returns an error if config parsing or validation fails.
	Init(config []byte) error

	// Read reads data from external system and sends to the output channel.
	// ctx: context for cancellation and timeout
	// out: output channel to send data
	// Returns: number of records sent, error if any
	//
	// Implementation guidelines:
	// - Establish connections in this method, not in Init
	// - Close resources before returning
	// - Check ctx.Done() regularly to support cancellation
	// - Return the count of successfully sent records
	Read(ctx context.Context, out chan<- T) (int64, error)
}

type StatelessProcessor[T any] struct{}

type Stats struct {
	// TotalIn is the total number of records read from source.
	TotalIn int64
	// TotalOut is the total number of records written to sink.
	TotalOut int64
	// TotalError is the total number of errors encountered.
	TotalError int64
	// Duration is the total run duration in milliseconds.
	Duration int64
}

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