v0.13.1 folder restructure, test script added, format adapter async fix

internal/source/console/console.go

@@ -0,0 +1,224 @@
+package console
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"sync/atomic"
+	"time"
+
+	"logwisp/internal/config"
+	"logwisp/internal/core"
+	"logwisp/internal/plugin"
+	"logwisp/internal/session"
+	"logwisp/internal/source"
+
+	lconfig "github.com/lixenwraith/config"
+	"github.com/lixenwraith/log"
+)
+
+// init registers the component in plugin factory
+func init() {
+	if err := plugin.RegisterSource("console", NewConsoleSourcePlugin); err != nil {
+		panic(fmt.Sprintf("failed to register console source: %v", err))
+	}
+
+	// Console stdin can only have one reader
+	if err := plugin.SetSourceMetadata("console", &plugin.PluginMetadata{
+		Capabilities: []core.Capability{core.CapSessionAware, core.CapSingleInstance},
+		MaxInstances: 1,
+	}); err != nil {
+		panic(fmt.Sprintf("failed to set console source metadata: %v", err))
+	}
+}
+
+// ConsoleSource reads log entries from the standard input stream
+type ConsoleSource struct {
+	// Plugin identity and session management
+	id      string
+	proxy   *session.Proxy
+	session *session.Session
+
+	// Configuration
+	config *config.ConsoleSourceOptions
+
+	// Application
+	subscribers []chan core.LogEntry
+	logger      *log.Logger
+
+	// Runtime
+	done chan struct{}
+
+	// Statistics
+	totalEntries   atomic.Uint64
+	droppedEntries atomic.Uint64
+	startTime      time.Time
+	lastEntryTime  atomic.Value // time.Time
+}
+
+const (
+	DefaultConsoleSourceBufferSize = 1000
+)
+
+// NewConsoleSourcePlugin creates a console source through plugin factory
+func NewConsoleSourcePlugin(
+	id string,
+	configMap map[string]any,
+	logger *log.Logger,
+	proxy *session.Proxy,
+) (source.Source, error) {
+	opts := &config.ConsoleSourceOptions{}
+
+	// Scan config map
+	if err := lconfig.ScanMap(configMap, opts); err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+
+	// Validate and apply defaults
+	if opts.BufferSize <= 0 {
+		opts.BufferSize = DefaultConsoleSourceBufferSize
+	}
+
+	// Create and return plugin instance
+	cs := &ConsoleSource{
+		id:          id,
+		proxy:       proxy,
+		config:      opts,
+		subscribers: make([]chan core.LogEntry, 0),
+		done:        make(chan struct{}),
+		logger:      logger,
+	}
+	cs.lastEntryTime.Store(time.Time{})
+
+	// Create session
+	cs.session = proxy.CreateSession(
+		"console_stdin",
+		map[string]any{
+			"instance_id": id,
+			"type":        "console",
+		},
+	)
+
+	cs.logger.Info("msg", "Console source initialized",
+		"component", "console_source",
+		"instance_id", id)
+
+	return cs, nil
+}
+
+// Capabilities returns supported capabilities
+func (s *ConsoleSource) Capabilities() []core.Capability {
+	return []core.Capability{
+		core.CapSessionAware, // Single console session
+	}
+}
+
+// Subscribe returns a channel for receiving log entries.
+func (s *ConsoleSource) Subscribe() <-chan core.LogEntry {
+	ch := make(chan core.LogEntry, s.config.BufferSize)
+	s.subscribers = append(s.subscribers, ch)
+	return ch
+}
+
+// Start begins reading from the standard input.
+func (s *ConsoleSource) Start() error {
+	s.startTime = time.Now()
+	go s.readLoop()
+
+	// Update session activity
+	s.proxy.UpdateActivity(s.session.ID)
+
+	s.logger.Info("msg", "Console source started",
+		"component", "console_source",
+		"instance_id", s.id)
+	return nil
+}
+
+// Stop signals the source to stop reading.
+func (s *ConsoleSource) Stop() {
+	close(s.done)
+
+	// Remove session
+	if s.session != nil {
+		s.proxy.RemoveSession(s.session.ID)
+	}
+
+	// Close subscriber channels
+	for _, ch := range s.subscribers {
+		close(ch)
+	}
+
+	s.logger.Info("msg", "Console source stopped",
+		"component", "console_source",
+		"instance_id", s.id)
+}
+
+// GetStats returns the source's statistics
+func (s *ConsoleSource) GetStats() source.SourceStats {
+	lastEntry, _ := s.lastEntryTime.Load().(time.Time)
+
+	return source.SourceStats{
+		Type:           "console",
+		TotalEntries:   s.totalEntries.Load(),
+		DroppedEntries: s.droppedEntries.Load(),
+		StartTime:      s.startTime,
+		LastEntryTime:  lastEntry,
+		Details:        map[string]any{},
+	}
+}
+
+// readLoop continuously reads lines from stdin and publishes them
+func (s *ConsoleSource) readLoop() {
+	scanner := bufio.NewScanner(os.Stdin)
+	for scanner.Scan() {
+		select {
+		case <-s.done:
+			return
+		default:
+			// Update session activity on each read
+			s.proxy.UpdateActivity(s.session.ID)
+
+			// Get raw line
+			lineBytes := scanner.Bytes()
+			if len(lineBytes) == 0 {
+				continue
+			}
+
+			// Add newline back (scanner strips it)
+			lineWithNewline := append(lineBytes, '\n')
+
+			entry := core.LogEntry{
+				Time:    time.Now(),
+				Source:  "console",
+				Message: string(lineWithNewline), // Keep newline
+				Level:   source.ExtractLogLevel(string(lineBytes)),
+				RawSize: int64(len(lineWithNewline)),
+			}
+
+			s.publish(entry)
+		}
+	}
+
+	if err := scanner.Err(); err != nil {
+		s.logger.Error("msg", "Scanner error reading stdin",
+			"component", "console_source",
+			"instance_id", s.id,
+			"error", err)
+	}
+}
+
+// publish sends a log entry to all subscribers
+func (s *ConsoleSource) publish(entry core.LogEntry) {
+	s.totalEntries.Add(1)
+	s.lastEntryTime.Store(entry.Time)
+
+	for _, ch := range s.subscribers {
+		select {
+		case ch <- entry:
+		default:
+			s.droppedEntries.Add(1)
+			s.logger.Debug("msg", "Dropped log entry - subscriber buffer full",
+				"component", "console_source")
+		}
+	}
+}

internal/source/file/file.go

@@ -0,0 +1,364 @@
+package file
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"logwisp/internal/config"
+	"logwisp/internal/core"
+	"logwisp/internal/plugin"
+	"logwisp/internal/session"
+	"logwisp/internal/source"
+
+	lconfig "github.com/lixenwraith/config"
+	"github.com/lixenwraith/log"
+)
+
+// init registers the component in plugin factory
+func init() {
+	if err := plugin.RegisterSource("file", NewFileSourcePlugin); err != nil {
+		panic(fmt.Sprintf("failed to register file source: %v", err))
+	}
+}
+
+// FileSource monitors log files and tails them
+type FileSource struct {
+	// Plugin identity and session management
+	id      string
+	proxy   *session.Proxy
+	session *session.Session
+
+	// Configuration
+	config *config.FileSourceOptions
+
+	// Application
+	subscribers []chan core.LogEntry
+	watchers    map[string]*fileWatcher
+	logger      *log.Logger
+
+	// Runtime
+	mu     sync.RWMutex
+	ctx    context.Context
+	cancel context.CancelFunc
+	wg     sync.WaitGroup
+
+	// Statistics
+	totalEntries   atomic.Uint64
+	droppedEntries atomic.Uint64
+	startTime      time.Time
+	lastEntryTime  atomic.Value // time.Time
+}
+
+const (
+	DefaultFileSourcePattern         = "*"
+	DefaultFileSourceCheckIntervalMS = 100
+	MinFileSourceCheckIntervalMS     = 10
+)
+
+// NewFileSourcePlugin creates a file source through plugin factory
+func NewFileSourcePlugin(
+	id string,
+	configMap map[string]any,
+	logger *log.Logger,
+	proxy *session.Proxy,
+) (source.Source, error) {
+	opts := &config.FileSourceOptions{}
+
+	// Use lconfig to scan map into struct (overriding defaults)
+	if err := lconfig.ScanMap(configMap, opts); err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+
+	// Validate and apply defaults
+	if err := lconfig.NonEmpty(opts.Directory); err != nil {
+		return nil, fmt.Errorf("directory: %w", err)
+	}
+
+	if opts.Pattern == "" {
+		opts.Pattern = DefaultFileSourcePattern
+	}
+	if opts.CheckIntervalMS <= 0 {
+		opts.CheckIntervalMS = DefaultFileSourceCheckIntervalMS
+	} else if opts.CheckIntervalMS < MinFileSourceCheckIntervalMS {
+		return nil, fmt.Errorf("check_interval_ms: must be >= %d", MinFileSourceCheckIntervalMS)
+	}
+
+	// Create and return plugin instance
+	fs := &FileSource{
+		id:          id,
+		proxy:       proxy,
+		config:      opts,
+		subscribers: make([]chan core.LogEntry, 0),
+		watchers:    make(map[string]*fileWatcher),
+		logger:      logger,
+	}
+	fs.lastEntryTime.Store(time.Time{})
+
+	fs.session = proxy.CreateSession(
+		fmt.Sprintf("file:///%s/%s", opts.Directory, opts.Pattern),
+		map[string]any{
+			"instance_id": id,
+			"type":        "file",
+			"directory":   opts.Directory,
+			"pattern":     opts.Pattern,
+		},
+	)
+
+	fs.logger.Info("msg", "File source initialized",
+		"component", "file_source",
+		"instance_id", id,
+		"directory", opts.Directory,
+		"pattern", opts.Pattern)
+
+	return fs, nil
+}
+
+// Capabilities returns supported capabilities
+func (fs *FileSource) Capabilities() []core.Capability {
+	return []core.Capability{
+		core.CapSessionAware, // Tracks sessions per file
+		core.CapMultiSession, // Multiple file sessions
+	}
+}
+
+// Subscribe returns a channel for receiving log entries
+func (fs *FileSource) Subscribe() <-chan core.LogEntry {
+	fs.mu.Lock()
+	defer fs.mu.Unlock()
+
+	ch := make(chan core.LogEntry, 1000)
+	fs.subscribers = append(fs.subscribers, ch)
+	return ch
+}
+
+// Start begins the file monitoring loop
+func (fs *FileSource) Start() error {
+	fs.ctx, fs.cancel = context.WithCancel(context.Background())
+	fs.startTime = time.Now()
+	fs.wg.Add(1)
+	go fs.monitorLoop()
+
+	fs.logger.Info("msg", "File source started",
+		"component", "File_source",
+		"path", fs.config.Directory,
+		"pattern", fs.config.Pattern,
+		"check_interval_ms", fs.config.CheckIntervalMS)
+	return nil
+}
+
+// Stop gracefully shuts down the file source and all file watchers
+func (fs *FileSource) Stop() {
+	if fs.cancel != nil {
+		fs.cancel()
+	}
+	fs.wg.Wait()
+
+	fs.proxy.RemoveSession(fs.session.ID)
+
+	fs.mu.Lock()
+	for _, w := range fs.watchers {
+		w.stop()
+	}
+	for _, ch := range fs.subscribers {
+		close(ch)
+	}
+	fs.mu.Unlock()
+
+	fs.logger.Info("msg", "File source stopped",
+		"component", "file_source",
+		"instance_id", fs.id,
+		"path", fs.config.Directory)
+}
+
+// GetStats returns the source's statistics, including active watchers.
+func (fs *FileSource) GetStats() source.SourceStats {
+	lastEntry, _ := fs.lastEntryTime.Load().(time.Time)
+
+	fs.mu.RLock()
+	watcherCount := int64(len(fs.watchers))
+	details := make(map[string]any)
+
+	// Add watcher details
+	watchers := make([]map[string]any, 0, watcherCount)
+	for _, w := range fs.watchers {
+		info := w.getInfo()
+		watchers = append(watchers, map[string]any{
+			"directory":    info.Directory,
+			"size":         info.Size,
+			"position":     info.Position,
+			"entries_read": info.EntriesRead,
+			"rotations":    info.Rotations,
+			"last_read":    info.LastReadTime,
+		})
+	}
+	details["watchers"] = watchers
+	details["active_watchers"] = watcherCount
+	fs.mu.RUnlock()
+
+	return source.SourceStats{
+		ID:             fs.id,
+		Type:           "file",
+		TotalEntries:   fs.totalEntries.Load(),
+		DroppedEntries: fs.droppedEntries.Load(),
+		StartTime:      fs.startTime,
+		LastEntryTime:  lastEntry,
+		Details:        details,
+	}
+}
+
+// monitorLoop periodically scans path for new or changed files.
+func (fs *FileSource) monitorLoop() {
+	defer fs.wg.Done()
+
+	fs.checkTargets()
+
+	ticker := time.NewTicker(time.Duration(fs.config.CheckIntervalMS) * time.Millisecond)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-fs.ctx.Done():
+			return
+		case <-ticker.C:
+			fs.checkTargets()
+		}
+	}
+}
+
+// checkTargets finds matching files and ensures watchers are running for them.
+func (fs *FileSource) checkTargets() {
+	files, err := fs.scanFile()
+	if err != nil {
+		fs.logger.Warn("msg", "Failed to scan file",
+			"component", "file_source",
+			"path", fs.config.Directory,
+			"pattern", fs.config.Pattern,
+			"error", err)
+		return
+	}
+
+	for _, file := range files {
+		fs.ensureWatcher(file)
+	}
+
+	fs.cleanupWatchers()
+}
+
+// ensureWatcher creates and starts a new file watcher if one doesn't exist for the given path.
+func (fs *FileSource) ensureWatcher(path string) {
+	fs.mu.Lock()
+	defer fs.mu.Unlock()
+
+	if _, exists := fs.watchers[path]; exists {
+		return
+	}
+
+	w := newFileWatcher(path, fs.publish, fs.logger)
+	fs.watchers[path] = w
+
+	fs.logger.Debug("msg", "Created file watcher",
+		"component", "file_source",
+		"path", path)
+
+	fs.wg.Add(1)
+	go func() {
+		defer fs.wg.Done()
+		if err := w.watch(fs.ctx); err != nil {
+			if errors.Is(err, context.Canceled) {
+				fs.logger.Debug("msg", "Watcher cancelled",
+					"component", "file_source",
+					"path", path)
+			} else {
+				fs.logger.Error("msg", "Watcher failed",
+					"component", "file_source",
+					"path", path,
+					"error", err)
+			}
+		}
+
+		fs.mu.Lock()
+		delete(fs.watchers, path)
+		fs.mu.Unlock()
+	}()
+}
+
+// cleanupWatchers stops and removes watchers for files that no longer exist.
+func (fs *FileSource) cleanupWatchers() {
+	fs.mu.Lock()
+	defer fs.mu.Unlock()
+
+	for path, w := range fs.watchers {
+		if _, err := os.Stat(path); os.IsNotExist(err) {
+			w.stop()
+			delete(fs.watchers, path)
+			fs.logger.Debug("msg", "Cleaned up watcher for non-existent file",
+				"component", "file_source",
+				"path", path)
+		}
+	}
+}
+
+// publish sends a log entry to all subscribers.
+func (fs *FileSource) publish(entry core.LogEntry) {
+	fs.mu.RLock()
+	defer fs.mu.RUnlock()
+
+	fs.totalEntries.Add(1)
+	fs.lastEntryTime.Store(entry.Time)
+
+	for _, ch := range fs.subscribers {
+		select {
+		case ch <- entry:
+		default:
+			fs.droppedEntries.Add(1)
+			fs.logger.Debug("msg", "Dropped log entry - subscriber buffer full",
+				"component", "file_source")
+		}
+	}
+}
+
+// scanFile finds all files in the configured path that match the pattern.
+func (fs *FileSource) scanFile() ([]string, error) {
+	entries, err := os.ReadDir(fs.config.Directory)
+	if err != nil {
+		return nil, err
+	}
+
+	// Convert glob pattern to regex
+	regexPattern := globToRegex(fs.config.Pattern)
+	re, err := regexp.Compile(regexPattern)
+	if err != nil {
+		return nil, fmt.Errorf("invalid pattern regex: %w", err)
+	}
+
+	var files []string
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+
+		name := entry.Name()
+		if re.MatchString(name) {
+			files = append(files, filepath.Join(fs.config.Directory, name))
+		}
+	}
+
+	return files, nil
+}
+
+// globToRegex converts a simple glob pattern to a regular expression.
+func globToRegex(glob string) string {
+	regex := regexp.QuoteMeta(glob)
+	regex = strings.ReplaceAll(regex, `\*`, `.*`)
+	regex = strings.ReplaceAll(regex, `\?`, `.`)
+	return "^" + regex + "$"
+}
+

internal/source/file/file_watcher.go

@@ -0,0 +1,383 @@
+package file
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"time"
+
+	"logwisp/internal/core"
+	"logwisp/internal/source"
+
+	"github.com/lixenwraith/log"
+)
+
+// WatcherInfo contains snapshot information about a file watcher's state
+type WatcherInfo struct {
+	Directory    string
+	Size         int64
+	Position     int64
+	ModTime      time.Time
+	EntriesRead  uint64
+	LastReadTime time.Time
+	Rotations    int64
+}
+
+// fileWatcher tails a single file, handles rotations, and sends new lines to a callback
+type fileWatcher struct {
+	directory    string
+	callback     func(core.LogEntry)
+	position     int64
+	size         int64
+	inode        uint64
+	modTime      time.Time
+	mu           sync.Mutex
+	stopped      bool
+	rotationSeq  int64
+	entriesRead  atomic.Uint64
+	lastReadTime atomic.Value // time.Time
+	logger       *log.Logger
+}
+
+// newFileWatcher creates a new watcher for a specific file path
+func newFileWatcher(directory string, callback func(core.LogEntry), logger *log.Logger) *fileWatcher {
+	w := &fileWatcher{
+		directory: directory,
+		callback:  callback,
+		position:  -1,
+		logger:    logger,
+	}
+	w.lastReadTime.Store(time.Time{})
+	return w
+}
+
+// watch starts the main monitoring loop for the file
+func (w *fileWatcher) watch(ctx context.Context) error {
+	if err := w.seekToEnd(); err != nil {
+		return fmt.Errorf("seekToEnd failed: %w", err)
+	}
+
+	ticker := time.NewTicker(core.FileWatcherPollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-ticker.C:
+			if w.isStopped() {
+				return fmt.Errorf("watcher stopped")
+			}
+			if err := w.checkFile(); err != nil {
+				// Log error but continue watching
+				w.logger.Warn("msg", "checkFile error", "error", err)
+			}
+		}
+	}
+}
+
+// stop signals the watcher to terminate its loop
+func (w *fileWatcher) stop() {
+	w.mu.Lock()
+	w.stopped = true
+	w.mu.Unlock()
+}
+
+// getInfo returns a snapshot of the watcher's current statistics
+func (w *fileWatcher) getInfo() WatcherInfo {
+	w.mu.Lock()
+	info := WatcherInfo{
+		Directory:   w.directory,
+		Size:        w.size,
+		Position:    w.position,
+		ModTime:     w.modTime,
+		EntriesRead: w.entriesRead.Load(),
+		Rotations:   w.rotationSeq,
+	}
+	w.mu.Unlock()
+
+	if lastRead, ok := w.lastReadTime.Load().(time.Time); ok {
+		info.LastReadTime = lastRead
+	}
+
+	return info
+}
+
+// checkFile examines the file for changes, rotations, or new content
+func (w *fileWatcher) checkFile() error {
+	file, err := os.Open(w.directory)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// File doesn't exist yet, keep watching
+			return nil
+		}
+		w.logger.Error("msg", "Failed to open file for checking",
+			"component", "file_watcher",
+			"directory", w.directory,
+			"error", err)
+		return err
+	}
+	defer file.Close()
+
+	info, err := file.Stat()
+	if err != nil {
+		w.logger.Error("msg", "Failed to stat file",
+			"component", "file_watcher",
+			"directory", w.directory,
+			"error", err)
+		return err
+	}
+
+	w.mu.Lock()
+	oldPos := w.position
+	oldSize := w.size
+	oldInode := w.inode
+	oldModTime := w.modTime
+	w.mu.Unlock()
+
+	currentSize := info.Size()
+	currentModTime := info.ModTime()
+	var currentInode uint64
+
+	if stat, ok := info.Sys().(*syscall.Stat_t); ok {
+		currentInode = stat.Ino
+	}
+
+	// Handle first time seeing a file that didn't exist before
+	if oldInode == 0 && currentInode != 0 {
+		// File just appeared, don't treat as rotation
+		w.mu.Lock()
+		w.inode = currentInode
+		w.size = currentSize
+		w.modTime = currentModTime
+		// Position stays at 0 for new files
+		w.mu.Unlock()
+		// Don't return here - continue to read content
+	}
+
+	// Check for rotation
+	rotated := false
+	rotationReason := ""
+	startPos := oldPos
+
+	// Rotation detection
+	if currentSize < oldSize {
+		// File was truncated
+		rotated = true
+		rotationReason = "size decrease"
+	} else if currentModTime.Before(oldModTime) && currentSize <= oldSize {
+		// Modification time went backwards (logrotate behavior)
+		rotated = true
+		rotationReason = "modification time reset"
+	} else if oldPos > currentSize+1024 {
+		// Our position is way beyond file size
+		rotated = true
+		rotationReason = "position beyond file size"
+	} else if oldInode != 0 && currentInode != 0 && currentInode != oldInode {
+		// Inode changed - distinguish between rotation and atomic save
+		if currentSize == 0 {
+			// Empty file with new inode = likely rotation
+			rotated = true
+			rotationReason = "inode change with empty file"
+		} else if currentSize < oldPos {
+			// New file is smaller than our position = rotation
+			rotated = true
+			rotationReason = "inode change with size less than position"
+		} else {
+			// Inode changed but file has content and size >= position
+			// This is likely an atomic save by an editor
+			// Update inode but keep position
+			w.mu.Lock()
+			w.inode = currentInode
+			w.mu.Unlock()
+
+			w.logger.Debug("msg", "Atomic file update detected",
+				"component", "file_watcher",
+				"directory", w.directory,
+				"old_inode", oldInode,
+				"new_inode", currentInode,
+				"position", oldPos,
+				"size", currentSize)
+		}
+	}
+
+	if rotated {
+		startPos = 0
+		w.mu.Lock()
+		w.rotationSeq++
+		seq := w.rotationSeq
+		w.inode = currentInode
+		w.position = 0 // Reset position on rotation
+		w.mu.Unlock()
+
+		w.callback(core.LogEntry{
+			Time:    time.Now(),
+			Source:  filepath.Base(w.directory),
+			Level:   "INFO",
+			Message: fmt.Sprintf("Log rotation detected (#%d): %s", seq, rotationReason),
+		})
+
+		w.logger.Info("msg", "Log rotation detected",
+			"component", "file_watcher",
+			"directory", w.directory,
+			"sequence", seq,
+			"reason", rotationReason)
+	}
+
+	// Read if there's new content OR if we need to continue from position
+	if currentSize > startPos {
+		if _, err := file.Seek(startPos, io.SeekStart); err != nil {
+			return err
+		}
+
+		scanner := bufio.NewScanner(file)
+		scanner.Buffer(make([]byte, 0, 64*1024), core.MaxLogEntryBytes)
+
+		for scanner.Scan() {
+			line := scanner.Text()
+			if line == "" {
+				continue
+			}
+
+			rawSize := int64(len(line))
+			entry := w.parseLine(line)
+			entry.RawSize = rawSize
+
+			w.callback(entry)
+			w.entriesRead.Add(1)
+			w.lastReadTime.Store(time.Now())
+		}
+
+		if err := scanner.Err(); err != nil {
+			w.logger.Error("msg", "Scanner error while reading file",
+				"component", "file_watcher",
+				"directory", w.directory,
+				"position", startPos,
+				"error", err)
+			return err
+		}
+
+		// Update position after successful read
+		currentPos, err := file.Seek(0, io.SeekCurrent)
+		if err != nil {
+			// Log error but don't fail - best effort position tracking
+			w.logger.Warn("msg", "Failed to get file position", "error", err)
+			// Use size as fallback position
+			currentPos = currentSize
+		}
+
+		w.mu.Lock()
+		w.position = currentPos
+		w.size = currentSize
+		w.modTime = currentModTime
+		if !rotated && currentInode != 0 {
+			w.inode = currentInode
+		}
+		w.mu.Unlock()
+
+		return scanner.Err()
+	}
+
+	// Update metadata even if no new content
+	w.mu.Lock()
+	w.size = currentSize
+	w.modTime = currentModTime
+	if currentInode != 0 {
+		w.inode = currentInode
+	}
+	w.mu.Unlock()
+
+	return nil
+}
+
+// seekToEnd sets the initial read position to the end of the file
+func (w *fileWatcher) seekToEnd() error {
+	file, err := os.Open(w.directory)
+	if err != nil {
+		if os.IsNotExist(err) {
+			w.mu.Lock()
+			w.position = 0
+			w.size = 0
+			w.modTime = time.Now()
+			w.inode = 0
+			w.mu.Unlock()
+			return nil
+		}
+		return err
+	}
+	defer file.Close()
+
+	info, err := file.Stat()
+	if err != nil {
+		return err
+	}
+
+	w.mu.Lock()
+	defer w.mu.Unlock()
+
+	// Keep existing position (including 0)
+	// First time initialization seeks to the end of the file
+	if w.position == -1 {
+		pos, err := file.Seek(0, io.SeekEnd)
+		if err != nil {
+			return err
+		}
+		w.position = pos
+	}
+
+	w.size = info.Size()
+	w.modTime = info.ModTime()
+	if stat, ok := info.Sys().(*syscall.Stat_t); ok {
+		w.inode = stat.Ino
+	}
+
+	return nil
+}
+
+// isStopped checks if the watcher has been instructed to stop
+func (w *fileWatcher) isStopped() bool {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.stopped
+}
+
+// parseLine attempts to parse a line as JSON, falling back to plain text
+func (w *fileWatcher) parseLine(line string) core.LogEntry {
+	var jsonLog struct {
+		Time    string          `json:"time"`
+		Level   string          `json:"level"`
+		Message string          `json:"msg"`
+		Fields  json.RawMessage `json:"fields"`
+	}
+
+	if err := json.Unmarshal([]byte(line), &jsonLog); err == nil {
+		timestamp, err := time.Parse(time.RFC3339Nano, jsonLog.Time)
+		if err != nil {
+			timestamp = time.Now()
+		}
+
+		return core.LogEntry{
+			Time:    timestamp,
+			Source:  filepath.Base(w.directory),
+			Level:   jsonLog.Level,
+			Message: jsonLog.Message,
+			Fields:  jsonLog.Fields,
+		}
+	}
+
+	level := source.ExtractLogLevel(line)
+
+	return core.LogEntry{
+		Time:    time.Now(),
+		Source:  filepath.Base(w.directory),
+		Level:   level,
+		Message: line,
+	}
+}

internal/source/httpchain/httpchain.go

@@ -0,0 +1,324 @@
+package httpchain
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"logwisp/internal/chain"
+	"logwisp/internal/config"
+	"logwisp/internal/core"
+	"logwisp/internal/plugin"
+	"logwisp/internal/session"
+	"logwisp/internal/source"
+
+	lconfig "github.com/lixenwraith/config"
+	"github.com/lixenwraith/log"
+)
+
+func init() {
+	if err := plugin.RegisterSource("http_chain", NewHTTPChainSourcePlugin); err != nil {
+		panic(fmt.Sprintf("failed to register http_chain source: %v", err))
+	}
+}
+
+const (
+	DefaultHTTPChainSourceBufferSize    = 1000
+	DefaultHTTPChainSourceIngestPath    = "/ingest"
+	DefaultHTTPChainSourceMaxBodyBytes  = 8 * 1024 * 1024
+	DefaultHTTPChainSourceReadTimeoutMS = 30000
+	HTTPChainReadHeaderTimeout          = 10 * time.Second
+	HTTPChainServerShutdownTimeout      = 2 * time.Second
+)
+
+// HTTPChainSource accepts NDJSON batches from upstream http_chain sinks
+type HTTPChainSource struct {
+	id     string
+	proxy  *session.Proxy
+	config *config.HTTPChainSourceOptions
+
+	subscribers []chan core.LogEntry
+	server      *http.Server
+	logger      *log.Logger
+
+	// Session cache: one session per remote host + declared node
+	sessions   map[string]string // key -> sessionID
+	sessionsMu sync.Mutex
+
+	mu sync.RWMutex
+
+	startTime        time.Time
+	totalEntries     atomic.Uint64
+	droppedEntries   atomic.Uint64
+	parseErrors      atomic.Uint64
+	totalRequests    atomic.Uint64
+	rejectedRequests atomic.Uint64
+	lastEntryTime    atomic.Value // time.Time
+}
+
+// NewHTTPChainSourcePlugin creates an http_chain source through plugin factory
+func NewHTTPChainSourcePlugin(
+	id string,
+	configMap map[string]any,
+	logger *log.Logger,
+	proxy *session.Proxy,
+) (source.Source, error) {
+	opts := &config.HTTPChainSourceOptions{
+		Host:      "0.0.0.0",
+		TrustNode: true,
+	}
+	if err := lconfig.ScanMap(configMap, opts); err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+	if err := lconfig.Port(opts.Port); err != nil {
+		return nil, fmt.Errorf("port: %w", err)
+	}
+	if opts.IngestPath == "" {
+		opts.IngestPath = DefaultHTTPChainSourceIngestPath
+	} else if !strings.HasPrefix(opts.IngestPath, "/") {
+		return nil, fmt.Errorf("ingest_path: must start with '/'")
+	}
+	if opts.BufferSize <= 0 {
+		opts.BufferSize = DefaultHTTPChainSourceBufferSize
+	}
+	if opts.MaxBodyBytes <= 0 {
+		opts.MaxBodyBytes = DefaultHTTPChainSourceMaxBodyBytes
+	}
+	if opts.ReadTimeoutMS <= 0 {
+		opts.ReadTimeoutMS = DefaultHTTPChainSourceReadTimeoutMS
+	}
+
+	s := &HTTPChainSource{
+		id:          id,
+		proxy:       proxy,
+		config:      opts,
+		subscribers: make([]chan core.LogEntry, 0),
+		sessions:    make(map[string]string),
+		logger:      logger,
+	}
+	s.lastEntryTime.Store(time.Time{})
+
+	logger.Info("msg", "HTTP chain source initialized",
+		"component", "http_chain_source",
+		"instance_id", id,
+		"host", opts.Host,
+		"port", opts.Port,
+		"ingest_path", opts.IngestPath)
+	return s, nil
+}
+
+// Capabilities returns supported capabilities
+func (s *HTTPChainSource) Capabilities() []core.Capability {
+	// CapTLS/CapAuth added when transport security lands
+	return []core.Capability{
+		core.CapSessionAware,
+		core.CapMultiSession,
+	}
+}
+
+// Subscribe returns a channel for receiving log entries
+func (s *HTTPChainSource) Subscribe() <-chan core.LogEntry {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	ch := make(chan core.LogEntry, s.config.BufferSize)
+	s.subscribers = append(s.subscribers, ch)
+	return ch
+}
+
+// Start binds the listener and serves the ingest endpoint
+func (s *HTTPChainSource) Start() error {
+	addr := net.JoinHostPort(s.config.Host, strconv.FormatInt(s.config.Port, 10))
+	// IPv4-only, aligns with tcp/http sinks
+	ln, err := net.Listen("tcp4", addr)
+	if err != nil {
+		return fmt.Errorf("listen %s: %w", addr, err)
+	}
+
+	mux := http.NewServeMux()
+	// Method-scoped pattern: mux answers 405 with Allow header on non-POST
+	mux.HandleFunc(http.MethodPost+" "+s.config.IngestPath, s.handleIngest)
+
+	s.server = &http.Server{
+		Handler:           mux,
+		ReadTimeout:       time.Duration(s.config.ReadTimeoutMS) * time.Millisecond,
+		ReadHeaderTimeout: HTTPChainReadHeaderTimeout,
+		// Future: TLSConfig for transport security
+	}
+	s.startTime = time.Now()
+
+	go func() {
+		if err := s.server.Serve(ln); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			s.logger.Error("msg", "HTTP chain server terminated",
+				"component", "http_chain_source",
+				"instance_id", s.id,
+				"error", err)
+		}
+	}()
+
+	s.logger.Info("msg", "HTTP chain source started",
+		"component", "http_chain_source",
+		"instance_id", s.id,
+		"addr", addr)
+	return nil
+}
+
+// Stop shuts down the server, sessions, and subscriber channels
+func (s *HTTPChainSource) Stop() {
+	if s.server != nil {
+		ctx, cancel := context.WithTimeout(context.Background(), HTTPChainServerShutdownTimeout)
+		defer cancel()
+		s.server.Shutdown(ctx)
+	}
+
+	s.sessionsMu.Lock()
+	for _, id := range s.sessions {
+		s.proxy.RemoveSession(id)
+	}
+	s.sessions = make(map[string]string)
+	s.sessionsMu.Unlock()
+
+	s.mu.Lock()
+	for _, ch := range s.subscribers {
+		close(ch)
+	}
+	s.mu.Unlock()
+
+	s.logger.Info("msg", "HTTP chain source stopped",
+		"component", "http_chain_source",
+		"instance_id", s.id)
+}
+
+// GetStats returns the source's statistics
+func (s *HTTPChainSource) GetStats() source.SourceStats {
+	lastEntry, _ := s.lastEntryTime.Load().(time.Time)
+
+	s.sessionsMu.Lock()
+	cachedSessions := len(s.sessions)
+	s.sessionsMu.Unlock()
+
+	return source.SourceStats{
+		ID:             s.id,
+		Type:           "http_chain",
+		TotalEntries:   s.totalEntries.Load(),
+		DroppedEntries: s.droppedEntries.Load(),
+		StartTime:      s.startTime,
+		LastEntryTime:  lastEntry,
+		Details: map[string]any{
+			"host":              s.config.Host,
+			"port":              s.config.Port,
+			"ingest_path":       s.config.IngestPath,
+			"total_requests":    s.totalRequests.Load(),
+			"rejected_requests": s.rejectedRequests.Load(),
+			"parse_errors":      s.parseErrors.Load(),
+			"cached_sessions":   cachedSessions,
+			"trust_node":        s.config.TrustNode,
+		},
+	}
+}
+
+// handleIngest validates protocol headers and ingests one NDJSON batch.
+// Batch acceptance is atomic: entries publish only after a clean full read.
+func (s *HTTPChainSource) handleIngest(w http.ResponseWriter, r *http.Request) {
+	s.totalRequests.Add(1)
+
+	if r.Header.Get(chain.HeaderProtocol) != strconv.Itoa(chain.ProtocolVersion) {
+		s.rejectedRequests.Add(1)
+		http.Error(w, "unsupported protocol version", http.StatusBadRequest)
+		return
+	}
+
+	remoteHost := r.RemoteAddr
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		remoteHost = host
+	}
+	connNode := r.Header.Get(chain.HeaderNode)
+	if connNode == "" || !s.config.TrustNode {
+		connNode = remoteHost
+	}
+
+	body := http.MaxBytesReader(w, r.Body, s.config.MaxBodyBytes)
+	scanner := bufio.NewScanner(body)
+	scanner.Buffer(make([]byte, 0, 64*1024), core.MaxLogEntryBytes)
+
+	entries := make([]core.LogEntry, 0, 128)
+	for scanner.Scan() {
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+		entry, err := chain.DecodeEntry(line, connNode, s.config.TrustNode)
+		if err != nil {
+			// Content error within a clean transfer: skip line, keep batch
+			s.parseErrors.Add(1)
+			continue
+		}
+		entries = append(entries, entry)
+	}
+	if err := scanner.Err(); err != nil {
+		// Transfer error: reject batch without partial ingestion, sender retries
+		s.rejectedRequests.Add(1)
+		var maxErr *http.MaxBytesError
+		if errors.As(err, &maxErr) {
+			http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
+			return
+		}
+		s.logger.Debug("msg", "Chain batch read failed",
+			"component", "http_chain_source",
+			"remote_addr", r.RemoteAddr,
+			"error", err)
+		http.Error(w, "malformed body", http.StatusBadRequest)
+		return
+	}
+
+	for _, entry := range entries {
+		s.publish(entry)
+	}
+	s.proxy.UpdateActivity(s.sessionFor(remoteHost, connNode))
+
+	w.Header().Set(chain.HeaderAccepted, strconv.Itoa(len(entries)))
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// sessionFor returns the cached session for a remote+node, recreating after idle expiry
+func (s *HTTPChainSource) sessionFor(remoteHost, node string) string {
+	key := remoteHost + "|" + node
+	s.sessionsMu.Lock()
+	defer s.sessionsMu.Unlock()
+
+	if id, ok := s.sessions[key]; ok {
+		if _, exists := s.proxy.GetSession(id); exists {
+			return id
+		}
+	}
+	sess := s.proxy.CreateSession(remoteHost, map[string]any{
+		"type": "http_chain",
+		"node": node,
+	})
+	s.sessions[key] = sess.ID
+	return sess.ID
+}
+
+// publish sends a log entry to all subscribers
+func (s *HTTPChainSource) publish(entry core.LogEntry) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	s.totalEntries.Add(1)
+	s.lastEntryTime.Store(entry.Time)
+
+	for _, ch := range s.subscribers {
+		select {
+		case ch <- entry:
+		default:
+			s.droppedEntries.Add(1)
+		}
+	}
+}

internal/source/null/null.go

@@ -0,0 +1,125 @@
+package null
+
+import (
+	"fmt"
+	"sync/atomic"
+	"time"
+
+	"logwisp/internal/core"
+	"logwisp/internal/plugin"
+	"logwisp/internal/session"
+	"logwisp/internal/source"
+
+	"github.com/lixenwraith/log"
+)
+
+// init registers the component in plugin factory
+func init() {
+	if err := plugin.RegisterSource("null", NewNullSourcePlugin); err != nil {
+		panic(fmt.Sprintf("failed to register null source: %v", err))
+	}
+}
+
+// NullSource generates no log entries, used for testing
+type NullSource struct {
+	// Plugin identity and session management
+	id      string
+	proxy   *session.Proxy
+	session *session.Session
+
+	// Application
+	subscribers []chan core.LogEntry
+	logger      *log.Logger
+
+	// Runtime
+	done chan struct{}
+
+	// Statistics
+	totalEntries  atomic.Uint64
+	startTime     time.Time
+	lastEntryTime atomic.Value // time.Time
+}
+
+// NewNullSourcePlugin creates a null source through plugin factory
+func NewNullSourcePlugin(
+	id string,
+	configMap map[string]any,
+	logger *log.Logger,
+	proxy *session.Proxy,
+) (source.Source, error) {
+	ns := &NullSource{
+		id:          id,
+		proxy:       proxy,
+		subscribers: make([]chan core.LogEntry, 0),
+		done:        make(chan struct{}),
+		logger:      logger,
+	}
+	ns.lastEntryTime.Store(time.Time{})
+
+	// Create session for null source
+	ns.session = proxy.CreateSession(
+		"null://void",
+		map[string]any{
+			"instance_id": id,
+			"type":        "null",
+		},
+	)
+
+	logger.Debug("msg", "Null source initialized",
+		"component", "null_source",
+		"instance_id", id)
+
+	return ns, nil
+}
+
+// Capabilities returns supported capabilities
+func (ns *NullSource) Capabilities() []core.Capability {
+	return []core.Capability{
+		core.CapSessionAware,
+	}
+}
+
+// Subscribe returns a channel for receiving log entries
+func (ns *NullSource) Subscribe() <-chan core.LogEntry {
+	ch := make(chan core.LogEntry, 1000)
+	ns.subscribers = append(ns.subscribers, ch)
+	return ch
+}
+
+// Start begins the source operation (no-op for null source)
+func (ns *NullSource) Start() error {
+	ns.startTime = time.Now()
+	ns.proxy.UpdateActivity(ns.session.ID)
+	ns.logger.Debug("msg", "Null source started",
+		"component", "null_source",
+		"instance_id", ns.id)
+	return nil
+}
+
+// Stop signals the source to stop
+func (ns *NullSource) Stop() {
+	close(ns.done)
+	if ns.session != nil {
+		ns.proxy.RemoveSession(ns.session.ID)
+	}
+	for _, ch := range ns.subscribers {
+		close(ch)
+	}
+	ns.logger.Debug("msg", "Null source stopped",
+		"component", "null_source",
+		"instance_id", ns.id)
+}
+
+// GetStats returns the source's statistics
+func (ns *NullSource) GetStats() source.SourceStats {
+	lastEntry, _ := ns.lastEntryTime.Load().(time.Time)
+
+	return source.SourceStats{
+		ID:            ns.id,
+		Type:          "null",
+		TotalEntries:  ns.totalEntries.Load(),
+		StartTime:     ns.startTime,
+		LastEntryTime: lastEntry,
+		Details:       map[string]any{},
+	}
+}

internal/source/random/random.go

@@ -0,0 +1,358 @@
+package random
+
+import (
+	"encoding/json"
+	"fmt"
+	"math/rand"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"logwisp/internal/config"
+	"logwisp/internal/core"
+	"logwisp/internal/plugin"
+	"logwisp/internal/session"
+	"logwisp/internal/source"
+
+	lconfig "github.com/lixenwraith/config"
+	"github.com/lixenwraith/log"
+)
+
+// init registers the component in plugin factory
+func init() {
+	if err := plugin.RegisterSource("random", NewRandomSourcePlugin); err != nil {
+		panic(fmt.Sprintf("failed to register random source: %v", err))
+	}
+}
+
+// RandomSource generates random log entries for testing
+type RandomSource struct {
+	// Plugin identity and session management
+	id      string
+	proxy   *session.Proxy
+	session *session.Session
+
+	// Configuration
+	config *config.RandomSourceOptions
+
+	// Application
+	subscribers []chan core.LogEntry
+	logger      *log.Logger
+	rng         *rand.Rand
+	mu          sync.RWMutex
+
+	// Runtime
+	done   chan struct{}
+	wg     sync.WaitGroup
+	cancel chan struct{}
+
+	// Statistics
+	totalEntries   atomic.Uint64
+	droppedEntries atomic.Uint64
+	startTime      time.Time
+	lastEntryTime  atomic.Value // time.Time
+}
+
+const (
+	DefaultRandomSourceIntervalMS = 500
+	DefaultRandomSourceFormat     = "txt"
+	DefaultRandomSourceLength     = 20
+)
+
+// NewRandomSourcePlugin creates a random source through plugin factory
+func NewRandomSourcePlugin(
+	id string,
+	configMap map[string]any,
+	logger *log.Logger,
+	proxy *session.Proxy,
+) (source.Source, error) {
+	// Step 1: Create empty config struct with defaults
+	opts := &config.RandomSourceOptions{
+		IntervalMS: 500,
+		JitterMS:   0,
+		Format:     "txt",
+		Length:     20,
+		Special:    false,
+	}
+
+	// Scan config map
+	if err := lconfig.ScanMap(configMap, opts); err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+
+	// Defaults
+	if opts.IntervalMS <= 0 {
+		opts.IntervalMS = DefaultRandomSourceIntervalMS
+	}
+	if opts.Format == "" {
+		opts.Format = DefaultRandomSourceFormat
+	}
+	if opts.Length <= 0 {
+		opts.Length = DefaultRandomSourceLength
+	}
+
+	// Validate
+	if opts.JitterMS < 0 {
+		return nil, fmt.Errorf("jitter_ms cannot be negative")
+	}
+	if opts.JitterMS > opts.IntervalMS {
+		opts.JitterMS = opts.IntervalMS
+	}
+
+	validateFormat := lconfig.OneOf("raw", "txt", "json")
+	if err := validateFormat(opts.Format); err != nil {
+		return nil, fmt.Errorf("format: %w", err)
+	}
+
+	rs := &RandomSource{
+		id:          id,
+		proxy:       proxy,
+		config:      opts,
+		subscribers: make([]chan core.LogEntry, 0),
+		done:        make(chan struct{}),
+		cancel:      make(chan struct{}),
+		logger:      logger,
+		rng:         rand.New(rand.NewSource(time.Now().UnixNano())),
+	}
+	rs.lastEntryTime.Store(time.Time{})
+
+	// Create session for random source
+	rs.session = proxy.CreateSession(
+		fmt.Sprintf("random://%s", id),
+		map[string]any{
+			"instance_id": id,
+			"type":        "random",
+			"format":      opts.Format,
+			"interval_ms": opts.IntervalMS,
+		},
+	)
+
+	logger.Debug("msg", "Random source initialized",
+		"component", "random_source",
+		"instance_id", id,
+		"format", opts.Format,
+		"interval_ms", opts.IntervalMS,
+		"jitter_ms", opts.JitterMS)
+
+	return rs, nil
+}
+
+// Capabilities returns supported capabilities
+func (rs *RandomSource) Capabilities() []core.Capability {
+	return []core.Capability{
+		core.CapSessionAware,
+	}
+}
+
+// Subscribe returns a channel for receiving log entries
+func (rs *RandomSource) Subscribe() <-chan core.LogEntry {
+	rs.mu.Lock()
+	defer rs.mu.Unlock()
+	ch := make(chan core.LogEntry, 1000)
+	rs.subscribers = append(rs.subscribers, ch)
+	return ch
+}
+
+// Start begins generating random log entries
+func (rs *RandomSource) Start() error {
+	rs.startTime = time.Now()
+	rs.wg.Add(1)
+	go rs.generateLoop()
+
+	rs.proxy.UpdateActivity(rs.session.ID)
+	rs.logger.Debug("msg", "Random source started",
+		"component", "random_source",
+		"instance_id", rs.id)
+	return nil
+}
+
+// Stop signals the source to stop generating
+func (rs *RandomSource) Stop() {
+	close(rs.cancel)
+	rs.wg.Wait()
+
+	if rs.session != nil {
+		rs.proxy.RemoveSession(rs.session.ID)
+	}
+
+	rs.mu.Lock()
+	for _, ch := range rs.subscribers {
+		close(ch)
+	}
+	rs.mu.Unlock()
+
+	rs.logger.Debug("msg", "Random source stopped",
+		"component", "random_source",
+		"instance_id", rs.id,
+		"total_entries", rs.totalEntries.Load())
+}
+
+// GetStats returns the source's statistics
+func (rs *RandomSource) GetStats() source.SourceStats {
+	lastEntry, _ := rs.lastEntryTime.Load().(time.Time)
+
+	return source.SourceStats{
+		ID:             rs.id,
+		Type:           "random",
+		TotalEntries:   rs.totalEntries.Load(),
+		DroppedEntries: rs.droppedEntries.Load(),
+		StartTime:      rs.startTime,
+		LastEntryTime:  lastEntry,
+		Details: map[string]any{
+			"format":      rs.config.Format,
+			"interval_ms": rs.config.IntervalMS,
+			"jitter_ms":   rs.config.JitterMS,
+			"length":      rs.config.Length,
+			"special":     rs.config.Special,
+		},
+	}
+}
+
+// generateLoop continuously generates random log entries at configured intervals
+func (rs *RandomSource) generateLoop() {
+	defer rs.wg.Done()
+
+	for {
+		// Calculate next interval with jitter
+		interval := time.Duration(rs.config.IntervalMS) * time.Millisecond
+		if rs.config.JitterMS > 0 {
+			jitter := time.Duration(rs.rng.Intn(int(rs.config.JitterMS))) * time.Millisecond
+			interval = interval - time.Duration(rs.config.JitterMS/2)*time.Millisecond + jitter
+		}
+
+		select {
+		case <-time.After(interval):
+			entry := rs.generateEntry()
+			rs.publish(entry)
+			rs.proxy.UpdateActivity(rs.session.ID)
+		case <-rs.cancel:
+			return
+		case <-rs.done:
+			return
+		}
+	}
+}
+
+// generateEntry creates a random log entry based on configured format
+func (rs *RandomSource) generateEntry() core.LogEntry {
+	now := time.Now()
+
+	switch rs.config.Format {
+	case "raw":
+		message := rs.generateRandomString(int(rs.config.Length))
+		return core.LogEntry{
+			Time:    now,
+			Source:  fmt.Sprintf("random_%s", rs.id),
+			Message: message,
+			RawSize: int64(len(message) + 1), // +1 for newline
+		}
+
+	case "txt":
+		level := rs.randomLogLevel()
+		message := rs.generateRandomString(int(rs.config.Length))
+		formatted := fmt.Sprintf("[%s] [%s] random_%s - %s",
+			now.Format(time.RFC3339),
+			level,
+			rs.id,
+			message)
+		return core.LogEntry{
+			Time:    now,
+			Source:  fmt.Sprintf("random_%s", rs.id),
+			Level:   level,
+			Message: formatted,
+			RawSize: int64(len(formatted) + 1),
+		}
+
+	case "json":
+		level := rs.randomLogLevel()
+		message := rs.generateRandomString(int(rs.config.Length))
+		data := map[string]any{
+			"time":    now.Format(time.RFC3339Nano),
+			"level":   level,
+			"source":  fmt.Sprintf("random_%s", rs.id),
+			"message": message,
+		}
+		jsonBytes, _ := json.Marshal(data)
+		return core.LogEntry{
+			Time:    now,
+			Source:  fmt.Sprintf("random_%s", rs.id),
+			Level:   level,
+			Message: string(jsonBytes),
+			RawSize: int64(len(jsonBytes) + 1),
+		}
+
+	default:
+		return core.LogEntry{}
+	}
+}
+
+// generateRandomString creates a random string of specified length
+func (rs *RandomSource) generateRandomString(length int) string {
+	const normalChars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 "
+	const specialChars = "\t\n\r\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0B\x0C\x0E\x0F"
+	const unicodeChars = "™€¢£¥§©®°±µ¶·ÀÉÑÖÜßäëïöü←↑→↓∀∃∅∇∈∉∪∩≈≠≤≥"
+
+	result := make([]byte, 0, length)
+
+	if rs.config.Special && length >= 3 {
+		// Reserve space for at least one special and one unicode char
+		normalLength := length - 2
+
+		// Generate normal characters
+		for i := 0; i < normalLength; i++ {
+			result = append(result, normalChars[rs.rng.Intn(len(normalChars))])
+		}
+
+		// Insert special character at random position
+		specialPos := rs.rng.Intn(len(result) + 1)
+		specialChar := specialChars[rs.rng.Intn(len(specialChars))]
+		result = append(result[:specialPos], append([]byte{specialChar}, result[specialPos:]...)...)
+
+		// Insert unicode character at random position
+		unicodePos := rs.rng.Intn(len(result) + 1)
+		unicodeChar := unicodeChars[rs.rng.Intn(len(unicodeChars)/3)*3:]
+		if len(unicodeChar) >= 3 {
+			unicodeBytes := []byte(unicodeChar[:3])
+			if unicodePos == len(result) {
+				result = append(result, unicodeBytes...)
+			} else {
+				result = append(result[:unicodePos], append(unicodeBytes, result[unicodePos:]...)...)
+			}
+		}
+
+		// Trim to exact length if needed
+		if len(result) > length {
+			result = result[:length]
+		}
+	} else {
+		// Normal generation without special characters
+		for i := 0; i < length; i++ {
+			result = append(result, normalChars[rs.rng.Intn(len(normalChars))])
+		}
+	}
+
+	return string(result)
+}
+
+// randomLogLevel returns a random log level
+func (rs *RandomSource) randomLogLevel() string {
+	levels := []string{"DEBUG", "INFO", "WARN", "ERROR"}
+	return levels[rs.rng.Intn(len(levels))]
+}
+
+// publish sends a log entry to all subscribers
+func (rs *RandomSource) publish(entry core.LogEntry) {
+	rs.mu.RLock()
+	defer rs.mu.RUnlock()
+
+	rs.totalEntries.Add(1)
+	rs.lastEntryTime.Store(entry.Time)
+
+	for _, ch := range rs.subscribers {
+		select {
+		case ch <- entry:
+		default:
+			rs.droppedEntries.Add(1)
+		}
+	}
+}

internal/source/source.go

@@ -0,0 +1,62 @@
+package source
+
+import (
+	"strings"
+	"time"
+
+	"logwisp/internal/core"
+)
+
+// Source represents an input data stream for log entries
+type Source interface {
+	// Capabilities returns a slice of supported Source capabilities
+	Capabilities() []core.Capability
+
+	// Subscribe returns a channel that receives log entries from the source
+	Subscribe() <-chan core.LogEntry
+
+	// Start begins reading from the source
+	Start() error
+
+	// Stop gracefully shuts down the source
+	Stop()
+
+	// SourceStats contains statistics about a source
+	GetStats() SourceStats
+}
+
+// SourceStats contains statistics about a source
+type SourceStats struct {
+	ID             string
+	Type           string
+	TotalEntries   uint64
+	DroppedEntries uint64
+	StartTime      time.Time
+	LastEntryTime  time.Time
+	Details        map[string]any
+}
+
+// ExtractLogLevel heuristically determines the log level from a line of text
+func ExtractLogLevel(line string) string {
+	patterns := []struct {
+		patterns []string
+		level    string
+	}{
+		{[]string{"[ERROR]", "ERROR:", " ERROR ", "ERR:", "[ERR]", "FATAL:", "[FATAL]"}, "ERROR"},
+		{[]string{"[WARN]", "WARN:", " WARN ", "WARNING:", "[WARNING]"}, "WARN"},
+		{[]string{"[INFO]", "INFO:", " INFO ", "[INF]", "INF:"}, "INFO"},
+		{[]string{"[DEBUG]", "DEBUG:", " DEBUG ", "[DBG]", "DBG:"}, "DEBUG"},
+		{[]string{"[TRACE]", "TRACE:", " TRACE "}, "TRACE"},
+	}
+
+	upperLine := strings.ToUpper(line)
+	for _, group := range patterns {
+		for _, pattern := range group.patterns {
+			if strings.Contains(upperLine, pattern) {
+				return group.level
+			}
+		}
+	}
+
+	return ""
+}

internal/source/tcpchain/tcpchain.go

@@ -0,0 +1,353 @@
+package tcpchain
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"logwisp/internal/chain"
+	"logwisp/internal/config"
+	"logwisp/internal/core"
+	"logwisp/internal/plugin"
+	"logwisp/internal/session"
+	"logwisp/internal/source"
+
+	lconfig "github.com/lixenwraith/config"
+	"github.com/lixenwraith/log"
+)
+
+func init() {
+	if err := plugin.RegisterSource("tcp_chain", NewTCPChainSourcePlugin); err != nil {
+		panic(fmt.Sprintf("failed to register tcp_chain source: %v", err))
+	}
+}
+
+const (
+	DefaultChainSourceBufferSize     = 1000
+	DefaultChainSourceHelloTimeoutMS = 10000
+)
+
+// TCPChainSource accepts connections from upstream tcp_chain sinks and ingests NDJSON entries
+type TCPChainSource struct {
+	id     string
+	proxy  *session.Proxy
+	config *config.TCPChainSourceOptions
+
+	subscribers []chan core.LogEntry
+	listener    net.Listener
+	conns       map[net.Conn]struct{}
+	logger      *log.Logger
+
+	mu     sync.RWMutex
+	ctx    context.Context
+	cancel context.CancelFunc
+	wg     sync.WaitGroup
+
+	startTime      time.Time
+	totalEntries   atomic.Uint64
+	droppedEntries atomic.Uint64
+	parseErrors    atomic.Uint64
+	rejectedConns  atomic.Uint64
+	activeConns    atomic.Int64
+	lastEntryTime  atomic.Value // time.Time
+}
+
+// NewTCPChainSourcePlugin creates a tcp_chain source through plugin factory
+func NewTCPChainSourcePlugin(
+	id string,
+	configMap map[string]any,
+	logger *log.Logger,
+	proxy *session.Proxy,
+) (source.Source, error) {
+	opts := &config.TCPChainSourceOptions{
+		Host:      "0.0.0.0",
+		TrustNode: true,
+	}
+	if err := lconfig.ScanMap(configMap, opts); err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+	if err := lconfig.Port(opts.Port); err != nil {
+		return nil, fmt.Errorf("port: %w", err)
+	}
+	if opts.BufferSize <= 0 {
+		opts.BufferSize = DefaultChainSourceBufferSize
+	}
+	if opts.HelloTimeoutMS <= 0 {
+		opts.HelloTimeoutMS = DefaultChainSourceHelloTimeoutMS
+	}
+
+	s := &TCPChainSource{
+		id:          id,
+		proxy:       proxy,
+		config:      opts,
+		subscribers: make([]chan core.LogEntry, 0),
+		conns:       make(map[net.Conn]struct{}),
+		logger:      logger,
+	}
+	s.lastEntryTime.Store(time.Time{})
+
+	logger.Info("msg", "TCP chain source initialized",
+		"component", "tcp_chain_source",
+		"instance_id", id,
+		"host", opts.Host,
+		"port", opts.Port)
+	return s, nil
+}
+
+// Capabilities returns supported capabilities
+func (s *TCPChainSource) Capabilities() []core.Capability {
+	// CapTLS/CapAuth added when transport security lands
+	return []core.Capability{
+		core.CapSessionAware,
+		core.CapMultiSession,
+	}
+}
+
+// Subscribe returns a channel for receiving log entries
+func (s *TCPChainSource) Subscribe() <-chan core.LogEntry {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	ch := make(chan core.LogEntry, s.config.BufferSize)
+	s.subscribers = append(s.subscribers, ch)
+	return ch
+}
+
+// Start binds the listener and begins accepting connections
+func (s *TCPChainSource) Start() error {
+	addr := net.JoinHostPort(s.config.Host, strconv.FormatInt(s.config.Port, 10))
+	// IPv4-only
+	ln, err := net.Listen("tcp4", addr)
+	if err != nil {
+		return fmt.Errorf("listen %s: %w", addr, err)
+	}
+	s.listener = ln
+	s.ctx, s.cancel = context.WithCancel(context.Background())
+	s.startTime = time.Now()
+
+	s.wg.Add(1)
+	go s.acceptLoop()
+
+	s.logger.Info("msg", "TCP chain source started",
+		"component", "tcp_chain_source",
+		"instance_id", s.id,
+		"addr", addr)
+	return nil
+}
+
+// Stop closes the listener, all connections, and subscriber channels
+func (s *TCPChainSource) Stop() {
+	if s.cancel != nil {
+		s.cancel()
+	}
+	if s.listener != nil {
+		s.listener.Close()
+	}
+
+	s.mu.Lock()
+	for conn := range s.conns {
+		conn.Close() // unblocks per-connection reads
+	}
+	s.mu.Unlock()
+
+	s.wg.Wait()
+
+	s.mu.Lock()
+	for _, ch := range s.subscribers {
+		close(ch)
+	}
+	s.mu.Unlock()
+
+	s.logger.Info("msg", "TCP chain source stopped",
+		"component", "tcp_chain_source",
+		"instance_id", s.id)
+}
+
+// GetStats returns the source's statistics
+func (s *TCPChainSource) GetStats() source.SourceStats {
+	lastEntry, _ := s.lastEntryTime.Load().(time.Time)
+	return source.SourceStats{
+		ID:             s.id,
+		Type:           "tcp_chain",
+		TotalEntries:   s.totalEntries.Load(),
+		DroppedEntries: s.droppedEntries.Load(),
+		StartTime:      s.startTime,
+		LastEntryTime:  lastEntry,
+		Details: map[string]any{
+			"host":               s.config.Host,
+			"port":               s.config.Port,
+			"active_connections": s.activeConns.Load(),
+			"rejected_conns":     s.rejectedConns.Load(),
+			"parse_errors":       s.parseErrors.Load(),
+			"trust_node":         s.config.TrustNode,
+		},
+	}
+}
+
+// acceptLoop accepts upstream connections until listener close
+func (s *TCPChainSource) acceptLoop() {
+	defer s.wg.Done()
+	for {
+		conn, err := s.listener.Accept()
+		if err != nil {
+			if errors.Is(err, net.ErrClosed) || s.ctx.Err() != nil {
+				return
+			}
+			s.logger.Warn("msg", "Accept error",
+				"component", "tcp_chain_source",
+				"error", err)
+			continue
+		}
+
+		if s.config.MaxConnections > 0 && s.activeConns.Load() >= s.config.MaxConnections {
+			s.rejectedConns.Add(1)
+			conn.Close()
+			continue
+		}
+
+		s.mu.Lock()
+		s.conns[conn] = struct{}{}
+		s.mu.Unlock()
+
+		s.wg.Add(1)
+		go s.handleConn(conn)
+	}
+}
+
+// handleConn validates the hello preamble, then streams entries until EOF/error
+func (s *TCPChainSource) handleConn(conn net.Conn) {
+	defer s.wg.Done()
+	remote := conn.RemoteAddr().String()
+	s.activeConns.Add(1)
+
+	var sessID string
+	defer func() {
+		conn.Close()
+		s.mu.Lock()
+		delete(s.conns, conn)
+		s.mu.Unlock()
+		if sessID != "" {
+			s.proxy.RemoveSession(sessID)
+		}
+		s.activeConns.Add(-1)
+	}()
+
+	scanner := bufio.NewScanner(conn)
+	// Oversized line (> MaxLogEntryBytes) is a protocol violation; scanner is
+	// unrecoverable after ErrTooLong, connection terminates
+	scanner.Buffer(make([]byte, 0, 64*1024), core.MaxLogEntryBytes)
+
+	// Hello preamble
+	conn.SetReadDeadline(time.Now().Add(time.Duration(s.config.HelloTimeoutMS) * time.Millisecond))
+	if !scanner.Scan() {
+		s.logger.Warn("msg", "Connection closed before hello",
+			"component", "tcp_chain_source",
+			"remote_addr", remote,
+			"error", scanner.Err())
+		return
+	}
+	hello, err := chain.DecodeHello(scanner.Bytes())
+	if err != nil {
+		s.logger.Warn("msg", "Rejected chain connection",
+			"component", "tcp_chain_source",
+			"remote_addr", remote,
+			"error", err)
+		return
+	}
+
+	connNode := hello.Node
+	if connNode == "" || !s.config.TrustNode {
+		if host, _, splitErr := net.SplitHostPort(remote); splitErr == nil {
+			connNode = host
+		} else {
+			connNode = remote
+		}
+	}
+
+	sess := s.proxy.CreateSession(remote, map[string]any{
+		"type": "tcp_chain",
+		"node": connNode,
+	})
+	sessID = sess.ID
+
+	s.logger.Info("msg", "Chain connection established",
+		"component", "tcp_chain_source",
+		"remote_addr", remote,
+		"node", connNode)
+
+	idle := time.Duration(s.config.ReadTimeoutMS) * time.Millisecond
+	for {
+		if idle > 0 {
+			conn.SetReadDeadline(time.Now().Add(idle))
+		} else {
+			conn.SetReadDeadline(time.Time{})
+		}
+		if !scanner.Scan() {
+			if err := scanner.Err(); err != nil && !errors.Is(err, net.ErrClosed) {
+				s.logger.Debug("msg", "Chain read terminated",
+					"component", "tcp_chain_source",
+					"remote_addr", remote,
+					"error", err)
+			}
+			return
+		}
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+		s.proxy.UpdateActivity(sessID)
+
+		entry, err := chain.DecodeEntry(line, connNode, s.config.TrustNode)
+		if err != nil {
+			s.parseErrors.Add(1)
+			s.logger.Debug("msg", "Dropped malformed chain entry",
+				"component", "tcp_chain_source",
+				"error", err)
+			continue
+		}
+		s.publish(entry)
+	}
+}
+
+// parseEntry decodes a canonical LogEntry line and applies the node policy
+func (s *TCPChainSource) parseEntry(line []byte, connNode string) (core.LogEntry, bool) {
+	var entry core.LogEntry
+	if err := json.Unmarshal(line, &entry); err != nil {
+		s.parseErrors.Add(1)
+		s.logger.Debug("msg", "Dropped malformed chain entry",
+			"component", "tcp_chain_source",
+			"error", err)
+		return core.LogEntry{}, false
+	}
+	if entry.Time.IsZero() {
+		entry.Time = time.Now()
+	}
+	if entry.Node == "" || !s.config.TrustNode {
+		entry.Node = connNode
+	}
+	entry.RawSize = int64(len(line))
+	return entry, true
+}
+
+// publish sends a log entry to all subscribers
+func (s *TCPChainSource) publish(entry core.LogEntry) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	s.totalEntries.Add(1)
+	s.lastEntryTime.Store(entry.Time)
+
+	for _, ch := range s.subscribers {
+		select {
+		case ch <- entry:
+		default:
+			s.droppedEntries.Add(1)
+		}
+	}
+}