// Package source defines the contract every Collector source plugin implements.
//
// A Source is a long-running goroutine that converts external events into
// inbox writes. It receives an Emit callback at start; each external event it
// observes results in one Emit call. The Source returns when its context is
// canceled, or earlier on a fatal error.
//
// Sources do not own the inbox writer or any other shared state. They emit;
// the dispatcher routes. This keeps each source small and testable in
// isolation.
package source

import (
	"context"

	"git.botbought.ai/foreman/agent-watcher/internal/inbox"
)

// Emit is the callback a Source uses to push one observed event into the
// dispatcher. The dispatcher writes it to recipient's inbox file. Returning
// an error means the inbox write failed; sources may log and continue, or
// drop, or shut down — that's a per-source policy decision.
type Emit func(recipient string, ev *inbox.Event) error

// Source is a Collector input. Implementations are constructed with their
// own configuration and started via Run.
type Source interface {
	// Name is a short identifier for logs and the "source" field on emitted
	// events ("webhook", "drop-folder", etc.).
	Name() string

	// Run blocks until ctx is canceled or a fatal error occurs. Each
	// observed external event becomes one Emit call.
	Run(ctx context.Context, emit Emit) error
}