statifier 0.0.1 → 0.1.0

data/lib/statifier/accepts.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "machine"
+require_relative "interpreter"
+
+module Statifier
+  # What {Statifier.check_accepts} answers: the declared names no descriptor
+  # in the chart's event vocabulary matches, and the vocabulary's descriptors
+  # that match no declared name. A frozen value, deeply.
+  #
+  # @!attribute [r] unreachable
+  #   @return [Array<String>] each declared name no descriptor in the
+  #     vocabulary matches, in the declaration's order and without
+  #     duplicates: a name the declaration promises and the chart can never
+  #     select on
+  # @!attribute [r] undeclared
+  #   @return [Array<String>] each descriptor in the vocabulary that matches
+  #     no declared name, in the vocabulary's order: a name the chart listens
+  #     for that the declaration does not state
+  AcceptsCheck = ::Data.define(:unreachable, :undeclared)
+
+  # The accepts check: a declaration of the event names a chart accepts,
+  # compared with the chart's event vocabulary, as the reference compares
+  # them (`Statifier.Chart.check_accepts/2` and the vocabulary it reads,
+  # `Statifier.Chart.events/1`, in statifier-ex). {Statifier.check_accepts}
+  # answers through this module.
+  #
+  # The vocabulary is every event descriptor on a transition whose source
+  # state can be active, each returned as authored and a pattern never
+  # expanded. "Can be active" is a static rule over the chart's structure: a
+  # state some path enters, its ancestors included, following Appendix D's
+  # `addDescendantStatesToEnter` and `addAncestorStatesToEnter`. The root is
+  # entered by its default. Entering a state by its default enters its
+  # `initial` states as targets (a compound state or the root), every child
+  # that is not a history by its default (a parallel state), or its history
+  # default transition's targets as targets (a history pseudo-state).
+  # Entering a state as a target enters it by its default, enters each of its
+  # proper ancestors, and, for each parallel ancestor, enters by its default
+  # every child region that holds none of the transition's targets. Every
+  # transition of an entered state enters its targets as targets. No `cond`
+  # and no `event` is read, so the rule over-counts and never under-counts.
+  # A history pseudo-state contributes no descriptor. Descriptors come in
+  # `t_index` order (a state's own transitions before its children's, as the
+  # compiler numbers them), within one `event` attribute in the order
+  # written, and a descriptor equal as a string to one already listed is
+  # dropped.
+  #
+  # Matching is transition selection's own, {Interpreter::NameMatch}.
+  #
+  # @api private
+  module Accepts
+    module_function
+
+    # The accepts check of `declared` against `machine`'s vocabulary.
+    #
+    # @param machine [Machine] a compiled chart
+    # @param declared [Array<String>, nil] the declared event names, or nil
+    #   for no declaration
+    # @return [AcceptsCheck]
+    def check(machine, declared)
+      return AcceptsCheck.new(unreachable: [].freeze, undeclared: [].freeze) if declared.nil?
+
+      descriptors = tokenized(vocabulary(machine))
+      names = tokenized(declared.uniq.map(&:-@))
+      AcceptsCheck.new(unreachable: unreachable(names, descriptors), undeclared: undeclared(names, descriptors))
+    end
+
+    # Each of `strings` with its tokens, as `[string, tokens]`.
+    def tokenized(strings) = strings.map { [_1, Interpreter::NameMatch.tokenize(_1)] }
+
+    # The declared names no descriptor matches, frozen.
+    def unreachable(names, descriptors)
+      descriptor_tokens = descriptors.map(&:last)
+      names.reject { Interpreter::NameMatch.name_match?(descriptor_tokens, _2) }.map(&:first).freeze
+    end
+
+    # The descriptors that match no declared name, frozen.
+    def undeclared(names, descriptors)
+      descriptors.reject { |_, tokens| names.any? { Interpreter::NameMatch.name_match?([tokens], _2) } }
+                 .map(&:first).freeze
+    end
+
+    # The chart's event vocabulary (the reference's `events/1`): every
+    # descriptor on a transition of a state that can be active, history
+    # pseudo-states left out, in `t_index` order and without duplicates.
+    #
+    # @param machine [Machine] a compiled chart
+    # @return [Array<String>] frozen descriptors
+    def vocabulary(machine)
+      entered_states(machine)
+        .reject { machine.history?(_1) }
+        .flat_map { machine.state(_1).transitions }
+        .sort
+        .flat_map { |t_index| machine.transitions.fetch(t_index).events.map { -_1.join(".") } }
+        .uniq
+    end
+
+    # The least set of state indexes closed under the entry rule, as a
+    # worklist: `[:default, index]` enters a state by its default and
+    # `[:targets, indexes]` enters one transition's (or one `initial`'s)
+    # targets as targets. `defaulted` bounds the default expansions and
+    # `entered` bounds the per-state transition walk, so each state's work is
+    # queued once and the walk ends on any chart, cycles included.
+    def entered_states(machine)
+      entered = Set.new
+      defaulted = Set.new
+      work = [[:default, 0]]
+      work.concat(entry_work(machine, work.pop, entered, defaulted)) until work.empty?
+      entered.to_a
+    end
+
+    # The work one entry adds: a state entered by its default (once), or one
+    # list of targets entered as targets.
+    def entry_work(machine, (kind, subject), entered, defaulted)
+      return enter_targets(machine, subject, entered) if kind == :targets
+      return [] unless defaulted.add?(subject)
+
+      mark_entered(machine, subject, entered) + default_entry(machine, subject)
+    end
+
+    # The work entering `targets` as targets adds: each target by its
+    # default, and each proper ancestor entered, with its own transitions'
+    # work and, for a parallel ancestor, its untargeted regions by default.
+    def enter_targets(machine, targets, entered)
+      ancestors = targets.flat_map { machine.proper_ancestors(_1) }.uniq
+      ancestor_work = ancestors.flat_map do |ancestor|
+        mark_entered(machine, ancestor, entered) + untargeted_regions(machine, ancestor, targets)
+      end
+      targets.map { [:default, _1] } + ancestor_work
+    end
+
+    # What entering `index` by its default enters next, by kind: a parallel
+    # state's regions by their defaults, a history's default transition's
+    # targets as targets, and otherwise the compiler-resolved `initial` as
+    # targets - nothing on an atomic state.
+    def default_entry(machine, index)
+      state = machine.state(index)
+      case state.kind
+      when :parallel then machine.child_states(index).map { [:default, _1] }
+      when :history
+        state.history_default.nil? ? [] : [[:targets, machine.transitions.fetch(state.history_default).targets]]
+      else state.initial.empty? ? [] : [[:targets, state.initial]]
+      end
+    end
+
+    # A parallel ancestor's regions that hold none of `targets`, each to be
+    # entered by its default; nothing for any other ancestor.
+    def untargeted_regions(machine, ancestor, targets)
+      return [] unless machine.parallel?(ancestor)
+
+      machine.child_states(ancestor)
+             .reject { |region| targets.any? { _1 == region || machine.descendant?(_1, region) } }
+             .map { [:default, _1] }
+    end
+
+    # Marks `index` entered. The first time only, answers the work its own
+    # transitions add: each targeted transition's targets, as targets.
+    def mark_entered(machine, index, entered)
+      return [] unless entered.add?(index)
+
+      machine.state(index).transitions
+             .map { machine.transitions.fetch(_1).targets }
+             .reject(&:empty?)
+             .map { [:targets, _1] }
+    end
+  end
+end

data/lib/statifier/basichttp/decode.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Statifier
+  # The receive side of the Basic HTTP processor: {BasicHTTP.decode} and
+  # its {BasicHTTP::Refusal}.
+  module BasicHTTP
+    # Why {BasicHTTP.decode} formed no event from a request.
+    #
+    # @!attribute [r] reason
+    #   @return [Symbol] `:method_not_allowed` (the method is not POST; a
+    #     front answers 405 with `Allow: POST`), `:not_utf8` (the query
+    #     string or the body does not decode to UTF-8) or
+    #     `:malformed_send_key` (the `scxml-send-key` value is not eight
+    #     fields joined by `/` whose second decodes to UTF-8); a front
+    #     answers either of the last two 400
+    # @!attribute [r] detail
+    #   @return [String, Symbol] the method, `:query` or `:body`, or the
+    #     header's value
+    Refusal = ::Data.define(:reason, :detail)
+
+    # The event one HTTP request carries (appendix C.2.1), as the
+    # reference's `Statifier.Send.BasicHTTP.decode/1` forms it. It is pure
+    # and knows no session: a host's own server resolves the request's
+    # location to a session, decodes the request here and passes the event's
+    # `name` and `data` to {Statifier.step} with the state it holds for that
+    # session.
+    #
+    # - The method must be POST, in any case.
+    # - The event's name is the first `_scxmleventname` parameter found, the
+    #   query string's before a form body's, else `HTTP.` and the method in
+    #   upper case (`HTTP.POST`).
+    # - A form body (a content type that begins
+    #   `application/x-www-form-urlencoded`, in any case) and the query
+    #   string give the other parameters, which are the event's data: a
+    #   Hash whose values are each read as a `<content>` body's text is read
+    #   (a predicator literal, else the text with its whitespace collapsed),
+    #   so `2` is the number 2; the last of a repeated name wins, and no
+    #   parameters is no data (`Predicator::UNDEFINED`).
+    # - A body of any other content type, a JSON body included, is the data,
+    #   read the same way, and the query string then gives the name only. No
+    #   charset is read.
+    # - The event is external, its `origintype` {EVENT_PROCESSOR} and its
+    #   `origin` and `sendid` nil.
+    # - The `scxml-send-key` value is checked and sets nothing on the event:
+    #   deduplicating on it is the server's. A server that has already taken
+    #   a request with the same value answers 204 again and takes nothing.
+    #
+    # A server answers 204 once it has taken the event, 405 or 400 for a
+    # refusal, and its own 404 for a location that names no session it holds.
+    #
+    # @example
+    #   decoded = Statifier::BasicHTTP.decode(method: "POST", content_type: "application/x-www-form-urlencoded",
+    #                                         body: "_scxmleventname=e.go&n=2", query: nil)
+    #   decoded.value.name # => "e.go"
+    #   decoded.value.data # => {"n" => 2}
+    #
+    # @param method [String] the request's method
+    # @param content_type [String, nil] its content type, nil when it carries
+    #   none
+    # @param body [String] its body, empty for none
+    # @param query [String, nil] its query string without the `?`, nil when
+    #   the URL has none
+    # @param send_key [String, nil] its `scxml-send-key` header's value, nil
+    #   when it carries none
+    # @return [Statifier::Result] the {Statifier::Event}, deeply frozen, or a
+    #   {Refusal}
+    # @raise [TypeError] for an argument of the wrong kind
+    def self.decode(method:, content_type:, body:, query:, send_key: nil)
+      Decode.request(method, content_type, body, query, send_key)
+    end
+
+    # The body of {BasicHTTP.decode}.
+    #
+    # @api private
+    module Decode
+      module_function
+
+      # {BasicHTTP.decode}'s body, its checks in the reference's order: the
+      # method, the query string, the body, the send key.
+      def request(method, content_type, body, query, send_key)
+        checked(method:, body:, content_type:, query:, send_key:)
+        return refused(:method_not_allowed, method) unless method.upcase == "POST"
+
+        query_pairs = query.nil? ? [] : Encoding.pairs(query)
+        return refused(:not_utf8, :query) if query_pairs.nil?
+
+        decoded(method, query_pairs, body(content_type, body), send_key)
+      end
+
+      # The event, after the body and the send key are checked.
+      def decoded(method, query_pairs, (body_pairs, text), send_key)
+        return refused(:not_utf8, :body) if body_pairs.nil?
+        return refused(:malformed_send_key, send_key) unless send_key.nil? || send_key?(send_key)
+
+        Result.new(value: event(method, query_pairs + body_pairs, text), error: nil)
+      end
+
+      # A form body's pairs and no text, or no pairs and the body as text;
+      # nil pairs when it does not decode to UTF-8.
+      def body(content_type, body)
+        return [Encoding.pairs(body), nil] if content_type&.downcase&.start_with?(Outbound::FORM)
+
+        text = Encoding.utf8(body.b)
+        text.valid_encoding? ? [[], text] : [nil, nil]
+      end
+
+      # Whether `value` is eight fields joined by `/` whose second decodes to
+      # UTF-8.
+      def send_key?(value)
+        fields = value.split("/", -1)
+        fields.size == 8 && !Encoding.unfield(fields[1]).nil?
+      end
+
+      # The event the pairs and the text carry.
+      def event(method, pairs, text)
+        named, params = pairs.partition { _1.first == Outbound::EVENT_NAME_PARAM }
+        name = named.empty? ? "HTTP.#{method.upcase}" : named.first.last
+        data = text ? Interpreter::Send.text_data(text) : params_data(params)
+        Frozen.copy(Event.external(name, data:, origintype: EVENT_PROCESSOR))
+      end
+
+      # Each parameter's value read as text, the last of a name winning.
+      def params_data(params)
+        Interpreter::Send.params_data(params.map { |name, value| [name, Interpreter::Send.text_data(value)] })
+      end
+
+      def refused(reason, detail) = Result.new(value: nil, error: Refusal.new(reason:, detail: frozen(detail)))
+
+      def frozen(detail) = detail.is_a?(String) ? detail.dup.freeze : detail
+
+      # The arguments, after checking their kinds.
+      def checked(**arguments)
+        arguments.each do |name, value|
+          next if value.is_a?(String) || (value.nil? && !%i[method body].include?(name))
+
+          raise TypeError, "expected #{name} to be a String#{" or nil" unless %i[method body].include?(name)}, " \
+                           "got #{value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/statifier/basichttp/encoding.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Statifier
+  module BasicHTTP
+    # The Basic HTTP processor's text encodings, as the reference writes and
+    # reads them (`Statifier.Send.BasicHTTP` in statifier-ex): a form body
+    # and a query string (its `URI.encode_query(pairs, :www_form)` and
+    # `URI.query_decoder(text, :www_form)`), the two escaped fields of the
+    # `scxml-send-key` header (`URI.encode/2` keeping RFC 3986's unreserved
+    # set, and `URI.decode/1`), and a parameter value written as text (its
+    # private `encode/1` and `json/1`).
+    #
+    # Every encoding works on a string's bytes, so a value that is not UTF-8
+    # is escaped byte for byte, as the reference escapes one.
+    #
+    # @api private
+    module Encoding
+      module_function
+
+      # The bytes neither encoding escapes: RFC 3986's unreserved set.
+      ESCAPED = /[^A-Za-z0-9\-._~]/n
+
+      # An escape the decoders read: `%` and two hex digits.
+      ESCAPE = /%(\h\h)/n
+
+      # The deepest a list or a map is written as JSON text; one nested
+      # deeper is written as predicator's tagged-value text instead, whose
+      # encoder refuses past its own limit.
+      JSON_DEPTH = 256
+
+      # The magnitude from which a float is always written with an exponent,
+      # as the reference's runtime writes it: 2 to the 53rd.
+      EXPONENT_FROM = 2**53
+
+      # The JSON escapes of the characters with a short one.
+      SHORT_ESCAPES = { '"' => '\\"', "\\" => "\\\\", "\b" => "\\b", "\t" => "\\t", "\n" => "\\n", "\f" => "\\f",
+                        "\r" => "\\r" }.freeze
+
+      # Name and value pairs as an `application/x-www-form-urlencoded` body,
+      # in the order given: every byte outside the unreserved set escaped as
+      # `%` and two upper-case hex digits, a space written `+`.
+      #
+      # @param pairs [Array<Array(String, String)>]
+      # @return [String]
+      def form(pairs) = pairs.map { |name, value| "#{www_form(name)}=#{www_form(value)}" }.join("&")
+
+      # One name or value of a form: escaped, a space as `+`.
+      def www_form(text) = text.b.gsub(ESCAPED) { _1 == " " ? "+" : format("%%%02X", _1.ord) }.force_encoding("UTF-8")
+
+      # A `scxml-send-key` field: every byte outside the unreserved set
+      # escaped, a space as `%20`, so the field carries no `/`.
+      #
+      # @param text [String]
+      # @return [String]
+      def field(text) = text.b.gsub(ESCAPED) { format("%%%02X", _1.ord) }.force_encoding("UTF-8")
+
+      # A form body or a query string as its name and value pairs, in order,
+      # or nil when a name or a value does not decode to UTF-8. Pairs are
+      # split at each `&` and a pair at its first `=`; a pair with no `=` has
+      # the empty value, an empty pair is two empty strings, and nothing
+      # after a final `&` is a pair.
+      #
+      # @param text [String]
+      # @return [Array<Array(String, String)>, nil]
+      def pairs(text)
+        out = []
+        rest = text.b
+        until rest.empty?
+          pair, _, rest = rest.partition("&")
+          name, _, value = pair.partition("=")
+          out << [decoded(name, plus: true), decoded(value, plus: true)]
+        end
+        out.flatten.all? ? out : nil
+      end
+
+      # A field escaped as {field} escapes one, decoded, or nil when it does
+      # not decode to UTF-8. A `+` stays a `+`.
+      def unfield(text) = decoded(text.b, plus: false)
+
+      # Text with each escape decoded to its byte (an escape that is not `%`
+      # and two hex digits stays as it is written) and, when `plus`, each
+      # `+` read as a space; nil when the bytes are not UTF-8.
+      def decoded(bytes, plus:)
+        bytes = bytes.tr("+", " ") if plus
+        text = bytes.gsub(ESCAPE) { Regexp.last_match(1).hex.chr }.force_encoding("UTF-8")
+        text.valid_encoding? ? text : nil
+      end
+
+      # A value written as text: a string as it is, nil as `null`,
+      # `Predicator::UNDEFINED` as the empty string, a boolean as its
+      # literal, an Integer in decimal, a finite Float as {float} writes it,
+      # a list or a map as JSON text ({json}) when every value inside it has
+      # a JSON form. Anything else (a date, a datetime, a duration, a list
+      # or a map holding a value with no JSON form) is predicator's
+      # tagged-value text, or the empty string when that encoder refuses it.
+      #
+      # @param value [Object] a predicator value
+      # @return [String]
+      def value(value)
+        case value
+        when String then value
+        when nil then "null"
+        when true, false, Integer then value.to_s
+        when Float then value.finite? ? float(value) : tagged(value)
+        else scalar_or_tagged(value)
+        end
+      end
+
+      # What {value} writes for a value that is not a String, nil, a
+      # boolean or a number.
+      def scalar_or_tagged(value)
+        return "" if value.equal?(Predicator::UNDEFINED)
+
+        (json(value) if value.is_a?(Array) || value.is_a?(Hash)) || tagged(value)
+      end
+
+      # Predicator's tagged-value text of `value`, or the empty string.
+      def tagged(value)
+        encoded = Predicator::Tagged.encode(value)
+        encoded.ok? ? encoded.value : ""
+      end
+
+      # A list or a map as JSON text, or nil when a value inside has no JSON
+      # form. Inside, `Predicator::UNDEFINED` and nil are `null`; a map's
+      # keys must be UTF-8 Strings, and its members stand in the byte order
+      # of their keys; a string must be UTF-8; a Float must be finite; a
+      # value nested deeper than {JSON_DEPTH} has none. Byte order is the
+      # order the reference's runtime lists a small map's string keys in (32
+      # keys or fewer); it lists a larger map in an order of its own, so for
+      # a map of more than 32 keys this text differs from the reference's.
+      #
+      # @param value [Array, Hash]
+      # @return [String, nil]
+      def json(value, depth = 1)
+        return nil if depth > JSON_DEPTH
+
+        case value
+        when Array then json_list(value, depth)
+        when Hash then json_map(value, depth)
+        else json_scalar(value)
+        end
+      end
+
+      def json_list(list, depth)
+        parts = list.map { json(_1, depth + 1) || (return nil) }
+        "[#{parts.join(",")}]"
+      end
+
+      def json_map(map, depth)
+        return nil unless map.each_key.all? { _1.is_a?(String) && utf8?(_1) }
+
+        parts = map.keys.sort_by(&:b).map { "#{json_string(_1)}:#{json(map[_1], depth + 1) || (return nil)}" }
+        "{#{parts.join(",")}}"
+      end
+
+      def json_scalar(value)
+        case value
+        when nil, Predicator::UNDEFINED then "null"
+        when true, false, Integer then value.to_s
+        when Float then float(value) if value.finite?
+        when String then json_string(value) if utf8?(value)
+        end
+      end
+
+      # A UTF-8 string as JSON text, as the reference's runtime writes one:
+      # `"` and `\` escaped, the control characters with a short escape
+      # written so, every other control character below U+0020 as `\u` and
+      # four upper-case hex digits, everything else as it is.
+      def json_string(text)
+        body = utf8(text).gsub(/["\\\x00-\x1f]/) { SHORT_ESCAPES.fetch(_1) { |char| format("\\u%04X", char.ord) } }
+        "\"#{body}\""
+      end
+
+      # Whether `text`'s bytes are UTF-8.
+      def utf8?(text) = utf8(text).valid_encoding?
+
+      # `text`'s bytes read as UTF-8.
+      def utf8(text) = text.encoding == ::Encoding::UTF_8 ? text : text.dup.force_encoding("UTF-8")
+
+      # A finite Float as the reference's runtime writes it: the shortest
+      # digits that read back as the same number, in the plain form (a point,
+      # and `.0` when whole) or the exponent form (one digit, a point, at
+      # least one more digit, `e` and the exponent, signed only when
+      # negative), whichever is shorter, the plain form on a tie; from 2 to
+      # the 53rd up always the exponent form. Zero is `0.0`, and negative
+      # zero `-0.0`.
+      #
+      # @param number [Float] a finite Float
+      # @return [String]
+      def float(number)
+        sign = number.to_s.start_with?("-") ? "-" : ""
+        return "#{sign}0.0" if number.zero?
+
+        digits, point = shortest_digits(number.abs)
+        exponent = exponent_form(digits, point)
+        return sign + exponent if number.abs >= EXPONENT_FROM
+
+        plain = plain_form(digits, point)
+        sign + (plain.size <= exponent.size ? plain : exponent)
+      end
+
+      # The shortest significant digits of a positive Float, without leading
+      # or trailing zeros, and where the point falls: the Float is
+      # 0.DIGITS times ten to the power `point`. Ruby's Float#to_s writes the
+      # same shortest digits, in a form of its own read apart here.
+      def shortest_digits(magnitude)
+        mantissa, exponent = magnitude.to_s.split("e")
+        whole, fraction = mantissa.split(".")
+        digits = whole + fraction
+        significant = digits.sub(/\A0+/, "")
+        [significant.sub(/0+\z/, ""), whole.size + exponent.to_i - (digits.size - significant.size)]
+      end
+
+      def exponent_form(digits, point) = "#{digits[0]}.#{digits.size > 1 ? digits[1..] : "0"}e#{point - 1}"
+
+      def plain_form(digits, point)
+        return "0.#{"0" * -point}#{digits}" if point <= 0
+        return "#{digits}#{"0" * (point - digits.size)}.0" if digits.size <= point
+
+        "#{digits[0, point]}.#{digits[point..]}"
+      end
+    end
+  end
+end