definitions

type BaseProcessor struct {
	ID string // ID is the unique identifier of the processor.
}

type BranchTracker interface {
	// MarkProcessorComplete marks a processor as complete for a session.
	// It returns whether the current processor was the last one for this level and if the next level should be scheduled.
	MarkProcessorComplete(sessionID uuid.UUID, processorID uuid.UUID) (bool, error)

	// AddProcessorsForSession adds a set of processors to be tracked for the session at the current level.
	AddProcessorsForSession(sessionID uuid.UUID, processorIDs []uuid.UUID)

	// HasPendingProcessors returns true if there are processors in the current level that haven't completed.
	HasPendingProcessors(sessionID uuid.UUID) bool

	// ClearSession removes a session from the tracker once it's completed.
	ClearSession(sessionID uuid.UUID)
}

type EngineFileHandler interface {
	ProcessorFileHandler

	// GetInputFile returns the file path of the input file being processed.
	GetInputFile() string

	// GetOutputFile returns the file path of the output file generated by the processing.
	GetOutputFile() string

	// Close closes any resources associated with the file handler.
	Close()

	// GenerateNewFileHandler creates and returns a new file handler, typically used for handling parallel processing paths.
	// Returns:
	//   - A new instance of EngineFileHandler.
	//   - An error if the operation fails.
	GenerateNewFileHandler() (EngineFileHandler, error)
}

type EngineFlowObject struct {
	Metadata map[string]interface{} `json:"metadata"`
}

type EngineIncomingObject struct {
	FlowID    uuid.UUID
	Metadata  map[string]interface{}
	Reader    io.Reader
	SessionID uuid.UUID
}

type EngineInterface interface {
	Submit(flowID uuid.UUID, metadata map[string]interface{}, reader io.Reader) uuid.UUID
	SessionUpdates() <-chan SessionUpdate
}

type Flow struct {
	ID                uuid.UUID                `json:"id"`                 // ID uniquely identifies the flow.
	Name              string                   `json:"name"`               // Name is the human-readable name of the flow.
	Description       string                   `json:"description"`        // Description provides a brief explanation of the flow's purpose.
	Processors        []SimpleProcessor        `json:"processors"`         // Processors is the list of processors that are part of the flow, executed in order.
	TriggerProcessors []SimpleTriggerProcessor `json:"trigger_processors"` // TriggerProcessors is the list of trigger processors associated with the flow.
	Active            bool                     `json:"active"`             // Active indicates whether the flow is currently active.
	LastUpdated       int64                    `json:"last_updated"`       // LastUpdated indicates the last update timestamp for the flow.
}

type FlowManager interface {
	// GetFirstProcessorsForFlow retrieves the first processors for a given flow.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// Returns:
	// - []SimpleProcessor: A slice of the first processors for the flow.
	// - error: An error if the retrieval fails.
	GetFirstProcessorsForFlow(flowID uuid.UUID) ([]SimpleProcessor, error)

	// GetLastProcessorForFlow retrieves the last processor for a given flow.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// Returns:
	// - *SimpleProcessor: The last processor for the flow.
	// - error: An error if the retrieval fails.
	GetLastProcessorForFlow(flowID uuid.UUID) (*SimpleProcessor, error)

	// GetTriggerProcessorsForFlow retrieves the trigger processors for a given flow.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// Returns:
	// - []*SimpleTriggerProcessor: A slice of the trigger processors for the flow.
	// - error: An error if the retrieval fails.
	GetTriggerProcessorsForFlow(flowID uuid.UUID) ([]*SimpleTriggerProcessor, error)

	// ListFlows lists all flows with pagination and a time filter.
	// Parameters:
	// - pagination: The pagination request containing page number and items per page.
	// - since: The time filter to list flows updated since this time.
	// Returns:
	// - PaginatedData[*Flow]: The paginated data containing the flows.
	// - error: An error if the listing fails.
	ListFlows(pagination *PaginationRequest, since time.Time) (PaginatedData[*Flow], error)

	// GetFlowByID retrieves a flow by its unique identifier.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// Returns:
	// - *Flow: The flow with the specified ID.
	// - error: An error if the retrieval fails.
	GetFlowByID(flowID uuid.UUID) (*Flow, error)

	// GetProcessorByID retrieves a processor by its unique identifier within a flow.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// - processorID: The unique identifier of the processor.
	// Returns:
	// - *SimpleProcessor: The processor with the specified ID.
	// - error: An error if the retrieval fails.
	GetProcessorByID(flowID uuid.UUID, processorID uuid.UUID) (*SimpleProcessor, error)

	// GetNextProcessors retrieves the next processors for a given processor within a flow.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// - processorID: The unique identifier of the processor.
	// Returns:
	// - []SimpleProcessor: A slice of the next processors for the specified processor.
	// - error: An error if the retrieval fails.
	GetNextProcessors(flowID uuid.UUID, processorID uuid.UUID) ([]SimpleProcessor, error)

	// AddProcessorToFlowBefore adds a processor to a flow before a reference processor.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// - processor: The processor to add.
	// - referenceProcessorID: The unique identifier of the reference processor.
	// Returns:
	// - error: An error if the addition fails.
	AddProcessorToFlowBefore(flowID uuid.UUID, processor *SimpleProcessor, referenceProcessorID uuid.UUID) error

	// AddProcessorToFlowAfter adds a processor to a flow after a reference processor.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// - processor: The processor to add.
	// - referenceProcessorID: The unique identifier of the reference processor.
	// Returns:
	// - error: An error if the addition fails.
	AddProcessorToFlowAfter(flowID uuid.UUID, processor *SimpleProcessor, referenceProcessorID uuid.UUID) error

	// SaveFlow saves a flow.
	// Parameters:
	// - flow: The flow to save.
	// Returns:
	// - error: An error if the save operation fails.
	SaveFlow(flow *Flow) error

	// GetLastUpdateTime retrieves the last update time for a given flow.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// Returns:
	// - time.Time: The last update time of the flow.
	// - error: An error if the retrieval fails.
	GetLastUpdateTime(flowIDs []uuid.UUID) (map[uuid.UUID]time.Time, error)

	// SetFlowActive marks a flow as active or inactive.
	// Parameters:
	// - flowID: The unique identifier of the flow.
	// - active: A boolean indicating whether the flow should be marked as active.
	// Returns:
	// - error: An error if the operation fails.
	SetFlowActive(flowID uuid.UUID, active bool) error
}

type LogEntry struct {
	SessionID     uuid.UUID        `json:"session_id"`
	ProcessorName string           `json:"processor_name"`
	ProcessorID   string           `json:"processor_id"`
	FlowID        uuid.UUID        `json:"flow_id"`
	InputFile     string           `json:"input_file"`
	OutputFile    string           `json:"output_file"`
	FlowObject    EngineFlowObject `json:"flow_object"`
	RetryCount    int              `json:"retry_count"`
}

type PaginatedData[T any] struct {
	Data       []T `json:"data"`       // Data is the slice of items for the current page.
	TotalCount int `json:"totalCount"` // TotalCount is the total number of items available.
}

type PaginationRequest struct {
	Page    int `json:"page" query:"page"`        // Page number of the paginated data.
	PerPage int `json:"perPage" query:"per_page"` // Number of items per page.
}

type Processor interface {
	// GetID returns the ID of the processor.
	// Returns:
	// - string: The ID of the processor.
	GetID() string

	// Name returns the name of the processor.
	// Returns:
	// - string: The name of the processor.
	Name() string

	// Execute executes the processor logic.
	// Parameters:
	// - info: The EngineFlowObject containing the execution information.
	// - fileHandler: The ProcessorFileHandler for handling file operations.
	// - log: The logger for logging information.
	// Returns:
	// - *EngineFlowObject: The updated EngineFlowObject after execution.
	// - error: An error if the execution fails.
	Execute(info *EngineFlowObject, fileHandler ProcessorFileHandler, log *logrus.Logger) (*EngineFlowObject, error)

	// SetConfig sets the configuration for the processor.
	// Parameters:
	// - config: A map containing the configuration settings.
	// Returns:
	// - error: An error if setting the configuration fails.
	SetConfig(config map[string]interface{}) error
}

type ProcessorFactory interface {
	// GetProcessor retrieves a processor by its type name.
	// Parameters:
	// - typeName: The type name of the processor to retrieve.
	// Returns:
	// - Processor: The retrieved processor.
	// - error: An error if the retrieval fails.
	GetProcessor(typeName string) (Processor, error)

	// GetTriggerProcessor retrieves a trigger processor by its type name.
	// Parameters:
	// - typeName: The type name of the trigger processor to retrieve.
	// Returns:
	// - TriggerProcessor: The retrieved trigger processor.
	// - error: An error if the retrieval fails.
	GetTriggerProcessor(typeName string) (TriggerProcessor, error)
}

type ProcessorFileHandler interface {
	// Read reads data from a file.
	// Returns:
	// - io.Reader: The reader for reading data.
	// - error: An error if the read operation fails.
	Read() (io.Reader, error)

	// Write writes data to a file.
	// Returns:
	// - io.Writer: The writer for writing data.
	// - error: An error if the write operation fails.
	Write() (io.Writer, error)
}

type ScheduleConfig struct {
	Type     ScheduleType
	CronExpr string // Used only if Type == CronDriven
}

type ScheduleType int

type SessionUpdate struct {
	SessionID uuid.UUID `json:"session_id"`
	Finished  bool      `json:"finished"`
	Error     error     `json:"error"`
}

type SimpleProcessor struct {
	ID         uuid.UUID              `json:"id"`          // ID uniquely identifies the processor.
	FlowID     uuid.UUID              `json:"flow_id"`     // FlowID is the ID of the flow to which the processor belongs.
	Name       string                 `json:"name"`        // Name is the human-readable name of the processor.
	Type       string                 `json:"type"`        // Type indicates the type of the processor, used to determine its implementation.
	FlowOrder  int                    `json:"flow_order"`  // FlowOrder specifies the order in which the processor is executed within the flow.
	Config     map[string]interface{} `json:"config"`      // Config holds the specific configuration for the processor.
	MaxRetries int                    `json:"max_retries"` // MaxRetries specifies the maximum number of retries allowed for this processor in case of failure.
	LogLevel   logrus.Level           `json:"log_level"`   // LogLevel defines the logging level used for this processor.
	Enabled    bool                   `json:"enabled"`     // Enabled indicates if the processor is enabled.
}

type SimpleTriggerProcessor struct {
	ID           uuid.UUID              `json:"id"`            // ID uniquely identifies the trigger processor.
	FlowID       uuid.UUID              `json:"flow_id"`       // FlowID is the ID of the flow to which the trigger processor belongs.
	Name         string                 `json:"name"`          // Name is the human-readable name of the trigger processor.
	Type         string                 `json:"type"`          // Type indicates the type of the trigger processor, used to determine its implementation.
	Config       map[string]interface{} `json:"config"`        // Config holds the specific configuration for the trigger processor.
	ScheduleType ScheduleType           `json:"schedule_type"` // ScheduleType defines the type of scheduling (event-driven or cron-driven).
	CronExpr     string                 `json:"cron_expr"`     // CronExpr is the cron expression used for scheduling, applicable if ScheduleType is CronDriven.
	EventName    string                 `json:"event_name"`    // EventName is the name of the event to listen to, applicable if ScheduleType is EventDriven.
	LogLevel     logrus.Level           `json:"log_level"`     // LogLevel defines the logging level used for this trigger processor.
	Enabled      bool                   `json:"enabled"`       // Enabled indicates if the processor is enabled.
}

type TriggerProcessor interface {
	Processor
	// GetScheduleType returns the scheduling type supported by the TriggerProcessor.
	GetScheduleType() ScheduleType
	// HandleSessionUpdate allows the TriggerProcessor to respond to session updates.
	HandleSessionUpdate(update SessionUpdate)
	// Close is called when the TriggerProcessor is being stopped or cleaned up.
	Close() error
}

type WriteAheadLogger interface {
	WriteEntry(entry LogEntry)
	ReadEntries() ([]LogEntry, error)
}