Perplexed.Search.SearXNG.Instances (Perplexed v0.2.0)

Copy Markdown View Source

The live set of public SearXNG instances, discovered instead of hard-coded. Set searxng_instances: :auto and Perplexed.Search.SearXNG asks this store for its instances.

The store starts empty. The first search that needs it runs Perplexed.Search.SearXNG.Directory.discover/1 (fetch searx.space, filter, probe each start page, seed the pool) and waits for it; searches that arrive meanwhile wait on the same discovery rather than starting their own. After that it refreshes in the background every searxng_refresh_ms (default daily), keeping the last good list if a refresh fails and retrying a failed refresh sooner. Discovery options come from the searxng_discovery setting, such as [countries: ["US", "CA"], max_median_ms: 2_500].

Discovery runs in a task under Perplexed.TaskSupervisor, so a slow searx.space never blocks the store, and a crash in it is logged as a failed refresh. Each finished refresh emits [:perplexed, :searxng, :instances] with count and metadata result.

Summary

Types

status()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

entries(opts \\ [])

Like urls/1, with each instance's directory entry and probe.

refresh(opts \\ [])

Refreshes now. With await: true, waits and returns the entries; otherwise starts the refresh in the background and returns [].

start_link(opts \\ [])

Starts the store. Options: :name (default Perplexed.Search.SearXNG.Instances), :discovery (options for Directory.discover/1, merged over the searxng_discovery setting), :refresh_ms and :retry_ms.

status(opts \\ [])

What the store holds and when it last refreshed.

urls(opts \\ [])

The live instances' URLs, fastest first, discovering them first when the store has never been filled (waiting up to :await_ms, default 120000). Options: :store, :await_ms.

Types

status()

@type status() :: %{
  count: non_neg_integer(),
  refreshed_at: DateTime.t() | nil,
  refreshing?: boolean(),
  last_error: term()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

entries(opts \\ [])

@spec entries(keyword()) :: [Perplexed.Search.SearXNG.Directory.entry()]

Like urls/1, with each instance's directory entry and probe.

refresh(opts \\ [])

@spec refresh(keyword()) :: [Perplexed.Search.SearXNG.Directory.entry()]

Refreshes now. With await: true, waits and returns the entries; otherwise starts the refresh in the background and returns [].

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the store. Options: :name (default Perplexed.Search.SearXNG.Instances), :discovery (options for Directory.discover/1, merged over the searxng_discovery setting), :refresh_ms and :retry_ms.

status(opts \\ [])

@spec status(keyword()) :: status()

What the store holds and when it last refreshed.

urls(opts \\ [])

@spec urls(keyword()) :: [String.t()]

The live instances' URLs, fastest first, discovering them first when the store has never been filled (waiting up to :await_ms, default 120000). Options: :store, :await_ms.