task

type Canceler ¶ added in v1.0.1

type Canceler interface {
	// CancelTask 특정 작업 인스턴스를 취소합니다. 취소 성공 여부(error)를 반환합니다.
	CancelTask(instanceID InstanceID) error
}

Canceler 실행 중인 작업을 취소하는 인터페이스입니다.

type CommandConfig ¶ added in v1.0.1

type CommandConfig struct {
	ID CommandID

	// AllowMultiple 동일 명령어의 중복 실행(Concurrency) 허용 여부입니다.
	// - true: 여러 인스턴스가 동시에 병렬 실행될 수 있습니다.
	// - false: 이미 실행 중인 인스턴스가 있다면 새로운 요청은 무시됩니다 (Throttling/Idempotency).
	AllowMultiple bool

	NewSnapshot NewSnapshotFunc
}

CommandConfig 개별 명령어(Command)에 대한 실행 정책과 결과 데이터 구조체를 생성하는 구조체입니다.

type CommandID ¶ added in v1.0.1

type CommandID string

CommandID 작업 내에서 실행할 구체적인 명령어의 식별자입니다.

func (id CommandID) IsEmpty() bool

func (id CommandID) Match(target CommandID) bool

func (id CommandID) String() string

func (id CommandID) Validate() error

type Config ¶ added in v1.0.1

type Config struct {
	// Commands 이 Task가 수행할 수 있는 모든 하위 명령어(Command)의 정의 목록입니다.
	// Task는 최소 하나 이상의 CommandConfig를 포함해야 하며, 이를 통해 지원 가능한 기능의 범위를 결정합니다.
	Commands []*CommandConfig

	NewTask NewTaskFunc
}

Config Task 생성 및 명령어(Command) 구성을 위한 메타데이터를 정의하는 불변(Immutable) 설정 객체입니다. 레지스트리에 등록된 이후에는 상태가 변경되지 않으며(Read-Only), Task 인스턴스를 생성하기 위한 청사진(Blueprint)으로 사용됩니다.

func (c *Config) Validate() error

type ConfigLookup ¶ added in v1.0.1

type ConfigLookup struct {
	Task    *Config
	Command *CommandConfig
}

ConfigLookup 요청된 ID(Task/Command)를 통해 Registry에서 조회된(Found) 설정 조합입니다.

func FindConfigForTest(taskID ID, commandID CommandID) (*ConfigLookup, error)

type EqualFunc ¶ added in v1.0.1

type EqualFunc func(selem, telem interface{}) (bool, error)

type ExecuteFunc ¶ added in v1.0.1

type ExecuteFunc func(previousSnapshot interface{}, supportsHTML bool) (string, interface{}, error)

ExecuteFunc 작업 실행 로직을 정의하는 함수 타입입니다.

이 함수는 순수 함수(Pure Function)에 가깝게 구현되어야 하며, 작업에 필요한 데이터(Snapshot)를 받아 처리한 후 결과 메시지와 변경된 데이터를 반환합니다.

매개변수:

• previousSnapshot: 이전 실행 시 저장된 데이터 (상태 복원용). 최초 실행 시에는 nil 또는 초기값이 전달됩니다.
• supportsHTML: 알림 채널(Notifier)이 HTML 포맷을 지원하는지 여부.

반환값:

• string: 사용자에게 알림으로 전송할 메시지 본문. 빈 문자열일 경우 알림을 보내지 않습니다.
• interface{}: 실행 완료 후 저장할 새로운 데이터. 다음 실행 시 data 인자로 전달됩니다.
• error: 실행 중 발생한 에러. nil이 아니면 작업 실패로 처리됩니다.

type Executor ¶ added in v1.0.1

type Executor interface {
	Submitter
	Canceler
}

Executor 작업을 실행하고 취소할 수 있는 Combined 인터페이스입니다.

type Fetcher ¶ added in v1.0.0

type Fetcher interface {
	Get(url string) (*http.Response, error)
	Do(req *http.Request) (*http.Response, error)
}

Fetcher HTTP 요청을 수행하는 인터페이스

type FileTaskResultStorage ¶ added in v1.0.1

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

FileTaskResultStorage 파일 시스템 기반의 Task 결과 저장소 구현체

func NewFileTaskResultStorage(appName string) *FileTaskResultStorage

func (s *FileTaskResultStorage) Load(taskID ID, commandID CommandID, v interface{}) error

func (s *FileTaskResultStorage) Save(taskID ID, commandID CommandID, v interface{}) error

func (s *FileTaskResultStorage) SetBaseDir(dir string)

type HTTPFetcher ¶ added in v1.0.0

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

HTTPFetcher 기본 타임아웃(30초) 및 User-Agent 자동 추가 기능이 내장된 HTTP 클라이언트 구현체입니다.

func NewHTTPFetcher() *HTTPFetcher

func (h *HTTPFetcher) Do(req *http.Request) (*http.Response, error)

func (h *HTTPFetcher) Get(url string) (*http.Response, error)

type Handler ¶ added in v1.0.1

type Handler interface {
	GetID() ID
	GetCommandID() CommandID
	GetInstanceID() InstanceID

	// GetNotifierID 알림을 발송할 대상 Notifier의 ID를 반환합니다.
	GetNotifierID() string

	// Cancel 작업을 취소 요청합니다.
	// 호출 즉시 IsCanceled()가 true를 반환해야 하며, 실행 중인 로직은 이를 감지하여 조기 종료해야 합니다.
	Cancel()

	// IsCanceled 작업이 취소되었는지 여부를 반환합니다.
	// Run 루프 내에서 주기적으로 확인하여, 취소 시 작업을 중단하는 용도로 사용됩니다.
	IsCanceled() bool

	// ElapsedTimeAfterRun 작업이 시작된 후 경과된 시간(초)을 반환합니다.
	// 작업 모니터링이나 타임아웃 감지에 활용될 수 있습니다.
	ElapsedTimeAfterRun() int64

	// SetStorage 작업 결과를 저장할 스토리지를 주입합니다.
	// 테스트 시 Mock 스토리지를 주입하거나, 런타임에 동적으로 스토리지를 변경할 때 사용됩니다.
	SetStorage(storage TaskResultStorage)

	// Run 작업을 실행하는 메인 메서드입니다.
	Run(taskCtx TaskContext, notificationSender NotificationSender, taskStopWG *sync.WaitGroup, taskDoneC chan<- InstanceID)
}

Handler 개별 Task 인스턴스를 제어하고 상태를 조회하기 위한 인터페이스입니다.

Handler는 Service 레이어와 개별 Task 구현체(Task 구조체) 사이의 계약(Contract)을 정의합니다. Service는 이 인터페이스를 통해 Task의 구체적인 구현을 알 필요 없이, 표준화된 방식으로 실행(Run), 취소(Cancel), 상태 확인 등을 수행할 수 있습니다.

type ID ¶ added in v1.0.1

type ID string

ID 작업의 고유 식별자입니다.

func (id ID) IsEmpty() bool

func (id ID) String() string

func (id ID) Validate() error

type InstanceID ¶ added in v1.0.1

type InstanceID string

InstanceID 실행 중인 작업 인스턴스의 고유 식별자입니다.

func (id InstanceID) IsEmpty() bool

func (id InstanceID) String() string

func (id InstanceID) Validate() error

type NewSnapshotFunc ¶ added in v1.0.1

type NewSnapshotFunc func() interface{}

NewSnapshotFunc Task 결과 데이터 구조체를 생성하는 팩토리 함수입니다.

type NewTaskFunc ¶ added in v1.0.1

type NewTaskFunc func(InstanceID, *SubmitRequest, *config.AppConfig) (Handler, error)

NewTaskFunc Task 인스턴스를 생성하는 팩토리 함수입니다.

type NotificationSender ¶ added in v1.0.1

type NotificationSender interface {
	// Notify 지정된 NotifierID를 통해 알림 메시지를 전송합니다.
	// Task의 실행 컨텍스트(TaskContext)를 함께 전달하여, 알림 수신자가 작업의 메타데이터(TaskID, Title, 실행 시간 등)를
	// 확인할 수 있도록 지원합니다. 메시지 형식은 Notifier 구현체에 따라 달라질 수 있습니다.
	//
	// 파라미터:
	//   - taskCtx: 작업 실행 컨텍스트 정보 (필수)
	//   - notifierID: 메시지를 발송할 대상 Notifier의 고유 ID
	//   - message: 전송할 알림 메시지 본문
	//
	// 반환값:
	//   - bool: 발송 요청이 성공적으로 처리되었는지 여부
	Notify(taskCtx TaskContext, notifierID string, message string) bool

	// NotifyDefault 시스템 기본 알림 채널로 일반 메시지를 발송합니다.
	// 특정 Notifier를 지정하지 않고, 시스템 설정에 정의된 기본 채널(예: 운영자 공통 채널)로
	// 알림을 보내야 할 때 사용합니다.
	//
	// 파라미터:
	//   - message: 전송할 메시지 내용
	//
	// 반환값:
	//   - bool: 발송 요청이 성공적으로 처리되었는지 여부
	NotifyDefault(message string) bool

	// SupportsHTML 지정된 Notifier가 HTML 포맷의 메시지 본문을 지원하는지 확인합니다.
	// 마크다운이나 텍스트 스타일링(굵게, 기울임, 링크 등)이 포함된 메시지를 전송하기 전에,
	// 해당 Notifier가 이를 올바르게 렌더링할 수 있는지 검사하는 용도로 사용됩니다.
	//
	// 파라미터:
	//   - notifierID: 지원 여부를 확인할 Notifier의 ID
	//
	// 반환값:
	//   - bool: HTML 포맷 지원 여부 (true: 지원함, false: 텍스트로만 처리됨)
	SupportsHTML(notifierID string) bool
}

NotificationSender Task 실행 중 발생하는 다양한 이벤트(시작, 성공, 실패 등)를 외부로 알리기 위한 인터페이스입니다. Task 로직은 이 인터페이스를 통해 구체적인 알림 수단(Telegram, Email, Slack 등)의 구현 상세에 의존하지 않고 추상화된 방식으로 메시지를 전달합니다. 이를 통해 알림 채널의 유연한 교체와 확장이 가능해집니다.

type OnFoundFunc ¶ added in v1.0.1

type OnFoundFunc func(selem, telem interface{})

type OnNotFoundFunc ¶ added in v1.0.1

type OnNotFoundFunc func(selem interface{})

type Registry ¶ added in v1.0.1

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

Registry 등록된 모든 Task와 Command의 설정을 관리하는 중앙 저장소(Repository)입니다.

func (r *Registry) Register(taskID ID, config *Config)

func (r *Registry) RegisterForTest(taskID ID, config *Config)

type RetryFetcher ¶ added in v1.0.0

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

RetryFetcher Fetcher 인터페이스를 구현하며, HTTP 요청 실패 시 자동으로 재시도를 수행합니다. 단순한 재시도가 아닌, Exponential Backoff(지수 백오프)와 Jitter(무작위 지연) 전략을 결합하여 서버 부하를 최소화하면서도 성공 확률을 높이는 안정적인 재시도 메커니즘을 제공합니다.

func NewRetryFetcher(delegate Fetcher, maxRetries int, retryDelay time.Duration, maxDelay time.Duration) *RetryFetcher

func NewRetryFetcherFromConfig(maxRetries int, retryDelayStr string) *RetryFetcher

func (f *RetryFetcher) Do(req *http.Request) (*http.Response, error)

func (f *RetryFetcher) Get(url string) (*http.Response, error)

type RunBy ¶ added in v1.0.1

type RunBy int

RunBy 누가 작업을 실행했는지를 나타내는 타입입니다.

const (
	// RunByUnknown 실행 주체가 명확하지 않은 상태 (Zero Value 안전성 확보)
	RunByUnknown RunBy = iota
	// RunByUser 사용자가 직접 실행 요청한 경우입니다.
	RunByUser
	// RunByScheduler 스케줄러에 의해 자동으로 실행된 경우입니다.
	RunByScheduler
)

func (t RunBy) IsValid() bool

func (t RunBy) String() string

func (t RunBy) Validate() error

type Service ¶ added in v1.0.1

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

Service 애플리케이션의 핵심 비즈니스 로직인 Task의 실행, 스케줄링, 상태 관리를 총괄하는 중앙 오케스트레이터(Central Orchestrator)입니다.

설계 철학 및 아키텍처: 이 서비스는 '단일 이벤트 루프(Single-threaded Event Loop)' 패턴을 차용하여 설계되었습니다. Task의 제출(Submit), 완료(Done), 취소(Cancel) 등 모든 상태 변경 이벤트는 채널을 통해 직렬화(Serialize)되며, 메인 루프에서 순차적으로 처리됩니다. 이를 통해 복잡한 뮤텍스(Mutex) 사용을 최소화하고, 교착 상태(Deadlock) 없는 안전한 동시성을 보장합니다.

주요 기능 및 책임:

1. 요청 수신 및 검증 (Request Handling): 실행 요청의 유효성을 'Fail Fast' 원칙에 따라 즉시 검증합니다.
2. 스케줄링 (Scheduling): Cron 표현식에 따라 정해진 시간에 Task를 자동으로 실행합니다.
3. 동시성 제어 (Concurrency Control): Task별 설정(AllowMultiple)에 따라 중복 실행 방지 및 실행 흐름을 제어합니다.
4. 안정적 종료 (Graceful Shutdown): 시스템 종료 시 실행 중인 Task들이 안전하게 작업을 마칠 수 있도록 대기하고 정리합니다.

func NewService(appConfig *config.AppConfig) *Service

func (s *Service) CancelTask(instanceID InstanceID) (err error)

func (s *Service) SetNotificationSender(notificationSender NotificationSender)

func (s *Service) Start(serviceStopCtx context.Context, serviceStopWG *sync.WaitGroup) error

func (s *Service) SubmitTask(req *SubmitRequest) (err error)

type SubmitRequest ¶ added in v1.0.1

type SubmitRequest struct {
	// TaskID 실행할 작업의 고유 식별자입니다. (예: "NAVER", "KURLY")
	TaskID ID

	// CommandID 작업 내에서 수행할 구체적인 명령어 식별자입니다. (예: "CheckPrice")
	CommandID CommandID

	// TaskContext 작업 실행 컨텍스트입니다.
	// 실행 흐름 전반에 걸쳐 메타데이터(Title, ID 등)를 전달하고, 취소 신호(Cancellation)를 전파하는 데 사용됩니다.
	TaskContext TaskContext

	// NotifierID 알림을 전송할 대상 채널 또는 수단(Notifier)의 식별자입니다.
	// 지정하지 않을 경우, Task 설정에 정의된 기본 Notifier가 사용됩니다.
	NotifierID string

	// NotifyOnStart 작업 시작 시점에 '시작 알림'을 발송할지 여부를 결정하는 플래그입니다.
	NotifyOnStart bool

	// RunBy 해당 작업을 누가/무엇이 실행 요청했는지를 나타냅니다.
	// (예: RunByUser - 사용자 수동 실행, RunByScheduler - 스케줄러 자동 실행)
	RunBy RunBy
}

SubmitRequest 작업 식별자, 커맨드, 컨텍스트 등 작업(Task) 실행에 필요한 모든 메타데이터와 요청 정보를 캡슐화한 구조체입니다. Scheduler 또는 API 요청 등을 통해 작업을 트리거할 때 사용됩니다.

func (r *SubmitRequest) Validate() error

type Submitter ¶ added in v1.0.1

type Submitter interface {
	// SubmitTask 작업을 제출합니다. 제출 성공 여부(error)를 반환합니다.
	SubmitTask(req *SubmitRequest) error
}

Submitter 작업을 제출하는 인터페이스입니다.

type Task ¶ added in v1.0.1

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

Task 개별 작업의 실행 단위이자 상태를 관리하는 핵심 구조체입니다.

Task는 불변 상태(id, commandID 등)와 가변 상태(canceled, storage 상태 등)를 모두 포함하며, Service에 의해 생성되고 생명주기가 관리됩니다. 이 구조체는 '작업의 정의'와 '실행 상태'를 모두 캡슐화합니다.

주요 특징:

• 상태 보존 (Stateful): storage를 통해 실행 결과를 영속화하여, 스크래핑 작업 간의 데이터 연속성을 보장합니다.
• 실행 제어 (Control): Cancel() 메서드를 통해 실행 중인 작업을 안전하게 중단할 수 있습니다.
• 의존성 주입 (DI): storage, fetcher 등의 외부 의존성을 필드로 주입받아 테스트 용이성을 높입니다.

func NewBaseTask(id ID, commandID CommandID, instanceID InstanceID, notifierID string, runBy RunBy) Task

func (t *Task) Cancel()

func (t *Task) ElapsedTimeAfterRun() int64

func (t *Task) GetCommandID() CommandID

func (t *Task) GetFetcher() Fetcher

func (t *Task) GetID() ID

func (t *Task) GetInstanceID() InstanceID

func (t *Task) GetNotifierID() string

func (t *Task) GetRunBy() RunBy

func (t *Task) IsCanceled() bool

func (t *Task) Run(taskCtx TaskContext, notificationSender NotificationSender, taskStopWG *sync.WaitGroup, taskDoneC chan<- InstanceID)

func (t *Task) SetExecute(fn ExecuteFunc)

func (t *Task) SetFetcher(f Fetcher)

func (t *Task) SetRunBy(runBy RunBy)

func (t *Task) SetStorage(storage TaskResultStorage)

type TaskContext ¶

type TaskContext interface {
	context.Context // 표준 Context 인터페이스 임베딩 (DeadLine, Done, Err, Value 등 지원)

	With(key, val interface{}) TaskContext
	WithTask(taskID ID, commandID CommandID) TaskContext
	WithInstanceID(instanceID InstanceID, elapsedTimeAfterRun int64) TaskContext
	WithTitle(title string) TaskContext
	WithError() TaskContext

	GetID() ID
	GetCommandID() CommandID
	GetInstanceID() InstanceID
	GetTitle() string
	GetElapsedTimeAfterRun() int64
	IsErrorOccurred() bool
}

TaskContext 작업 실행 흐름 전반에서 메타데이터를 전달하는 컨텍스트 인터페이스입니다.

func NewTaskContext() TaskContext

type TaskResultStorage ¶ added in v1.0.1

type TaskResultStorage interface {
	Load(taskID ID, commandID CommandID, v interface{}) error
	Save(taskID ID, commandID CommandID, v interface{}) error
}

TaskResultStorage Task 실행 결과를 저장하고 불러오는 저장소 인터페이스