Improve agent-facing history endpoints (Phase 1)

- Fix /api/history/{type} to search the full persistent store instead of
  only the bounded in-memory ring buffer, so filtered history isn't
  silently truncated.
- Add structured type/since/until filters to /api/history/search and
  /api/history/wait, alongside the existing free-text query.
- Add GET /api/traces/{traceId} to fetch all entries for a trace in one
  call instead of relying on substring search.
- Rate-limit /api/history/wait per client IP.
- Add docs/PLAN.md tracking the phased improvement plan; update README
  and agents_example.md for the new/changed endpoints.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

internal/storage/file_store.go

@@ -42,11 +42,40 @@ func (fs *FileStore) Append(ctx context.Context, entry websocket.HistoryEntry) e
 
 // GetHistory retrieves historical entries from the file store.
 func (fs *FileStore) GetHistory(ctx context.Context, limit int) ([]websocket.HistoryEntry, error) {
-	return fs.Search(ctx, "", limit)
+	return fs.Search(ctx, SearchOptions{}, limit)
 }
 
-// Search searches for historical entries in the file store matching the query.
-func (fs *FileStore) Search(ctx context.Context, query string, limit int) ([]websocket.HistoryEntry, error) {
+// entryHead is used to cheaply inspect an entry's type/timestamp without
+// unmarshaling the (potentially large) Data payload.
+type entryHead struct {
+	Type      string `json:"type"`
+	Timestamp int64  `json:"timestamp"`
+}
+
+// matches reports whether the given line satisfies the type/time filters in opts.
+// The free-text Query filter is applied separately by the caller against the raw line.
+func (opts SearchOptions) matches(line string) bool {
+	if opts.Type == "" && opts.Since == 0 && opts.Until == 0 {
+		return true
+	}
+	var head entryHead
+	if err := json.Unmarshal([]byte(line), &head); err != nil {
+		return false
+	}
+	if opts.Type != "" && head.Type != opts.Type {
+		return false
+	}
+	if opts.Since != 0 && head.Timestamp < opts.Since {
+		return false
+	}
+	if opts.Until != 0 && head.Timestamp > opts.Until {
+		return false
+	}
+	return true
+}
+
+// Search searches for historical entries in the file store matching opts.
+func (fs *FileStore) Search(ctx context.Context, opts SearchOptions, limit int) ([]websocket.HistoryEntry, error) {
 	if limit <= 0 {
 		limit = 50 // Default to a manageable number
 	}
@@ -70,16 +99,20 @@ func (fs *FileStore) Search(ctx context.Context, query string, limit int) ([]web
 	scanner.Buffer(buf, maxCapacity)
 
 	// Lowercase query for case-insensitive search
-	lowerQuery := strings.ToLower(query)
+	lowerQuery := strings.ToLower(opts.Query)
 
 	for scanner.Scan() {
 		line := scanner.Text()
-		if query == "" || strings.Contains(strings.ToLower(line), lowerQuery) {
-			matchingLines = append(matchingLines, line)
-			// Only keep the most recent 'limit' matches to save memory
-			if len(matchingLines) > limit {
-				matchingLines = matchingLines[1:]
-			}
+		if opts.Query != "" && !strings.Contains(strings.ToLower(line), lowerQuery) {
+			continue
+		}
+		if !opts.matches(line) {
+			continue
+		}
+		matchingLines = append(matchingLines, line)
+		// Only keep the most recent 'limit' matches to save memory
+		if len(matchingLines) > limit {
+			matchingLines = matchingLines[1:]
 		}
 	}
 

internal/storage/file_store_test.go

@@ -50,7 +50,7 @@ func TestFileStore(t *testing.T) {
 	}
 
 	// Test Search
-	results, err := fs.Search(ctx, "hello", 10)
+	results, err := fs.Search(ctx, SearchOptions{Query: "hello"}, 10)
 	if err != nil {
 		t.Fatalf("Search failed: %v", err)
 	}
@@ -64,3 +64,56 @@ func TestFileStore(t *testing.T) {
         t.Errorf("unexpected data content: %s", string(data))
     }
 }
+
+func TestFileStoreSearchFilters(t *testing.T) {
+	filename := "test-otel-filters.log"
+	defer func() {
+		_ = os.Remove(filename)
+	}()
+
+	fs := NewFileStore(filename)
+	ctx := context.Background()
+
+	entries := []websocket.HistoryEntry{
+		{Type: "logs", Timestamp: 100, Data: json.RawMessage(`{"msg":"first log"}`)},
+		{Type: "traces", Timestamp: 200, Data: json.RawMessage(`{"msg":"a trace"}`)},
+		{Type: "logs", Timestamp: 300, Data: json.RawMessage(`{"msg":"second log"}`)},
+	}
+	for _, e := range entries {
+		if err := fs.Append(ctx, e); err != nil {
+			t.Fatalf("failed to append entry: %v", err)
+		}
+	}
+
+	// Filter by type only
+	results, err := fs.Search(ctx, SearchOptions{Type: "logs"}, 10)
+	if err != nil {
+		t.Fatalf("Search failed: %v", err)
+	}
+	if len(results) != 2 {
+		t.Fatalf("expected 2 log entries, got %d", len(results))
+	}
+	for _, r := range results {
+		if r.Type != "logs" {
+			t.Errorf("expected type 'logs', got %s", r.Type)
+		}
+	}
+
+	// Filter by time range: only the entry at Timestamp=200 should match
+	results, err = fs.Search(ctx, SearchOptions{Since: 150, Until: 250}, 10)
+	if err != nil {
+		t.Fatalf("Search failed: %v", err)
+	}
+	if len(results) != 1 || results[0].Timestamp != 200 {
+		t.Fatalf("expected single entry at timestamp 200, got %+v", results)
+	}
+
+	// Combine type and query filters
+	results, err = fs.Search(ctx, SearchOptions{Type: "logs", Query: "second"}, 10)
+	if err != nil {
+		t.Fatalf("Search failed: %v", err)
+	}
+	if len(results) != 1 || results[0].Timestamp != 300 {
+		t.Fatalf("expected single entry at timestamp 300, got %+v", results)
+	}
+}

internal/storage/store.go

@@ -5,9 +5,24 @@ import (
 	"git.tornberg.me/go-otel/internal/websocket"
 )
 
+// SearchOptions narrows a Search call beyond the free-text query.
+type SearchOptions struct {
+	// Query is a case-insensitive substring match against the raw entry JSON.
+	Query string
+	// Type restricts results to a single telemetry type (traces, metrics, logs).
+	// Empty matches any type.
+	Type string
+	// Since restricts results to entries with Timestamp >= Since (unix nanoseconds).
+	// Zero means no lower bound.
+	Since int64
+	// Until restricts results to entries with Timestamp <= Until (unix nanoseconds).
+	// Zero means no upper bound.
+	Until int64
+}
+
 // Store interface for telemetry history persistence.
 type Store interface {
 	Append(ctx context.Context, entry websocket.HistoryEntry) error
 	GetHistory(ctx context.Context, limit int) ([]websocket.HistoryEntry, error)
-	Search(ctx context.Context, query string, limit int) ([]websocket.HistoryEntry, error)
+	Search(ctx context.Context, opts SearchOptions, limit int) ([]websocket.HistoryEntry, error)
 }