NAME
Net::Async::WebSearch::Provider - Base class for Net::Async::WebSearch providers
VERSION
version 0.002
SYNOPSIS
package Net::Async::WebSearch::Provider::Foo;
use parent 'Net::Async::WebSearch::Provider';
use Future;
use Net::Async::WebSearch::Result;
sub search {
my ( $self, $http, $query, $opts ) = @_;
# ... build HTTP::Request, dispatch via $http->do_request(...)
# return Future->done([ Net::Async::WebSearch::Result->new(...), ... ]);
}DESCRIPTION
Base class for search providers. Subclasses override search and return a Future that resolves to an arrayref of Net::Async::WebSearch::Result objects in provider-native rank order.
The same Net::Async::HTTP client is shared by every provider attached to a Net::Async::WebSearch, so providers should not build their own HTTP pipelines.
name
Provider short name (used in allow/deny lists). Defaults to the lowercased leaf package name. Read/write — "add_provider" in Net::Async::WebSearch auto-renames a provider (name#2, name#3...) when a stacked instance would otherwise collide with an existing registered name.
enabled
Boolean. Disabled providers are skipped by Net::Async::WebSearch regardless of per-query only/exclude.
tags
Arrayref of tag strings. Tags are matched by only/exclude and provider_opts keys alongside the provider's name — so you can group multiple stacked instances (e.g. tag every paid API as paid, tag a set of private SearxNGs as private) and select/deselect them together.
default_name
Lowercased leaf package name. Used by name when no explicit name was passed to new.
has_tag($tag)
True if this provider carries $tag.
matches($selector)
True if $selector equals this provider's name, its class leaf (lowercased), or one of its tags. Used internally by Net::Async::WebSearch for only/exclude/provider_opts resolution.
search($http, $query, \%opts)
Abstract. $http is a Net::Async::HTTP. $query is the search string. %opts carries limit, language, region, safesearch, and any provider-specific overrides from the caller. Return a Future of arrayref of Net::Async::WebSearch::Result.
user_agent_string
Default User-Agent used if the provider needs to build its own request.
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-websearch/issues.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de> https://raudss.us/
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.