querylane 0.1.0

data/lib/querylane/group_token.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Querylane
+  # An opaque, expiring handle for one group of hits (e.g. a person), so a page
+  # can ask for "more records" without the group's key (a member ID) ever
+  # reaching HTML. Encrypted and signed with the host app's secret, bound to
+  # the definition's name.
+  module GroupToken
+    module_function
+
+    # @param definition [Querylane::Definition]
+    # @param value [String] the group attribute's value
+    # @param shown [Array<String>] "index:id" of the group's records already on the page
+    # @return [String]
+    def write(definition, value, shown, config: Querylane.configuration)
+      encryptor.encrypt_and_sign({"v" => value.to_s, "s" => shown}, purpose: purpose(definition), expires_in: config.group_token_ttl)
+    end
+
+    # @return [Array(String, Array<String>), nil] nil when tampered, expired or for another definition
+    def read(definition, token)
+      payload = encryptor.decrypt_and_verify(token.to_s, purpose: purpose(definition))
+      [payload.fetch("v"), Array(payload["s"])] if payload.is_a?(Hash)
+    rescue ActiveSupport::MessageEncryptor::InvalidMessage, ActiveSupport::MessageVerifier::InvalidSignature
+      nil
+    end
+
+    def purpose(definition) = "querylane.group.#{definition.name}"
+
+    def encryptor
+      ActiveSupport::MessageEncryptor.new(Rails.application.key_generator.generate_key("querylane group token", 32))
+    end
+  end
+end

data/lib/querylane/parser.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Turns query text into an Ast::Root (syntax only; meaning is Query's job).
+  #
+  # Grammar (Gmail style: implicit AND, OR binds tighter):
+  #   query := unit*            unit := unary ("OR" unary)*
+  #   unary := ("-" | "NOT") atom | atom
+  #   atom  := "(" query ")" | key ":" value | word | "phrase"
+  #
+  # Bounded: length, nesting depth and number of terms (Configuration).
+  class Parser
+    # A syntax error with the character range it concerns.
+    class Error < StandardError
+      attr_reader :range
+
+      def initialize(message, range)
+        super(message)
+        @range = range
+      end
+    end
+
+    Token = Data.define(:type, :range, :key, :value, :quoted)
+
+    KEY = /([A-Za-z][A-Za-z0-9_]*):/
+    QUOTED = /"((?:[^"\\]|\\.)*)"/
+    BARE = /[^\s()"]+/
+
+    # @param source [String]
+    # @return [Querylane::Ast::Root]
+    # @raise [Querylane::Parser::Error]
+    def self.parse(source, config: Querylane.configuration)
+      new(source.to_s, config).parse
+    end
+
+    def initialize(source, config)
+      @source = source
+      @config = config
+    end
+
+    def parse
+      if @source.length > @config.max_length
+        raise Error.new("Search is too long (#{@config.max_length} characters at most).", 0...@source.length)
+      end
+
+      @tokens = tokenize
+      @position = 0
+      @depth = 0
+      @terms = 0
+      nodes = parse_sequence(closing: false)
+      Ast::Root.new(nodes.freeze, @source)
+    end
+
+    private
+
+    def tokenize
+      scanner = StringScanner.new(@source)
+      tokens = []
+      until scanner.eos?
+        next if scanner.skip(/\s+/)
+
+        start = scanner.charpos
+        tokens << next_token(scanner, start)
+      end
+      tokens
+    end
+
+    def next_token(scanner, start)
+      if scanner.scan("(") then token(:lparen, scanner, start)
+      elsif scanner.scan(")") then token(:rparen, scanner, start)
+      elsif scanner.scan(/OR(?=[\s()]|\z)/) then token(:or, scanner, start)
+      elsif scanner.scan(/NOT(?=\s)/) then token(:not, scanner, start)
+      elsif scanner.scan(/-(?=[^\s)])/) then token(:minus, scanner, start)
+      elsif scanner.scan(KEY) then key_token(scanner, start, scanner[1])
+      elsif scanner.scan(QUOTED) then token(:term, scanner, start, value: unescape(scanner[1]), quoted: true)
+      elsif scanner.scan('"') then raise Error.new("Close the quote.", start...@source.length)
+      else
+        scanner.scan(BARE)
+        token(:term, scanner, start, value: scanner.matched)
+      end
+    end
+
+    def key_token(scanner, start, key)
+      if scanner.scan(QUOTED)
+        token(:term, scanner, start, key: key, value: unescape(scanner[1]), quoted: true)
+      elsif scanner.scan(BARE)
+        token(:term, scanner, start, key: key, value: scanner.matched)
+      else
+        raise Error.new("#{key}: needs a value.", start...scanner.charpos)
+      end
+    end
+
+    def token(type, scanner, start, key: nil, value: nil, quoted: false)
+      Token.new(type, start...scanner.charpos, key, value, quoted)
+    end
+
+    def unescape(text) = text.gsub(/\\(.)/, '\1')
+
+    def parse_sequence(closing:)
+      nodes = []
+      until done? || (closing && peek?(:rparen))
+        raise Error.new("Unexpected ).", current.range) if peek?(:rparen)
+
+        nodes << parse_or
+      end
+      nodes
+    end
+
+    def parse_or
+      parts = [parse_unary]
+      while peek?(:or)
+        operator = advance
+        raise Error.new("OR needs a term on both sides.", operator.range) if done? || peek?(:rparen) || peek?(:or)
+
+        parts << parse_unary
+      end
+      return parts.first if parts.one?
+
+      Ast::Or.new(parts.freeze, parts.first.range.begin...parts.last.range.end)
+    end
+
+    def parse_unary
+      if peek?(:minus) || peek?(:not)
+        operator = advance
+        raise Error.new("#{(operator.type == :not) ? "NOT" : "-"} needs a term.", operator.range) if done?
+
+        node = parse_atom
+        return Ast::Not.new(node, operator.range.begin...node.range.end)
+      end
+      parse_atom
+    end
+
+    def parse_atom
+      raise Error.new("Search ended early.", @source.length...@source.length) if done?
+
+      case current.type
+      when :lparen then parse_group
+      when :or then raise Error.new("OR needs a term on both sides.", current.range)
+      when :term then parse_term
+      else raise Error.new("Unexpected #{@source[current.range]}.", current.range)
+      end
+    end
+
+    def parse_group
+      open = advance
+      @depth += 1
+      raise Error.new("Too many nested parentheses (#{@config.max_depth} at most).", open.range) if @depth > @config.max_depth
+
+      nodes = parse_sequence(closing: true)
+      raise Error.new("Add the closing ).", open.range.begin...@source.length) unless peek?(:rparen)
+      raise Error.new("Empty parentheses.", open.range) if nodes.empty?
+
+      close = advance
+      @depth -= 1
+      Ast::Group.new(nodes.freeze, open.range.begin...close.range.end)
+    end
+
+    def parse_term
+      term = advance
+      @terms += 1
+      raise Error.new("Too many terms (#{@config.max_terms} at most).", term.range) if @terms > @config.max_terms
+
+      Ast::Term.new(term.key&.downcase, term.value, term.quoted, term.range)
+    end
+
+    def current = @tokens[@position]
+
+    def advance
+      token = current
+      @position += 1
+      token
+    end
+
+    def peek?(type) = !done? && current.type == type
+
+    def done? = @position >= @tokens.length
+  end
+end

data/lib/querylane/presenter.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Querylane
+  # How a host's records look in the gem's result rows. Subclass and override:
+  # Ruby decides (this class), the gem's partials draw (querylane/_rows,
+  # _group, _record, _outcome). Hits are grouped on the server by `group_key`
+  # (e.g. one person); the key itself never reaches the page.
+  #
+  #   class MemberPresenter < Querylane::Presenter
+  #     def columns = [Column.new(:policy, "Policy", 80)]
+  #     def group_key(hit) = hit.document["memberid"]
+  #     def cells(hit) = [Cell.new(hit.document["policy_number"], :strong)]
+  #     def outcome(hit) = Action.new("Open", select_path, {id: hit.id}, :primary)
+  #   end
+  class Presenter
+    # A record lane; width in pixels, nil to take the remaining space.
+    Column = Data.define(:key, :label, :width)
+    # One lane's value; style :strong, :muted or nil.
+    Cell = Data.define(:text, :style)
+    # tone: :success, :warning, :danger, :info, :neutral.
+    Badge = Data.define(:text, :tone)
+    # A button that opens the record (full-page POST, outside the frame).
+    Action = Data.define(:label, :url, :params, :style)
+    # Why a record cannot be opened, with an optional link to go instead.
+    # more: further reasons, shown on request ("+2 more").
+    Reason = Data.define(:text, :link_label, :link_url, :more) do
+      def initialize(text:, link_label: nil, link_url: nil, more: [])
+        super
+      end
+    end
+    Group = Data.define(:key, :hits)
+    # A group in suggestions: a short detail, its status, and what choosing it
+    # does (an Action opens it; nil runs the full search).
+    Suggestion = Data.define(:detail, :badge, :action)
+
+    attr_reader :result, :view, :id
+
+    # @param result [Querylane::Result]
+    # @param view [ActionView::Base] for routes and helpers
+    # @param id [String, nil] the widget id (frames and the search form)
+    def initialize(result, view, id: nil)
+      @result = result
+      @view = view
+      @id = id&.to_s
+    end
+
+    # @return [Array<Column>]
+    def columns = []
+
+    # Header of the last lane.
+    def outcome_label = "Open"
+
+    # Header of the status lane, nil for no status lane.
+    def status_label = "Status"
+
+    # Hits sharing a key form one group; nil keeps a hit on its own. Default:
+    # the definition's `group` attribute. An override must return that
+    # attribute's value (it is what "more records" searches for).
+    def group_key(hit) = result.definition.group_value(hit.document)
+
+    # An opaque token for loading every record of the group ("more records",
+    # preview), or nil when the group cannot be loaded.
+    #
+    # @return [String, nil]
+    def group_token(group)
+      value = group_key(group.hits.first)
+      return if value.nil? || result.definition.group.nil?
+
+      GroupToken.write(result.definition, value, group.hits.map { |hit| "#{hit.index}:#{hit.id}" })
+    end
+
+    # How many of the group's records the page does not show, or nil when
+    # unknown. "More records" shows only when this is positive.
+    #
+    # @return [Integer, nil]
+    def more_count(group)
+      value = group_key(group.hits.first)
+      return if value.nil? || result.group_totals.nil?
+
+      shown = group.hits.sum { |hit| 1 + hit.contributors.size }
+      more = result.group_totals.fetch(value.to_s.downcase, 0) - shown
+      more if more.positive?
+    end
+
+    # @return [String] the id of the group's "more records" frame
+    def related_frame_id(group) = "#{id}-related-#{record_key(group.hits.first)}"
+
+    # @return [Array<Group>] in hit order, the best-ranked hit leading each group
+    def groups
+      order = []
+      grouped = {}
+      result.hits.each_with_index do |hit, position|
+        key = group_key(hit) || "__#{position}"
+        order << key unless grouped.key?(key)
+        (grouped[key] ||= []) << hit
+      end
+      order.map { |key| Group.new(key, order_records(grouped.fetch(key))) }
+    end
+
+    # A group's records in the definition's group order (the order "more
+    # records" and the preview use); unchanged without one. The best-ranked
+    # record still decides where the group sits on the page.
+    def order_records(hits)
+      order = result.definition.group&.order
+      return hits if order.nil? || hits.one?
+
+      hits.each_with_index.sort do |(left, first), (right, second)|
+        compared = compare_records(left, right, order)
+        compared.zero? ? first <=> second : compared
+      end.map(&:first)
+    end
+
+    def compare_records(left, right, order)
+      order.each do |attribute, direction|
+        compared = left.document[attribute].to_s <=> right.document[attribute].to_s
+        return (direction.to_sym == :desc) ? -compared : compared unless compared.zero?
+      end
+      0
+    end
+
+    # Group heading (HTML-safe); default: the first highlighted text attribute.
+    def title(group)
+      attribute = result.definition.highlight.first
+      view.querylane_highlight(group.hits.first, attribute)
+    end
+
+    # Secondary heading next to the title (HTML-safe or plain), or nil.
+    def subtitle(group) = nil
+
+    # Why the group matched, or nil.
+    def note(group) = nil
+
+    # @return [Array<Cell>] one per column
+    def cells(hit) = []
+
+    # @return [Badge, nil]
+    def status(hit) = nil
+
+    # @return [Array<Badge>] small flags after the status lane
+    def flags(hit) = []
+
+    # @return [Action, Reason, nil]
+    def outcome(hit) = nil
+
+    # How a group appears in suggestions. Default: its record count, the first
+    # record's status, and its Action when exactly one record can be opened.
+    #
+    # @return [Suggestion]
+    def suggestion(group)
+      actions = group.hits.map { |hit| outcome(hit) }.grep(Action)
+      Suggestion.new(view.t("querylane.suggest.records", count: group.hits.size), status(group.hits.first),
+        actions.one? ? actions.first : nil)
+    end
+
+    # An opaque, stable key for keyboard focus and tests.
+    def record_key(hit) = Digest::SHA256.hexdigest("#{hit.index}:#{hit.id}")[0, 16]
+  end
+end

data/lib/querylane/preview.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Querylane
+  # What the options panel would write: the composed query and the parts kept
+  # as typed, with sensitive values masked for display. Built without a search.
+  #
+  # text, kept: masked display strings (nil when the box query is invalid);
+  # error: a QueryError for the composed text, or the box's own error.
+  Preview = Data.define(:text, :kept, :error) do
+    # @param definition [Querylane::Definition]
+    # @param source [String] the box text
+    # @param fields [Hash] compose fields from the panel
+    # @return [Querylane::Preview]
+    def self.for(definition, source, fields, config: Querylane.configuration)
+      query = Query.analyze(definition, source.to_s, config: config)
+      return new(nil, nil, query.error) unless query.valid?
+
+      composed = Query.analyze(definition, Rewriter.compose(query, fields.to_h.transform_keys(&:to_s)), config: config)
+      kept = Query.analyze(definition, Rewriter.panel(query).kept, config: config)
+      new(masked(composed), masked(kept), composed.error)
+    end
+
+    # The query text with every sensitive term's value masked.
+    #
+    # @param query [Querylane::Query]
+    # @return [String]
+    def self.masked(query)
+      text = query.source.dup
+      query.terms.select { |term| mask_of(term.operator) != :none }.sort_by { |term| -term.range.begin }.each do |term|
+        segment = text[term.range]
+        value = segment.split(":", 2).last
+        text[term.range] = segment.delete_suffix(value) + Chips.mask(value.delete('"'), mask_of(term.operator))
+      end
+      text
+    end
+
+    def self.mask_of(operator)
+      # :count reads as prose ("9 characters"); inside query text use dots.
+      return :none unless operator.respond_to?(:mask)
+
+      (operator.mask == :count) ? :all : operator.mask
+    end
+    private_class_method :mask_of
+  end
+end

data/lib/querylane/query.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Querylane
+  # The meaning of a query: parsed, bare words interpreted, every term matched
+  # to an operator of the definition and validated. One error at most.
+  #
+  #   query = Query.analyze(definition, "smith 5432 is:active")
+  #   query.valid?  # => true
+  #   query.nodes   # => [Term(:text name "smith"), Term(:filter last4 "5432"), Term(:flag is :active)]
+  class Query
+    # A resolved term. kind: :text, :filter or :flag.
+    # raw: the token as typed (for "instead" readings of interpreted terms).
+    Term = Data.define(:kind, :operator, :value, :quoted, :range, :interpreted, :raw)
+
+    attr_reader :definition, :source, :nodes, :error
+
+    # @param definition [Querylane::Definition]
+    # @param source [String]
+    # @return [Querylane::Query]
+    def self.analyze(definition, source, config: Querylane.configuration)
+      new(definition, source.to_s, config)
+    end
+
+    def valid? = error.nil?
+
+    def blank? = source.strip.empty?
+
+    # Top-level text terms (all share one operator).
+    #
+    # @return [Array<Term>]
+    def text_terms = nodes.grep(Term).select { |term| term.kind == :text }
+
+    # @return [Querylane::Definition::Text, nil]
+    def text_operator = text_terms.first&.operator
+
+    # Every term at any depth (inside NOT, OR and groups), in order.
+    #
+    # @return [Array<Term>]
+    def terms = walk(nodes)
+
+    # Whether every word is shorter than `length` and nothing else narrows the
+    # search ("*" is not counted: legacy queries used it as a wildcard).
+    def too_short?(length)
+      return false if length.nil? || blank?
+
+      terms.all? { |term| term.kind == :text } && terms.none? { |term| term.value.to_s.delete("*").length >= length }
+    end
+
+    # Terms whose operator is sensitive (member IDs, SSNs, last fours).
+    #
+    # @return [Array<Term>]
+    def sensitive_terms = terms.select { |term| term.operator.respond_to?(:sensitive) && term.operator.sensitive }
+
+    private
+
+    def walk(nodes)
+      nodes.flat_map do |node|
+        case node
+        when Term then [node]
+        when Ast::Not then walk([node.node])
+        when Ast::Or, Ast::Group then walk(node.nodes)
+        else []
+        end
+      end
+    end
+
+    def initialize(definition, source, config)
+      @definition = definition
+      @source = source
+      @nodes = []
+      @error = nil
+      root = Parser.parse(source, config: config)
+      @nodes = root.nodes.map { |node| resolve(node, context: nil) }.freeze
+      check_single_text_operator
+    rescue Parser::Error => error
+      @error = QueryError.new(error.message, error.range)
+    rescue Invalid => invalid
+      @error = invalid.error
+      @nodes = [].freeze
+    end
+
+    class Invalid < StandardError
+      attr_reader :error
+
+      def initialize(message, range, fix = nil)
+        super(message)
+        @error = QueryError.new(message, range, fix)
+      end
+    end
+    private_constant :Invalid
+
+    def resolve(node, context:)
+      case node
+      when Ast::Term then resolve_term(node, context)
+      when Ast::Not then Ast::Not.new(resolve(node.node, context: :not), node.range)
+      when Ast::Or then Ast::Or.new(node.nodes.map { |child| resolve(child, context: :or) }, node.range)
+      when Ast::Group then Ast::Group.new(node.nodes.map { |child| resolve(child, context: :group) }, node.range)
+      end
+    end
+
+    def resolve_term(term, context)
+      key, value, interpreted = term.key, term.value, false
+      if key.nil? && !term.quoted && (reading = definition.interpret(value))
+        key, value = reading
+        interpreted = true
+      end
+      return text_term(definition.default_text, value, term, context, interpreted) if key.nil?
+
+      raise Invalid.new(I18n.t("querylane.errors.parked", key: key, default: "%{key}: is not available yet."), term.range) if definition.parked.include?(key.to_s.downcase)
+
+      operator = definition.operator(key) || raise(unknown_key(key, term))
+      resolve_operator(operator, value, term, context, interpreted)
+    end
+
+    def resolve_operator(operator, value, term, context, interpreted)
+      case operator
+      when Definition::Text then text_term(operator, value, term, context, interpreted)
+      when Definition::FilterOperator then filter_term(operator, value, term, interpreted)
+      when Definition::Flags then flag_term(operator, value, term, interpreted)
+      end
+    end
+
+    def text_term(operator, value, term, context, interpreted)
+      if context
+        message = {
+          or: "OR joins operators, not names. Search one name at a time.",
+          not: "- and NOT apply to operators, not names.",
+          group: "Parentheses group operators, not names."
+        }.fetch(context)
+        raise Invalid.new(message, term.range)
+      end
+      Term.new(:text, operator, value, term.quoted, term.range, interpreted, term.value)
+    end
+
+    def filter_term(operator, value, term, interpreted)
+      normalized = operator.normalize ? operator.normalize.call(value) : value
+      if operator.format && !operator.format.match?(normalized)
+        shown = operator.sensitive ? "That value" : "\"#{value}\""
+        raise Invalid.new("#{shown} is not a valid #{operator.key}: value.", term.range)
+      end
+      Term.new(:filter, operator, normalized, term.quoted, term.range, interpreted, term.value)
+    end
+
+    def flag_term(operator, value, term, interpreted)
+      symbol = value.to_s.downcase.to_sym
+      unless operator.values.key?(symbol)
+        raise Invalid.new("#{value} is not a value of #{operator.key}:. Try #{operator.values.keys.join(", ")}.", term.range)
+      end
+      Term.new(:flag, operator, symbol, term.quoted, term.range, interpreted, term.value)
+    end
+
+    def check_single_text_operator
+      operators = text_terms.map(&:operator).uniq
+      return if operators.size <= 1
+
+      second = text_terms.find { |term| term.operator == operators.last }
+      others = definition.filters.map { |filter| "#{filter.key}:" }.first(2).join(" or ")
+      raise Invalid.new("Search #{operators.map(&:key).join(" or ")} one at a time, or combine with #{others}.", second.range)
+    end
+
+    # "stauts: is not an operator. Did you mean status:?", with the corrected term as the fix.
+    def unknown_key(key, term)
+      suggestion = definition.operator_keys.min_by { |candidate| distance(candidate, key) }
+      return Invalid.new("#{key}: is not an operator.", term.range) unless suggestion && distance(suggestion, key) <= 2
+
+      fixed = source[term.range].sub(/\A[^:]+/, suggestion)
+      Invalid.new("#{key}: is not an operator. Did you mean #{suggestion}:?", term.range, fixed)
+    end
+
+    # Levenshtein distance (short strings only).
+    def distance(a, b)
+      previous = (0..b.length).to_a
+      a.each_char.with_index(1) do |char_a, i|
+        current = [i]
+        b.each_char.with_index(1) do |char_b, j|
+          current << [previous[j] + 1, current[j - 1] + 1, previous[j - 1] + ((char_a == char_b) ? 0 : 1)].min
+        end
+        previous = current
+      end
+      previous.last
+    end
+  end
+end

data/lib/querylane/request.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Querylane
+  # One search request, bounded and allowlisted against the definition.
+  #
+  # Params: query (Configuration#param_name), toggle ("facet:value"),
+  # remove (chip index), clear, instead, widen, relax, compose (with
+  # compose_submit), options, sort, page, per, revision.
+  class Request
+    attr_reader :fix, :saved, :save_search, :saved_name, :group, :query, :toggle, :remove, :clear, :instead, :widen, :relax, :compose, :options, :sort, :page, :per, :revision
+
+    # @param params [ActionController::Parameters, Hash]
+    # @param definition [Querylane::Definition]
+    def self.from_params(params, definition:, config: Querylane.configuration)
+      values = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
+      values = values.transform_keys(&:to_s)
+      new(definition: definition, query: values[config.param_name.to_s], toggle: values["toggle"], remove: values["remove"], clear: values["clear"],
+        instead: values["instead"], widen: values["widen"], relax: values["relax"],
+        compose: (values["compose"] if values["compose_submit"].present?), options: values["options"],
+        fix: values["fix"], group: values["group"], saved: values["saved"], save_search: values["save_search"], saved_name: values["saved_name"], sort: values["sort"], page: values["page"], per: values["per"], revision: values["revision"])
+    end
+
+    # instead: "chip.alternative" (use another reading of an interpreted term);
+    # widen: a facet key (drop that facet's terms); relax: match fewer words.
+    # compose: options-panel fields {"name" => "…", "policy" => "1 2", "is" => [...], "options" => [...]}
+    # (applied only with compose_submit); options: open the options panel;
+    # group: a GroupToken (all records of one group, see Search#related);
+    # saved: a saved search id to run; save_search with saved_name: save the query.
+    def initialize(definition:, query: nil, toggle: nil, remove: nil, clear: nil, instead: nil, widen: nil, relax: nil,
+      compose: nil, options: nil, fix: nil, group: nil, saved: nil, save_search: nil, saved_name: nil, sort: nil, page: nil, per: nil, revision: nil)
+      @query = query.to_s
+      @clear = clear.present?
+      @instead = instead.to_s.match(/\A(\d+)\.(\d+)\z/)&.captures&.map(&:to_i)
+      @widen = definition.facet(widen)
+      @relax = relax.present?
+      @options = options.present?
+      @group = group.presence
+      @fix = fix.present?
+      @saved = saved.to_s.presence&.first(64)
+      @save_search = save_search.present?
+      @saved_name = saved_name.to_s.squish.first(80)
+      @compose = compose.is_a?(Hash) ? compose.to_h.transform_keys(&:to_s) : nil
+      @toggle = parse_toggle(definition, toggle)
+      @remove = (Integer(remove.to_s, exception: false) if remove.present?)
+      @sort = definition.sort(sort)
+      @per = definition.per_options.include?(per.to_i) ? per.to_i : definition.per_options.first
+      @page = rewriting? ? 1 : [page.to_i, 1].max
+      @revision = [revision.to_i, 0].max
+    end
+
+    # @return [Integer] records skipped before this page
+    def offset = (page - 1) * per
+
+    # Whether this request asks the server to rewrite the query text.
+    def rewriting? = (@toggle || @remove || @clear || @instead || @widen || @compose || @saved) ? true : false
+
+    private
+
+    # @return [Array(Querylane::Definition::Facet, String), nil]
+    def parse_toggle(definition, toggle)
+      key, value = toggle.to_s.split(":", 2)
+      facet = definition.facet(key) if value.present?
+      [facet, value] if facet
+    end
+  end
+end