querylane 0.1.0

data/lib/querylane/chips.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Querylane
+  # "Searching for" chips: one per top-level term of a valid query (all name
+  # words share one chip). Sensitive values are masked; nothing here repeats a
+  # sensitive value in clear.
+  module Chips
+    # alternatives: other readings of an interpreted term ("Division 5432 instead");
+    # words: the chip of the query's words (names), not a filter.
+    Chip = Data.define(:index, :label, :ranges, :alternatives, :words) do
+      def initialize(index:, label:, ranges:, alternatives: [], words: false)
+        super
+      end
+    end
+    Alternative = Data.define(:index, :label, :text)
+
+    module_function
+
+    # @param query [Querylane::Query]
+    # @return [Array<Chip>]
+    def for(query)
+      return [] unless query.valid?
+
+      chips = []
+      if (texts = query.text_terms).any?
+        words = texts.map { |term| term.quoted ? %("#{term.value}") : term.value }.join(" ")
+        chips << [format(texts.first.operator, mask(words, texts.first.operator.mask)), texts.map(&:range), [], true]
+      end
+      query.nodes.each do |node|
+        next if node.is_a?(Query::Term) && node.kind == :text
+
+        chips << [label(node), [node.range], alternatives(query, node)]
+      end
+      chips.each_with_index.map do |(text, ranges, others, words), index|
+        Chip.new(index: index, label: text, ranges: ranges, alternatives: others || [], words: words || false)
+      end
+    end
+
+    # Other readings of an interpreted term, each with the explicit text it
+    # would become (e.g. "div:5432").
+    def alternatives(query, node)
+      return [] unless node.is_a?(Query::Term) && node.interpreted
+
+      query.definition.alternatives(node.raw).each_with_index.filter_map do |(key, value), index|
+        operator = query.definition.operator(key)
+        next unless operator
+
+        reading = Query.analyze(query.definition, "#{key}:#{value}")
+        next unless reading.valid?
+
+        Alternative.new(index, "#{label(reading.nodes.first)} instead", "#{operator.key}:#{value}")
+      end
+    end
+
+    def label(node)
+      case node
+      when Query::Term then term_label(node)
+      when Ast::Not then "Not #{label(node.node)}"
+      when Ast::Or then node.nodes.map { |child| label(child) }.join(" or ")
+      when Ast::Group then "(#{node.nodes.map { |child| label(child) }.join(" and ")})"
+      end
+    end
+
+    def term_label(term)
+      case term.kind
+      when :filter then format(term.operator, mask(term.value, term.operator.mask))
+      when :flag then "#{term.operator.label} #{term.operator.values.fetch(term.value)}"
+      when :text then format(term.operator, term.value)
+      end
+    end
+
+    def format(operator, value) = operator.label.gsub("%{value}", value.to_s)
+
+    # @param value [String]
+    # @param mask [Symbol] :none, :all, :last4, :count
+    def mask(value, mask)
+      case mask
+      when :none then value
+      when :last4 then (value.length >= 4) ? "•••-••-#{value[-4..]}" : "•" * value.length
+      when :count then I18n.t("querylane.chips.count", count: value.length, default: "%{count} characters")
+      else "•" * value.length
+      end
+    end
+  end
+end

data/lib/querylane/compiler.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Turns a valid Query into what a searcher runs: one text query (words and
+  # the attributes to search) and a filter per index (without the scope).
+  class Compiler
+    # matching: :all (every word) or :frequency (relaxed; rare words kept).
+    Compiled = Data.define(:text, :text_attributes, :filter_builder, :matching) do
+      # @return [Querylane::Filter] the query's filter for one index
+      def filter_for(index) = filter_builder.call(index.to_sym)
+    end
+
+    # @param query [Querylane::Query] valid
+    # @return [Querylane::Compiler::Compiled]
+    def self.compile(query)
+      raise ArgumentError, "compile a valid query" unless query.valid?
+
+      new(query).compile
+    end
+
+    def initialize(query)
+      @query = query
+      @definition = query.definition
+    end
+
+    def compile
+      terms = @query.text_terms
+      # Prefix matching is built in, so a "*" typed as a wildcard is dropped.
+      text = terms.map { |term| term.quoted ? %("#{term.value}") : term.value.to_s.delete("*") }.compact_blank.join(" ").presence
+      filter_nodes = @query.nodes.reject { |node| node.is_a?(Query::Term) && node.kind == :text }
+      Compiled.new(text, @query.text_operator&.attributes, ->(index) { Filter.and(*filter_nodes.map { |node| to_filter(node, index) }) }, :all)
+    end
+
+    private
+
+    def to_filter(node, index)
+      case node
+      when Query::Term then term_filter(node, index)
+      when Ast::Not then Filter.not(to_filter(node.node, index))
+      when Ast::Or then Filter.or(*node.nodes.map { |child| to_filter(child, index) })
+      when Ast::Group then Filter.and(*node.nodes.map { |child| to_filter(child, index) })
+      end
+    end
+
+    def term_filter(term, index)
+      case term.kind
+      when :filter then Filter.eq(term.operator.attribute, term.value)
+      when :flag then @definition.flag_filter(term.operator, term.value, index: index)
+      end
+    end
+  end
+end

data/lib/querylane/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Process-wide settings, set once in a host initializer:
+  #
+  #   Querylane.configure do |config|
+  #     config.searcher = -> { Querylane::Searchers::Meilisearch.new(client: MeilisearchService.client) }
+  #   end
+  class Configuration
+    # Name of the query parameter (filtered from logs by the engine).
+    attr_accessor :param_name
+    # Bounds every query is checked against.
+    attr_accessor :max_length, :max_depth, :max_terms
+    # Debounce (ms) before a typed query is submitted.
+    attr_accessor :debounce_ms
+    # Allows GET requests to carry the query (off: POST only).
+    attr_accessor :allow_get_query
+
+    attr_writer :searcher
+
+    # How long a group token ("more records", preview) stays valid.
+    attr_accessor :group_token_ttl
+
+    # Records read for suggestions (header box and palette), and people shown.
+    attr_accessor :suggest_records, :suggest_people
+
+    def initialize
+      @group_token_ttl = 3600
+      @suggest_records = 20
+      @suggest_people = 5
+      @param_name = :search_query
+      @max_length = 256
+      @max_depth = 3
+      @max_terms = 20
+      @debounce_ms = 300
+      @allow_get_query = false
+      @searcher = nil
+    end
+
+    # The searcher for this request. A callable is resolved on every call, so
+    # it can follow code reloading and per-request clients.
+    #
+    # @return [#search]
+    def searcher
+      found = @searcher.respond_to?(:call) ? @searcher.call : @searcher
+      found || raise(ConfigurationError, "Set Querylane.configure { |c| c.searcher = ... }")
+    end
+  end
+end

data/lib/querylane/context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Per-request facts hooks may use (the current user, the request, anything
+  # the host adds). Built by the host controller; never from params.
+  Context = Data.define(:user, :request, :extras) do
+    def initialize(user: nil, request: nil, extras: {})
+      super
+    end
+  end
+end

data/lib/querylane/controller.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Include in the host controller that serves a search page.
+  #
+  #   def search
+  #     if querylane_frame?(:member_search, :writes)
+  #       return render partial: "querylane/writes", locals: {preview: querylane_preview(MEMBERS), id: "member_search"}
+  #     end
+  #     @search = querylane_search(MEMBERS, scope: member_search_scope)
+  #     render partial: "members/results" if querylane_frame?(:member_search)
+  #   end
+  module Controller
+    # Runs the search for this request. Query text travels by POST only
+    # (unless the host opts in) and responses are never cached.
+    #
+    # @param definition [Querylane::Definition]
+    # @param scope [Querylane::Scope] built on the server for the current user
+    # @return [Querylane::Result]
+    # @param context [Querylane::Context] facts for the definition's hooks
+    def querylane_search(definition, scope:, context: Context.new(request: request), params: self.params, config: Querylane.configuration)
+      querylane_guard!(params, config)
+      Search.new(definition: definition, request: Request.from_params(params, definition: definition, config: config),
+        scope: scope, context: context, config: config).call
+    end
+
+    # Suggestions for the header box or palette (operators and people);
+    # render with the querylane_suggestions helper.
+    #
+    # @return [Querylane::Result]
+    def querylane_suggest(definition, scope:, context: Context.new(request: request), params: self.params, config: Querylane.configuration)
+      querylane_guard!(params, config)
+      Search.new(definition: definition, request: Request.from_params(params, definition: definition, config: config),
+        scope: scope, context: context, config: config).suggest
+    end
+
+    # All records of one group ("More records", the preview), from the
+    # request's `group` token; render with querylane/related or querylane/preview.
+    #
+    # @return [Querylane::Result, nil] nil when the request carries no token
+    def querylane_related(definition, scope:, context: Context.new(request: request), params: self.params, config: Querylane.configuration)
+      return if params[:group].blank?
+
+      querylane_guard!(params, config)
+      Search.new(definition: definition, request: Request.from_params(params.except(config.param_name), definition: definition, config: config),
+        scope: scope, context: context, config: config).related
+    end
+
+    # What the options panel would write, without searching (the panel's
+    # "Writes" line). Render it with the querylane/writes partial.
+    #
+    # @return [Querylane::Preview]
+    def querylane_preview(definition, params: self.params, config: Querylane.configuration)
+      querylane_guard!(params, config)
+      fields = params[:compose]
+      fields = fields.respond_to?(:to_unsafe_h) ? fields.to_unsafe_h : fields.to_h
+      Preview.for(definition, params[config.param_name], fields, config: config)
+    end
+
+    private
+
+    # Query text and panel fields never travel in a URL (unless the host opts
+    # in), and no response is cached. Only the URL's own query string is
+    # checked: a host may pass a query it restored on the server (e.g. a
+    # remembered search) to a GET.
+    def querylane_guard!(_params, config)
+      url = request.query_parameters
+      carries_text = [config.param_name, :compose, :group].any? { |name| url[name.to_s].present? }
+      if request.get? && carries_text && !config.allow_get_query
+        raise ActionController::BadRequest, "Search queries are sent by POST"
+      end
+
+      response.headers["Cache-Control"] = "no-store"
+    end
+
+    public
+
+    # @param id [Symbol, String] the widget id given to querylane_form
+    # @param part [Symbol] :results, or :writes (the options panel preview)
+    # @return [Boolean] whether this request targets that frame of the widget
+    def querylane_frame?(id, part = :results)
+      request.headers["Turbo-Frame"] == "#{id}-#{part}"
+    end
+  end
+end