feat(config): AutoConf with "auto" placeholders

boxo/autoconfig/README.md

@@ -0,0 +1,162 @@
+# AutoConfig Library
+
+This package provides a client library for fetching and caching IPFS autoconfig.json files. It's designed to be generic and self-contained for easy extraction to the boxo library later.
+
+## Features
+
+- **HTTP Client**: Configurable HTTP client with timeout, user-agent, and TLS options
+- **Caching**: Intelligent caching with ETag/Last-Modified support and version rotation
+- **Version Management**: Automatic cleanup of old cached versions
+- **Path Safety**: Sanitized cache directory structure based on URL hostname
+- **Error Handling**: Graceful fallback to cached versions when remote fetch fails
+
+## Usage
+
+### Basic Usage
+
+```go
+import "github.com/ipfs/kubo/boxo/autoconfig"
+
+// Create a client with default options
+client, err := autoconfig.NewClient()
+if err != nil {
+    return err
+}
+
+// Fetch the latest config
+config, err := client.GetLatest(ctx, "https://config.ipfs-mainnet.org/autoconfig.json")
+if err != nil {
+    return err
+}
+
+// Use the config
+fmt.Printf("Bootstrap peers: %v\n", config.Bootstrap)
+```
+
+### With Custom Options
+
+```go
+client, err := autoconfig.NewClient(
+    autoconfig.WithCacheDir("/path/to/cache"),
+    autoconfig.WithUserAgent("my-app/1.0"),
+    autoconfig.WithCacheSize(5),
+    autoconfig.WithTimeout(10*time.Second),
+)
+```
+
+### Integration with Applications
+
+This library is designed to be integrated into applications that need autoconfig functionality. The client is generic and does not depend on any specific application framework.
+
+```go
+func main() {
+    client, err := autoconfig.NewClient(
+        autoconfig.WithCacheDir("/app/data/autoconfig"),
+        autoconfig.WithUserAgent("myapp/1.2.3"),
+        autoconfig.WithTimeout(10*time.Second),
+    )
+    if err != nil {
+        panic(err)
+    }
+
+    config, err := client.GetLatest(context.Background(), "https://config.ipfs-mainnet.org/autoconfig.json")
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Printf("Bootstrap peers: %v\n", config.Bootstrap)
+    fmt.Printf("DNS resolvers: %v\n", config.DNSResolvers)
+}
+```
+
+### Background Updates
+
+For applications that need periodic config updates, use the background updater:
+
+```go
+func main() {
+    client, err := autoconfig.NewClient(
+        autoconfig.WithCacheDir("/app/data/autoconfig"),
+        autoconfig.WithUserAgent("myapp/1.2.3"),
+    )
+    if err != nil {
+        panic(err)
+    }
+
+    // Create background updater with custom callbacks
+    updater, err := autoconfig.NewBackgroundUpdater(client, "https://config.ipfs-mainnet.org/autoconfig.json",
+        autoconfig.WithUpdateInterval(6*time.Hour), // Check every 6 hours
+        autoconfig.WithOnVersionChange(func(oldVersion, newVersion int64, configURL string) {
+            fmt.Printf("New config version %d available (was %d) - consider restarting\n", newVersion, oldVersion)
+        }),
+        autoconfig.WithOnUpdateSuccess(func(resp *autoconfig.AutoConfigResponse) {
+            fmt.Printf("Updated config cache at %s\n", resp.FetchTime.Format(time.RFC3339))
+        }),
+        autoconfig.WithOnUpdateError(func(err error) {
+            fmt.Printf("Update failed: %v\n", err)
+        }),
+    )
+    if err != nil {
+        panic(err)
+    }
+
+    ctx := context.Background()
+    if err := updater.Start(ctx); err != nil {
+        panic(err)
+    }
+    defer updater.Stop()
+
+    // Your application logic here...
+    select {}
+}
+```
+
+## Cache Structure
+
+The cache is organized by hostname and version:
+
+```
+$CACHE_DIR/
+  autoconfig/
+    config.ipfs-mainnet.org/
+      2025071801.json
+      2025071802.json
+      .etag
+      .last-modified
+```
+
+## Configuration Options
+
+### Client Options
+- `WithCacheDir(dir)`: Set custom cache directory
+- `WithHTTPClient(client)`: Use custom HTTP client
+- `WithCacheSize(n)`: Set maximum cached versions (default: 3)
+- `WithUserAgent(ua)`: Set HTTP user-agent
+- `WithTimeout(duration)`: Set HTTP timeout (default: 5s)
+- `WithTLSInsecureSkipVerify(bool)`: Skip TLS verification (for testing)
+
+### Background Updater Options
+- `WithUpdateInterval(duration)`: Set update check interval (default: 24h)
+- `WithOnVersionChange(callback)`: Called when new config version is detected
+- `WithOnUpdateSuccess(callback)`: Called on successful update for metadata persistence
+- `WithOnUpdateError(callback)`: Called when update fails
+
+## Error Handling
+
+The client implements graceful fallback:
+1. Try to fetch from remote URL
+2. If remote fails, fall back to latest cached version
+3. If no cache exists, fall back to hardcoded defaults (when using `MustGetConfigWithMainnetFallbacks`)
+
+Note: `GetLatest()` returns errors, while `MustGetConfigWithMainnetFallbacks()` never fails and always returns usable configuration.
+
+## Testing
+
+Run tests with:
+```bash
+go test .
+```
+
+## Future Extraction
+
+This package is designed to be extracted to `github.com/ipfs/boxo` with no changes needed. It has no application-specific dependencies.

boxo/autoconfig/autoconfig.go

@@ -0,0 +1,4 @@
+package autoconfig
+
+// This file exists to maintain backwards compatibility during the transition.
+// All Kubo-specific client functions have been moved to github.com/ipfs/kubo/config

boxo/autoconfig/client.go

@@ -0,0 +1,187 @@
+package autoconfig
+
+import (
+	"crypto/tls"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	logging "github.com/ipfs/go-log/v2"
+)
+
+var log = logging.Logger("autoconfig")
+
+const (
+	defaultTimeout         = 5 * time.Second
+	defaultCacheSize       = 3
+	defaultMaxResponseSize = 2 * 1024 * 1024 // 2MiB
+	etagFile               = ".etag"
+	lastModifiedFile       = ".last-modified"
+)
+
+// Client is the autoconfig client
+type Client struct {
+	httpClient      *http.Client
+	cacheDir        string
+	cacheSize       int
+	userAgent       string
+	maxResponseSize int64
+}
+
+// Option is a function that configures the client
+type Option func(*Client) error
+
+// NewClient creates a new autoconfig client with the given options
+func NewClient(options ...Option) (*Client, error) {
+	c := &Client{
+		httpClient:      &http.Client{Timeout: defaultTimeout},
+		cacheSize:       defaultCacheSize,
+		maxResponseSize: defaultMaxResponseSize,
+	}
+
+	for _, opt := range options {
+		if err := opt(c); err != nil {
+			return nil, fmt.Errorf("failed to apply option: %w", err)
+		}
+	}
+
+	// Use temp dir if no cache dir provided
+	if c.cacheDir == "" {
+		tmpDir, err := os.MkdirTemp("", "ipfs-autoconfig-")
+		if err != nil {
+			return nil, fmt.Errorf("failed to create temp dir: %w", err)
+		}
+		c.cacheDir = tmpDir
+		log.Debugf("using temporary cache directory: %s", tmpDir)
+	}
+
+	return c, nil
+}
+
+// WithHTTPClient sets a custom HTTP client
+func WithHTTPClient(client *http.Client) Option {
+	return func(c *Client) error {
+		if client == nil {
+			return fmt.Errorf("http client cannot be nil")
+		}
+		c.httpClient = client
+		return nil
+	}
+}
+
+// WithCacheDir sets the cache directory
+func WithCacheDir(dir string) Option {
+	return func(c *Client) error {
+		c.cacheDir = dir
+		return nil
+	}
+}
+
+// WithCacheSize sets the maximum number of versions to keep in cache
+func WithCacheSize(size int) Option {
+	return func(c *Client) error {
+		if size < 1 {
+			return fmt.Errorf("cache size must be at least 1")
+		}
+		c.cacheSize = size
+		return nil
+	}
+}
+
+// WithUserAgent sets the user agent for HTTP requests
+func WithUserAgent(ua string) Option {
+	return func(c *Client) error {
+		c.userAgent = ua
+		return nil
+	}
+}
+
+// WithTimeout sets the HTTP client timeout
+func WithTimeout(timeout time.Duration) Option {
+	return func(c *Client) error {
+		c.httpClient.Timeout = timeout
+		return nil
+	}
+}
+
+// WithTLSInsecureSkipVerify sets whether to skip TLS verification (for testing)
+func WithTLSInsecureSkipVerify(skip bool) Option {
+	return func(c *Client) error {
+		if skip {
+			log.Warnf("TLS certificate verification is disabled - this should only be used for testing")
+		}
+		if c.httpClient.Transport == nil {
+			c.httpClient.Transport = http.DefaultTransport.(*http.Transport).Clone()
+		}
+		if t, ok := c.httpClient.Transport.(*http.Transport); ok {
+			if t.TLSClientConfig == nil {
+				t.TLSClientConfig = &tls.Config{}
+			}
+			t.TLSClientConfig.InsecureSkipVerify = skip
+		}
+		return nil
+	}
+}
+
+// sanitizeForPath sanitizes a string to be safe for use in file paths
+func sanitizeForPath(s string) string {
+	// Replace any character that's not alphanumeric, dash, underscore, or dot
+	re := regexp.MustCompile(`[^a-zA-Z0-9\-_\.]`)
+	sanitized := re.ReplaceAllString(s, "_")
+	// Replace consecutive dots with a single underscore
+	re2 := regexp.MustCompile(`\.{2,}`)
+	return re2.ReplaceAllString(sanitized, "_")
+}
+
+// getCacheDir returns the cache directory for a given URL
+func (c *Client) getCacheDir(configURL string) (string, error) {
+	u, err := url.Parse(configURL)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse URL: %w", err)
+	}
+
+	host := sanitizeForPath(u.Host)
+	return filepath.Join(c.cacheDir, "autoconfig", host), nil
+}
+
+// readCachedMetadata reads cached ETag and Last-Modified values
+func (c *Client) readCachedMetadata(cacheDir string) (etag, lastModified string) {
+	// Sanitize cache directory path
+	cleanCacheDir := filepath.Clean(cacheDir)
+
+	etagData, err := os.ReadFile(filepath.Join(cleanCacheDir, etagFile))
+	if err != nil {
+		log.Debugf("failed to read cached etag: %v", err)
+	}
+
+	lastModData, err := os.ReadFile(filepath.Join(cleanCacheDir, lastModifiedFile))
+	if err != nil {
+		log.Debugf("failed to read cached last-modified: %v", err)
+	}
+
+	return strings.TrimSpace(string(etagData)), strings.TrimSpace(string(lastModData))
+}
+
+// writeCachedMetadata writes ETag and Last-Modified values to cache
+func (c *Client) writeCachedMetadata(cacheDir, etag, lastModified string) error {
+	// Sanitize cache directory path
+	cleanCacheDir := filepath.Clean(cacheDir)
+	if etag != "" {
+		// Use owner-only permissions (0600) for security
+		if err := os.WriteFile(filepath.Join(cleanCacheDir, etagFile), []byte(etag), 0600); err != nil {
+			return fmt.Errorf("failed to write etag: %w", err)
+		}
+	}
+	if lastModified != "" {
+		// Use owner-only permissions (0600) for security
+		if err := os.WriteFile(filepath.Join(cleanCacheDir, lastModifiedFile), []byte(lastModified), 0600); err != nil {
+			return fmt.Errorf("failed to write last-modified: %w", err)
+		}
+	}
+	return nil
+}