fetch

Documentation

Overview

Package fetch retrieves remote resources (subscriptions, rulesets, base configs) with three concerns airports impose on us:

1. User-Agent gating — many panels only return nodes for a clash-like UA.
2. Upstream proxy — some airports are only reachable through a proxy; the converter host itself may be unable to reach them directly.
3. Cloudflare challenge — when a "Just a moment" interstitial is detected we fall back to a FlareSolverr instance to obtain a cf_clearance cookie and replay the request through the same egress.

See docs/proxy.md and docs/cloudflare.md.

Index

• type Cache
  • func NewCache(ttl time.Duration) *Cache
  • func (c *Cache) Flush()
  • func (c *Cache) Len() int
• type Client
  • func New(opts Options) (*Client, error)
  • func (c *Client) FlushCache()
  • func (c *Client) Get(ctx context.Context, target string) ([]byte, error)
  • func (c *Client) GetWithMeta(ctx context.Context, target string) ([]byte, http.Header, error)
• type Options

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a thread-safe, in-memory TTL cache for successful GET responses, keyed by URL. Entries retain both the body and the response headers so metadata (e.g. Subscription-Userinfo) survives a cache hit.

The cache is keyed by URL only; it deliberately ignores per-request proxy differences. Callers that need a fresh fetch must bypass (use a Client with caching disabled) or Flush the cache.

func NewCache

func NewCache(ttl time.Duration) *Cache

NewCache creates a cache with the given TTL.

func (*Cache) Flush

func (c *Cache) Flush()

Flush removes all entries.

func (*Cache) Len

func (c *Cache) Len() int

Len reports the number of stored entries (including possibly-expired ones).

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client fetches URLs applying the configured access strategy.

func New

func New(opts Options) (*Client, error)

New builds a Client. proxyOverride, when non-empty, replaces opts.Proxy (used for per-request &proxy= overrides).

func (*Client) FlushCache

func (c *Client) FlushCache()

FlushCache clears all cached entries. Safe to call when caching is disabled.

func (*Client) Get

func (c *Client) Get(ctx context.Context, target string) ([]byte, error)

Get retrieves target, transparently solving a Cloudflare challenge if one is detected and a FlareSolverr endpoint is configured. It honours the TTL cache.

func (*Client) GetWithMeta

func (c *Client) GetWithMeta(ctx context.Context, target string) ([]byte, http.Header, error)

GetWithMeta is like Get but also returns the response headers of the final (origin or FlareSolverr-replay) response. Callers use this to capture airport metadata such as the Subscription-Userinfo header.

Caching: successful (200, non-empty) responses are cached by URL. Cached entries also retain their headers so repeated reads see Subscription-Userinfo. Pass a context value (see NoCache) is not used here; cache bypass is decided by the caller wiring a Client with caching disabled or by clearing the cache.

type Options

type Options struct {
	UserAgent       string        // default: clash.meta UA
	Proxy           string        // http(s):// or socks5:// upstream proxy URL
	FlareSolverrURL string        // e.g. http://127.0.0.1:8191/v1 (empty disables)
	Timeout         time.Duration // per-request timeout (default 30s)
	MaxRetries      int           // network retry attempts (default 2)

	// CacheTTL controls the in-memory TTL cache for successful GETs:
	//   0  => use defaultCacheTTL (300s)
	//   <0 => caching disabled
	//   >0 => that TTL
	CacheTTL time.Duration

	// Cache, when non-nil, is a shared cache injected by the caller (e.g. the
	// HTTP server reuses one cache across per-request Clients). When nil, New
	// creates a per-Client cache (unless caching is disabled).
	Cache *Cache
}

Options configures a single Client. Zero values fall back to sensible defaults in New.