feat: migrate from env vars to config.toml

- Add internal/config package with TOML parsing (BurntSushi/toml)
- Create config.example.toml documenting all settings
- Update main.go to load config via -config flag (default: config.toml)
- Environment variables remain as fallback overrides for backward compat
- Config file values are used as defaults; env vars override when set
- Add comprehensive tests for file loading, defaults, and env overrides
- Add config.toml to .gitignore (secrets stay local)

internal/config/config.go

@@ -0,0 +1,130 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/BurntSushi/toml"
+)
+
+// Config is the top-level configuration for the gosearch service.
+type Config struct {
+	Server  ServerConfig  `toml:"server"`
+	Upstream UpstreamConfig `toml:"upstream"`
+	Engines EnginesConfig `toml:"engines"`
+}
+
+type ServerConfig struct {
+	Port        int    `toml:"port"`
+	HTTPTimeout string `toml:"http_timeout"`
+}
+
+type UpstreamConfig struct {
+	URL string `toml:"url"`
+}
+
+type EnginesConfig struct {
+	LocalPorted []string   `toml:"local_ported"`
+	Brave       BraveConfig `toml:"brave"`
+	Qwant       QwantConfig `toml:"qwant"`
+}
+
+type BraveConfig struct {
+	APIKey       string `toml:"api_key"`
+	AccessToken  string `toml:"access_token"`
+}
+
+type QwantConfig struct {
+	Category       string `toml:"category"`
+	ResultsPerPage int    `toml:"results_per_page"`
+}
+
+// Load reads configuration from the given TOML file path.
+// If the file does not exist, it returns defaults (empty values where applicable).
+// Environment variables are used as fallbacks for any zero-value fields.
+func Load(path string) (*Config, error) {
+	cfg := defaultConfig()
+
+	if _, err := os.Stat(path); err == nil {
+		if _, err := toml.DecodeFile(path, &cfg); err != nil {
+			return nil, fmt.Errorf("parse config %s: %w", path, err)
+		}
+	}
+
+	applyEnvOverrides(cfg)
+	return cfg, nil
+}
+
+func defaultConfig() *Config {
+	return &Config{
+		Server: ServerConfig{
+			Port:        8080,
+			HTTPTimeout: "10s",
+		},
+		Upstream: UpstreamConfig{},
+		Engines: EnginesConfig{
+			LocalPorted: []string{"wikipedia", "arxiv", "crossref", "braveapi", "qwant"},
+			Qwant: QwantConfig{
+				Category:       "web-lite",
+				ResultsPerPage: 10,
+			},
+		},
+	}
+}
+
+// applyEnvOverrides fills any zero-value fields from environment variables.
+// This preserves backward compatibility: existing deployments using env vars
+// continue to work without a config file.
+func applyEnvOverrides(cfg *Config) {
+	if v := os.Getenv("PORT"); v != "" {
+		fmt.Sscanf(v, "%d", &cfg.Server.Port)
+	}
+	if v := os.Getenv("HTTP_TIMEOUT"); v != "" {
+		cfg.Server.HTTPTimeout = v
+	}
+	if v := os.Getenv("UPSTREAM_SEARXNG_URL"); v != "" {
+		cfg.Upstream.URL = v
+	}
+	if v := os.Getenv("LOCAL_PORTED_ENGINES"); v != "" {
+		parts := splitCSV(v)
+		if len(parts) > 0 {
+			cfg.Engines.LocalPorted = parts
+		}
+	}
+	if v := os.Getenv("BRAVE_API_KEY"); v != "" {
+		cfg.Engines.Brave.APIKey = v
+	}
+	if v := os.Getenv("BRAVE_ACCESS_TOKEN"); v != "" {
+		cfg.Engines.Brave.AccessToken = v
+	}
+}
+
+// HTTPTimeout parses the configured timeout string into a time.Duration.
+func (c *Config) HTTPTimeout() time.Duration {
+	if d, err := time.ParseDuration(c.Server.HTTPTimeout); err == nil && d > 0 {
+		return d
+	}
+	return 10 * time.Second
+}
+
+// LocalPortedCSV returns the local ported engines as a comma-separated string.
+func (c *Config) LocalPortedCSV() string {
+	return strings.Join(c.Engines.LocalPorted, ",")
+}
+
+func splitCSV(s string) []string {
+	if s == "" {
+		return nil
+	}
+	parts := strings.Split(s, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		if p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}