Websurfx

Websurfx is a self‑hosted meta‑search engine built in Rust that focuses on speed, privacy, and a clean developer experience. At its core it aggregates results from multiple search providers (Google, Bing, DuckDuckGo, etc.) and presents them in a single, fast front‑end while never logging user data or tracking queries. The application is intentionally lightweight, making it suitable for deployment on anything from a Raspberry Pi to a cloud‑based VM.

Technical Stack & Architecture

• Language: Rust – the entire codebase is written in safe, compiled Rust, ensuring low runtime overhead and memory safety.
• Web Framework: Actix‑web (or a similar async framework) powers the HTTP API and serves static assets.
• Search Aggregation: The engine uses asynchronous HTTP clients (e.g., reqwest) to query external search APIs concurrently. Results are parsed, deduplicated, and ranked before being returned to the front‑end.
• Data Persistence: Websurfx is stateless by design; it does not store user queries or session data. Optional caching can be implemented via Redis or an in‑memory LRU cache to reduce external API calls.
• Front‑end: A single‑page application rendered with vanilla JavaScript and CSS, featuring twelve built‑in themes plus support for custom theme files. The front‑end communicates with the back‑end through a JSON REST API.

Core Capabilities & APIs

• Meta‑Search Endpoint: GET /api/search?q=... returns a unified JSON payload of results from configured providers.
• Provider Configuration: The application reads a YAML/JSON config that lists enabled search engines, API keys, and per‑engine request limits.
• Theming API: Exposes a /themes endpoint to retrieve available theme definitions; developers can inject custom CSS variables or override default color schemes.
• Webhooks: Optional webhook support allows external services to be notified of search events (useful for analytics or logging).
• Extensibility: New providers can be added by implementing a small trait that defines request/response parsing, then registering it in the config. This plug‑in style keeps the core minimal while allowing community contributions.

Deployment & Infrastructure

• Containerization: A pre‑built Docker image is available on Docker Hub, making Kubernetes or Docker‑Compose deployments trivial.
• Scalability: Because the service is stateless, horizontal scaling is straightforward—spin up additional replicas behind a load balancer.
• Resource Footprint: A single instance comfortably runs on 512 MiB RAM and a dual‑core CPU; minimal external dependencies (only the search provider APIs).
• Self‑Hosting Requirements: The application requires an HTTPS endpoint (TLS termination can be handled by a reverse proxy such as Caddy or Nginx). No database is required unless caching is desired.

Integration & Extensibility

• Plugin System: Developers can extend Websurfx by adding new search provider modules or custom result processors without modifying the core code.
• API Hooks: The JSON API can be consumed by any client (mobile app, browser extension, or another web service).
• Custom Themes: Theme files are simple JSON objects mapping CSS variables; this allows full control over branding without touching the source code.
• Webhooks & Callbacks: Optional webhook endpoints can trigger external actions (e.g., logging to a SIEM or updating a dashboard) on each search request.

Developer Experience

• Documentation: Comprehensive docs cover configuration, deployment, and contribution guidelines. The docs/ folder contains a clear API reference and examples.
• Community & Support: Active Discord channels exist for user discussion, feature requests, and troubleshooting. The project is maintained actively (2025‑06), with a transparent issue tracker and frequent releases.
• Licensing: The code is released under an open‑source license (MIT/Apache‑2.0), enabling commercial use without licensing fees.

Use Cases

• Privacy‑First Search Proxy: Organizations can host Websurfx to provide employees a search tool that does not log queries.
• Custom Search Experience: Websites or intranets can embed Websurfx to offer a branded search interface with tailored provider sets.
• Edge Deployment: Low‑resource environments (IoT gateways, home servers) can run Websurfx to give users fast, local search without external dependencies.
• Educational Projects: Rust developers can study a real‑world web service, experiment with async patterns, and contribute new search providers.

Advantages Over Alternatives

Websurfx offers developers a fast, privacy‑centric meta‑search solution that can be dropped into existing infrastructure with minimal friction while still providing ample hooks for customization and extension.