duck_search 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b30f0ccc51c4d05deef7e46119c461ab3f4d1267c7ba617e7385f24aa61ea4c4
+  data.tar.gz: eb98b71458dea2141e75467a942bf5ccf5cbfb3c72c3165cfd20af81ad9cfa7e
+SHA512:
+  metadata.gz: e512526190e909700a253240d032a77db2502301eb1599328c4f1bd4b46047f67b5ef3339c6db68e3e557fe7741b6b85f126f56c316c4b4a1afa683e3aa0b4ab
+  data.tar.gz: 34d234bab472e6e3db41deda79047f841cf3d443ab01c11b1c27948b0b450810be8f6acd582ff95bb0aebd569bad096b6e678b82775faf9610db12e7e8d95f1a

data/README.md

@@ -0,0 +1,13 @@
+# DuckSearch
+
+Lightweight DuckDuckGo HTML search client. Fetches and parses DuckDuckGo's no-JS HTML search endpoint, returning titles, snippets, and decoded URLs. No API key required.
+
+## Usage
+
+```ruby
+client = DuckSearch::Client.new
+results = client.search("FG0326 specifications")
+results.each do |r|
+  puts "#{r.title} - #{r.url}"
+end
+```

data/lib/duck_search/client.rb

@@ -0,0 +1,96 @@
+require "uri"
+require "cgi"
+require "faraday/retry"
+
+module DuckSearch
+  class Client
+    BASE_URL = "https://html.duckduckgo.com"
+    SEARCH_PATH = "/html"
+    DEFAULT_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    RESULT_CAP = 5
+
+    attr_reader :proxy, :timeout, :open_timeout, :user_agent
+
+    def initialize(proxy: nil, timeout: 15, open_timeout: 10, user_agent: DEFAULT_USER_AGENT)
+      @proxy = proxy
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @user_agent = user_agent
+    end
+
+    def search(query)
+      response = connection.post(SEARCH_PATH) do |req|
+        req.headers["User-Agent"] = user_agent
+        req.headers["DNT"] = "1"
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(
+          q: query,
+          b: "",
+          kf: "-1",
+          kh: "1",
+          kp: "1",
+          k1: "-1"
+        )
+      end
+
+      raise HttpError.new("DuckDuckGo returned HTTP #{response.status}",
+                           status: response.status,
+                           url: "#{BASE_URL}#{SEARCH_PATH}") unless response.success?
+
+      parse_html(response.body)
+    rescue Faraday::Error => e
+      raise HttpError.new("DuckDuckGo connection failed: #{e.message}",
+                           url: "#{BASE_URL}#{SEARCH_PATH}")
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |f|
+        f.proxy = proxy if proxy
+        f.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                  retry_statuses: [429, 500, 502, 503, 504],
+                  methods: [:post]
+        f.options.timeout = timeout
+        f.options.open_timeout = open_timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def parse_html(html_body)
+      return [] if html_body.nil? || html_body.strip.empty?
+
+      doc = Nokogiri::HTML(html_body)
+
+      results = doc.css(".result").map do |node|
+        anchor = node.at_css(".result__a")
+        snippet_node = node.at_css(".result__snippet")
+
+        next unless anchor
+
+        DuckSearch::Result.new(
+          title:       anchor.text.strip,
+          description: snippet_node&.text&.strip || "",
+          url:         clean_url(anchor["href"])
+        )
+      end.compact
+
+      results.first(RESULT_CAP)
+    end
+
+    def clean_url(href)
+      return nil if href.nil? || href.strip.empty?
+
+      if href.include?("uddg=")
+        parsed = URI.parse(href.start_with?("http") ? href : "https:#{href}")
+        params = URI.decode_www_form(parsed.query || "")
+        uddg = params.find { |k, _| k == "uddg" }
+        uddg ? CGI.unescape(uddg[1]) : href
+      else
+        href.strip
+      end
+    rescue URI::InvalidURIError
+      href
+    end
+  end
+end

data/lib/duck_search/errors.rb

@@ -0,0 +1,15 @@
+module DuckSearch
+  class Error < StandardError; end
+
+  class HttpError < Error
+    attr_reader :status, :url
+
+    def initialize(message = nil, status: nil, url: nil)
+      @status = status
+      @url = url
+      super(message || "DuckDuckGo request failed (HTTP #{status})")
+    end
+  end
+
+  class ParseError < Error; end
+end

data/lib/duck_search/result.rb

@@ -0,0 +1,3 @@
+module DuckSearch
+  Result = Struct.new(:title, :description, :url, keyword_init: true)
+end

data/lib/duck_search.rb

@@ -0,0 +1,10 @@
+require "faraday"
+require "nokogiri"
+
+require_relative "duck_search/errors"
+require_relative "duck_search/result"
+require_relative "duck_search/client"
+
+module DuckSearch
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: duck_search
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wenmar Pro
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.18.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.18.0
+description: Fetches and parses DuckDuckGo's no-JS HTML search results. Returns titles,
+  snippets, and URLs. No API key required.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/duck_search.rb
+- lib/duck_search/client.rb
+- lib/duck_search/errors.rb
+- lib/duck_search/result.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Lightweight DuckDuckGo HTML search client
+test_files: []