lingara-apps 0.1.0.pre.alpha.3

data/lib/lingara/apps/generated/card.rb

@@ -0,0 +1,239 @@
+=begin
+#Lingara apps
+
+#No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+The version of the OpenAPI document: 2026-10-affable-towhee
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.14.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Lingara::Apps
+  class Card
+    attr_accessor :elements
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'elements' => :'elements'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'elements' => :'Array<Object>'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Lingara::Apps::Card` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Lingara::Apps::Card`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'elements')
+        if (value = attributes[:'elements']).is_a?(Array)
+          self.elements = value
+        end
+      else
+        self.elements = nil
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      if @elements.nil?
+        invalid_properties.push('invalid value for "elements", elements cannot be nil.')
+      end
+
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      return false if @elements.nil?
+      true
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] elements Value to be assigned
+    def elements=(elements)
+      if elements.nil?
+        fail ArgumentError, 'elements cannot be nil'
+      end
+
+      @elements = elements
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          elements == o.elements
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [elements].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Deserializes the data based on type
+    # @param string type Data type
+    # @param string value Value to be deserialized
+    # @return [Object] Deserialized data
+    def self._deserialize(type, value)
+      case type.to_sym
+      when :Time
+        Time.parse(value)
+      when :Date
+        Date.parse(value)
+      when :String
+        value.to_s
+      when :Integer
+        value.to_i
+      when :Float
+        value.to_f
+      when :Boolean
+        if value.to_s =~ /\A(true|t|yes|y|1)\z/i
+          true
+        else
+          false
+        end
+      when :Object
+        # generic object (usually a Hash), return directly
+        value
+      when /\AArray<(?<inner_type>.+)>\z/
+        inner_type = Regexp.last_match[:inner_type]
+        value.map { |v| _deserialize(inner_type, v) }
+      when /\AHash<(?<k_type>.+?), (?<v_type>.+)>\z/
+        k_type = Regexp.last_match[:k_type]
+        v_type = Regexp.last_match[:v_type]
+        {}.tap do |hash|
+          value.each do |k, v|
+            hash[_deserialize(k_type, k)] = _deserialize(v_type, v)
+          end
+        end
+      else # model
+        # models (e.g. Pet) or oneOf
+        klass = Lingara::Apps.const_get(type)
+        klass.respond_to?(:openapi_any_of) || klass.respond_to?(:openapi_one_of) ? klass.build(value) : klass.build_from_hash(value)
+      end
+    end
+
+    # Returns the string representation of the object
+    # @return [String] String presentation of the object
+    def to_s
+      to_hash.to_s
+    end
+
+    # to_body is an alias to to_hash (backward compatibility)
+    # @return [Hash] Returns the object in the form of hash
+    def to_body
+      to_hash
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+    # Outputs non-array value in the form of hash
+    # For object, use to_hash. Otherwise, just return the value
+    # @param [Object] value Any valid value
+    # @return [Hash] Returns the value in the form of hash
+    def _to_hash(value)
+      if value.is_a?(Array)
+        value.compact.map { |v| _to_hash(v) }
+      elsif value.is_a?(Hash)
+        {}.tap do |hash|
+          value.each { |k, v| hash[k] = _to_hash(v) }
+        end
+      elsif value.respond_to? :to_hash
+        value.to_hash
+      else
+        value
+      end
+    end
+
+  end
+
+end

data/lib/lingara/apps/limits.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  module Apps
+    # A card or reply the relay would clamp, refused with the first rule it
+    # breaks. #reason is one of Limits::REASONS.
+    class CardLimitError < StandardError
+      attr_reader :reason
+
+      def initialize(reason)
+        @reason = reason
+        super("the card breaks the #{reason} rule")
+      end
+    end
+
+    # The card rules (ADR 30.9.26am D5): the relay's clamp restated as
+    # refusals, held to conformance/vectors/card-limits.json and to the
+    # contract's reference validator. Every limit is a constant here and
+    # nowhere else, because the view carries none of them: they are
+    # post-parse clamps.
+    #
+    # A "character" is a Unicode scalar value (String#length on UTF-8), never
+    # a grapheme. "Empty" is empty after trimming Unicode White_Space, which
+    # String#strip does not do (it trims ASCII only). Patterns match the
+    # whole string (\A…\z), never one line of it as ^…$ would.
+    module Limits
+      # The largest reply body the relay reads, in bytes.
+      REPLY_MAX_BYTES = 32_768
+      # The largest request body a kit reads, in bytes.
+      REQUEST_MAX_BYTES = 65_536
+      MAX_ELEMENTS = 24
+      MAX_BUTTONS = 4
+      MAX_LIST_ITEMS = 20
+      TUTOR_NOTE_MAX_CHARS = 280
+      MAX_URL_BYTES = 2048
+
+      HEADING_MAX_CHARS = 80
+      TEXT_MAX_CHARS = 600
+      TERM_WORD_MAX_CHARS = 60
+      TERM_READING_MAX_CHARS = 120
+      TERM_GLOSS_MAX_CHARS = 160
+      PROGRESS_LABEL_MAX_CHARS = 60
+      BUTTON_LABEL_MAX_CHARS = 32
+      LINK_LABEL_MAX_CHARS = 60
+
+      LANG_PATTERN = /\A[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}\z/
+      ACTION_PATTERN = /\A[A-Za-z0-9_.:-]{1,64}\z/
+
+      # The refusal reasons, in the contract's order: a reply's reason is the
+      # first it breaks.
+      REASONS = %i[control_chars text_length heading_level progress_range lang link button_action buttons list_items
+        empty_element elements empty_card tutor_note_length reply_too_large].freeze
+
+      # C0 and C1 controls, and the bidi overrides and isolates; the second
+      # leaves out `\n`.
+      CONTROL = /[\u0000-\u001F\u007F-\u009F\u202A-\u202E\u2066-\u2069]/
+      CONTROL_BUT_NEWLINE = /[\u0000-\u0009\u000B-\u001F\u007F-\u009F\u202A-\u202E\u2066-\u2069]/
+      EDGES = /\A\p{White_Space}+|\p{White_Space}+\z/
+
+      # One text field's rule: its limit, whether `\n` is legal, whether it
+      # must be non-empty.
+      Field = Data.define(:limit, :newline, :required)
+      HEADING = Field.new(HEADING_MAX_CHARS, false, true)
+      TEXT = Field.new(TEXT_MAX_CHARS, true, true)
+      WORD = Field.new(TERM_WORD_MAX_CHARS, false, true)
+      READING = Field.new(TERM_READING_MAX_CHARS, false, false)
+      GLOSS = Field.new(TERM_GLOSS_MAX_CHARS, false, false)
+      PROGRESS_LABEL = Field.new(PROGRESS_LABEL_MAX_CHARS, false, true)
+      BUTTON_LABEL = Field.new(BUTTON_LABEL_MAX_CHARS, false, true)
+      LINK_LABEL = Field.new(LINK_LABEL_MAX_CHARS, false, true)
+      # `lang`, `button.action` and `link.url`: no length limit of their own.
+      RAW = Field.new(Float::INFINITY, false, false)
+
+      # The rules a reply breaks, collected; the reason is the first in
+      # REASONS order, as the reference validator's BTreeSet minimum is.
+      class Found
+        def initialize
+          @broken = []
+        end
+
+        def flag(reason, broken)
+          @broken << reason if broken
+        end
+
+        def raise_first
+          reason = REASONS.find { |r| @broken.include?(r) }
+          raise CardLimitError, reason if reason
+        end
+
+        def text(value, rule)
+          unless value.is_a?(String)
+            flag(:empty_element, rule.required)
+            return nil
+          end
+          flag(:control_chars, Limits.control?(value, rule.newline))
+          flag(:text_length, value.length > rule.limit)
+          flag(:empty_element, rule.required && Limits.trim(value).empty?)
+          value
+        end
+
+        def lang(value)
+          tag = text(value, RAW)
+          flag(:lang, !tag.match?(LANG_PATTERN)) if tag
+        end
+
+        def item(item)
+          case item["type"]
+          when "text"
+            text(item["text"], TEXT)
+            lang(item["lang"])
+          when "term"
+            text(item["word"], WORD)
+            text(item["reading"], READING) unless item["reading"].nil?
+            text(item["gloss"], GLOSS) unless item["gloss"].nil?
+            lang(item["lang"])
+          end
+        end
+
+        def element(e)
+          case e["type"]
+          when "heading"
+            text(e["text"], HEADING)
+            flag(:heading_level, !(e["level"].is_a?(Integer) && [1, 2].include?(e["level"])))
+          when "text", "term" then item(e)
+          when "list" then list(e)
+          when "progress"
+            flag(:progress_range, !(e["value"].is_a?(Numeric) && e["value"].between?(0, 1)))
+            text(e["label"], PROGRESS_LABEL)
+          when "button"
+            text(e["label"], BUTTON_LABEL)
+            flag(:button_action, !text(e["action"], RAW).to_s.match?(ACTION_PATTERN))
+          when "link"
+            text(e["label"], LINK_LABEL)
+            flag(:link, !Limits.safe_link?(text(e["url"], RAW).to_s))
+          end
+        end
+
+        def list(e)
+          items = e["items"].is_a?(Array) ? e["items"] : []
+          items.each { |i| item(i.is_a?(Hash) ? i : {}) }
+          flag(:list_items, items.empty? || items.size > MAX_LIST_ITEMS)
+        end
+
+        def card(card)
+          raw = card.is_a?(Hash) ? card["elements"] : nil
+          elements = Array(raw.is_a?(Array) ? raw : nil).map { |e| e.is_a?(Hash) ? e : {} }
+          elements.each { |e| element(e) }
+          flag(:buttons, elements.count { |e| e["type"] == "button" } > MAX_BUTTONS)
+          flag(:elements, elements.size > MAX_ELEMENTS)
+          flag(:empty_card, elements.empty?)
+        end
+
+        def tutor_note(note)
+          return unless note.is_a?(String)
+          flag(:control_chars, Limits.control?(note, true))
+          # The relay turns `\n` into a space and trims before it counts.
+          flag(:tutor_note_length, Limits.trim(note.tr("\n", " ")).length > TUTOR_NOTE_MAX_CHARS)
+        end
+      end
+
+      module_function
+
+      # Trims Unicode White_Space from both ends.
+      def trim(text)
+        text.gsub(EDGES, "")
+      end
+
+      # Whether `text` holds a refused character, `\n` aside when `newline`.
+      def control?(text, newline)
+        text.match?(newline ? CONTROL_BUT_NEWLINE : CONTROL)
+      end
+
+      # The relay's cut, never applied implicitly: over `limit` scalar values,
+      # the first `limit − 1` and `…`; otherwise unchanged.
+      def truncate(text, limit)
+        return text if text.length <= limit
+        "#{text[0, [limit - 1, 0].max]}…"
+      end
+
+      # `https`, no user information, a host name (never an IP address), at
+      # most MAX_URL_BYTES. Read as a WHATWG parser reads a special URL: a
+      # host whose last label is a number is IPv4 (127.1, 0x7f.1).
+      def safe_link?(raw)
+        return false if raw.bytesize > MAX_URL_BYTES
+        authority = raw[%r{\Ahttps://([^/?#\\]*)}i, 1]
+        return false if authority.nil? || authority.include?("@")
+        host, port = authority.match(/\A(.*?)(?::(\d*))?\z/m).captures
+        return false if port && !port.empty? && port.to_i > 65_535
+        !host.empty? && !host.match?(%r{[\u0000\t\n\r #/:<>?@\[\\\]^|%]}) && !ends_in_number?(host)
+      end
+
+      def ends_in_number?(host)
+        last = host.delete_suffix(".").split(".").last.to_s.downcase
+        return false if last.empty?
+        last.match?(/\A(?:\d+|0x\h*)\z/)
+      end
+
+      # Every card rule, the tutor note, and the size of the reply encoded
+      # exactly as it will be sent: compact JSON, raw UTF-8, `/` unescaped,
+      # an absent tutor_note omitted. Returns those bytes, or raises
+      # CardLimitError with the first reason. Takes the generic JSON shape
+      # (a Hash with String keys), so a vector feeds it as it is.
+      def validate_reply(reply)
+        found = Found.new
+        reply = {} unless reply.is_a?(Hash)
+        found.card(reply["card"])
+        found.tutor_note(reply["tutor_note"])
+        found.raise_first
+        bytes = JSON.generate(reply)
+        raise CardLimitError, :reply_too_large if bytes.bytesize > REPLY_MAX_BYTES
+        bytes
+      end
+
+      # The card rules alone (reasons 1–12): what CardBuilder#build runs.
+      def check_card(card)
+        Found.new.tap { |f| f.card(card) }.raise_first
+      end
+
+      # The tutor note's rules alone: what Reply#tutor_note runs.
+      def check_tutor_note(note)
+        Found.new.tap { |f| f.tutor_note(note) }.raise_first
+      end
+    end
+  end
+end

data/lib/lingara/apps/manifest.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  module Apps
+    # A manifest the upload would refuse, with the first rule it breaks.
+    # #rule is one of ManifestRules::RULES.
+    class ManifestError < StandardError
+      attr_reader :rule
+
+      def initialize(rule)
+        @rule = rule
+        super("the manifest breaks the #{rule} rule")
+      end
+    end
+
+    # The manifest's rules (ADR 30.9.26am D5), hand-written against the
+    # manifest's wire form, which is in no spec the view reads. Each refuses
+    # what the upload would refuse or normalise away where a kit can know it,
+    # in the order conformance/vectors/manifest.json describes; a refusal
+    # names the first broken rule.
+    module ManifestRules
+      NAME_MAX_CHARS = 40
+      DESCRIPTION_MAX_CHARS = 280
+      STORED_MAX_BYTES = 65_536
+
+      RULES = %i[manifest_version default_locale name description render_url slots context duplicate too_large].freeze
+
+      # The slots a manifest may name: the generated AppSlotName's values,
+      # without the generator's unknown-value placeholder.
+      SLOT_NAMES = (AppSlotName.all_vars - [AppSlotName::UNKNOWN_DEFAULT_OPEN_API]).freeze
+
+      # Zero-width characters, beyond the card rules' controls and bidi marks.
+      ZERO_WIDTH = /[\u200B-\u200F\uFEFF]/
+      RENDER_URL = %r{\Ahttps://[^/?#]}i
+
+      module_function
+
+      def localized?(value, max)
+        return false unless value.is_a?(Hash) && !value.empty?
+        value.each_value.all? do |v|
+          next false unless v.is_a?(String)
+          trimmed = Limits.trim(v)
+          trimmed.length.between?(1, max) && !Limits.control?(trimmed, false) && !trimmed.match?(ZERO_WIDTH)
+        end
+      end
+
+      def default_locale?(m)
+        locale = m["default_locale"]
+        return false unless locale.is_a?(String) && !locale.empty?
+        [m["name"], m["description"]].all? { |map| !map.is_a?(Hash) || map.key?(locale) }
+      end
+
+      # A list of allowed strings; absent passes only when +optional+.
+      def within?(m, key, allowed, optional)
+        return optional unless m.key?(key)
+        value = m[key]
+        return false unless value.is_a?(Array)
+        return false if value.empty? && !optional
+        value.all? { |v| v.is_a?(String) && allowed.include?(v) }
+      end
+
+      def duplicate?(m)
+        %w[slots context scopes].any? { |k| m[k].is_a?(Array) && m[k].uniq.size != m[k].size }
+      end
+
+      # The compact UTF-8 JSON of the seven stored keys, defaults filled.
+      def stored_bytes(m)
+        stored = {
+          "default_locale" => m["default_locale"], "name" => m["name"], "description" => m["description"],
+          "slots" => m["slots"], "context" => m["context"] || [], "scopes" => m["scopes"] || [],
+          "tutor_note" => m["tutor_note"].nil? ? false : m["tutor_note"]
+        }
+        JSON.generate(stored).bytesize
+      end
+
+      CHECKS = {
+        manifest_version: ->(m) { m["manifest_version"].is_a?(Integer) && m["manifest_version"] == 1 },
+        default_locale: ->(m) { default_locale?(m) },
+        name: ->(m) { localized?(m["name"], NAME_MAX_CHARS) },
+        description: ->(m) { localized?(m["description"], DESCRIPTION_MAX_CHARS) },
+        render_url: ->(m) { m["render_url"].is_a?(String) && m["render_url"].match?(RENDER_URL) },
+        slots: ->(m) { within?(m, "slots", SLOT_NAMES, false) },
+        context: ->(m) { within?(m, "context", CONTEXT_SLICE_KINDS, true) },
+        duplicate: ->(m) { !duplicate?(m) },
+        too_large: ->(m) { stored_bytes(m) <= STORED_MAX_BYTES }
+      }.freeze
+
+      # The first rule +manifest+ breaks, or nil. Takes any JSON value.
+      def first_broken(manifest)
+        m = manifest.is_a?(Hash) ? manifest : {}
+        RULES.find { |rule| !CHECKS.fetch(rule).call(m) }
+      end
+    end
+
+    # A fluent manifest. #build validates and returns the wire form (a Hash);
+    # #to_json writes the upload.
+    #
+    #   Lingara::Apps.manifest.default_locale("en").name("Daily five").description("Five words.")
+    #     .render_url("https://apps.example.com/lingara").slots("home.side").build
+    class ManifestBuilder
+      def initialize
+        @default_locale = ""
+        @name = ""
+        @description = ""
+        @render_url = ""
+        @slots = []
+        @context = []
+        @scopes = []
+        @tutor_note = false
+        @listed = false
+      end
+
+      def default_locale(locale) = set(:@default_locale, locale)
+
+      # A locale map, or a bare String meaning the default locale's.
+      def name(name) = set(:@name, name)
+
+      # A locale map, or a bare String meaning the default locale's.
+      def description(description) = set(:@description, description)
+
+      def render_url(url) = set(:@render_url, url)
+
+      # AppSlotName values.
+      def slots(*slots) = set(:@slots, slots)
+
+      # CONTEXT_SLICE_KINDS values.
+      def context(*kinds) = set(:@context, kinds)
+
+      def scopes(*scopes) = set(:@scopes, scopes)
+
+      # Whether the app's replies may carry a tutor note.
+      def tutor_note(enabled = true) = set(:@tutor_note, enabled)
+
+      # Whether the app appears in the catalogue; false unless set.
+      def listed(listed = true) = set(:@listed, listed)
+
+      # The manifest, or ManifestError naming the first rule it breaks.
+      def build
+        manifest = {
+          "manifest_version" => 1, "default_locale" => @default_locale, "name" => localized(@name),
+          "description" => localized(@description), "render_url" => @render_url, "slots" => @slots.dup,
+          "context" => @context.dup, "scopes" => @scopes.dup, "tutor_note" => @tutor_note, "listed" => @listed
+        }
+        Apps.validate_manifest(manifest)
+        manifest
+      end
+
+      # The validated manifest as the JSON the console accepts as an upload.
+      def to_json(*)
+        "#{JSON.pretty_generate(build)}\n"
+      end
+
+      private
+
+      def set(ivar, value)
+        instance_variable_set(ivar, value)
+        self
+      end
+
+      def localized(value)
+        value.is_a?(String) ? {@default_locale => value} : value
+      end
+    end
+
+    module_function
+
+    # Starts a manifest.
+    def manifest
+      ManifestBuilder.new
+    end
+
+    # Raises ManifestError naming the first rule +manifest+ (a Hash with
+    # String keys, as JSON.parse gives) breaks; nil when it keeps them all.
+    def validate_manifest(manifest)
+      rule = ManifestRules.first_broken(manifest)
+      raise ManifestError, rule if rule
+    end
+  end
+end

data/lib/lingara/apps/operations.rb

@@ -0,0 +1,23 @@
+# Generated by ruby/codegen/generate.rb from the app view. DO NOT EDIT.
+
+module Lingara
+  module Apps
+    # The view's x-lingara-app-operations: the request messages a kit
+    # dispatches on (a request's `type`) and the reply message. The core's
+    # dispatch table is held to REQUESTS' keys by a unit test, so a third
+    # operation fails the build until the core handles it.
+    module Operations
+      RENDER = "app.render"
+      ACTION = "app.action"
+
+      # Each request message and the name of its generated request model.
+      REQUESTS = {
+        "app.render" => "AppRenderRequest",
+        "app.action" => "AppActionRequest"
+      }.freeze
+
+      # The reply every request expects: a card.
+      REPLY = "app.card"
+    end
+  end
+end

data/lib/lingara/apps/rack_app.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Apps
+    # The Rack adapter (ADR 30.9.26am D2): a Rack-protocol endpoint over an
+    # App. The Rack protocol is a callable and a Hash, so the kit depends on
+    # no `rack` gem; mount it in any Rack server, Rails or Sinatra.
+    #
+    #   # config.ru
+    #   run Lingara::Apps::RackApp.new(app)
+    #
+    # It reads `rack.input` itself, as raw bytes and at most 64 KiB + 1 of
+    # them, before anything parses it, and hands the env to the library's
+    # verifier as the headers, as it is. Mount it where no middleware has
+    # already read or decoded the body: the signature covers the exact bytes
+    # Lingara sent.
+    class RackApp
+      def initialize(app)
+        raise ArgumentError, "RackApp wraps a Lingara::Apps::App" unless app.is_a?(App)
+        @app = app
+      end
+
+      def call(env)
+        input = env["rack.input"]
+        read = ->(limit) { input&.read(limit).to_s }
+        status, headers, body = @app.handle(env["REQUEST_METHOD"], env, read)
+        [status, headers.dup, body.empty? ? [] : [body]]
+      end
+    end
+  end
+end