kiosk-test-support 0.5.20

data/lib/kiosk/test_helpers/person.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'kiosk/user_identity_providers/devise_session'
+require 'kiosk/test_helpers/customer'
+
+module Kiosk
+  module TestHelpers
+    # Someone signed in on the operator's own site: links assistants to their
+    # account, approves the code an assistant shows them, and unlinks one.
+    #
+    #   alice = a_person(email: "alice@example.com", password: "…")
+    #   diner = alice.links(a_newcomer(as: Diner))
+    class Person
+      # The signed-in browser session, for the operator's own pages.
+      attr_reader :site
+
+      def initialize(origin, email:, password:)
+        @origin = origin
+        @site = UserIdentityProviders::DeviseSession.new(origin).sign_in!(email:, password:)
+      end
+
+      # A one-time code for an assistant to redeem.
+      def link_code
+        status, link = site.post_json('/kiosk/auth/link', {}, { session: true })
+        raise "the site minted no link code: #{status} #{link}" unless status == 201
+
+        link.fetch('link_code')
+      end
+
+      # `customer` redeems a fresh link code, and comes back acting for this person.
+      def links(customer) = customer.redeems(link_code)
+
+      # A newly keyed assistant, linked to this person's account.
+      def links_a_newcomer = links(Customer.newcomer(Assistant.new(base_url: @origin)))
+
+      # Approves the code an assistant showed, on the site's verification page.
+      def approves(user_code)
+        page = site.get_html("/kiosk/oauth/device/verify?user_code=#{user_code}")
+        approved = site.post_form('/kiosk/oauth/device/verify', 'user_code' => user_code, 'decision' => 'approve',
+                                                                'authenticity_token' => site.csrf_token(page.body))
+        raise "the site did not approve #{user_code}: #{page.code}, #{approved.code}" unless [page.code, approved.code] == %w[200 200]
+      end
+
+      def unlinks(customer)
+        status, = site.post_json('/kiosk/auth/unlink', { agent_id: customer.principal.agent_id }, { session: true })
+        raise "the site did not unlink #{customer.principal.agent_id}: #{status}" unless status == 204
+      end
+
+      def visits(path) = site.get_html(path)
+    end
+  end
+end

data/lib/kiosk/test_helpers/small_equihash.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'kiosk/pow/equihash'
+
+module Kiosk
+  module TestHelpers
+    # Require this from test setup only. It makes the Equihash default params
+    # n=96 k=5, so a registration in a test solves in about 0.2 s, not 10 s.
+    # Params passed explicitly are unchanged.
+    module SmallEquihash
+      PARAMS = { n: 96, k: 5 }.freeze
+
+      def params(n: PARAMS[:n], k: PARAMS[:k]) = super # rubocop:disable Naming/MethodParameterName -- the Equihash parameter names.
+    end
+  end
+end
+
+Kiosk::Pow::Equihash.singleton_class.prepend(Kiosk::TestHelpers::SmallEquihash)

data/lib/kiosk/test_helpers/story.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'kiosk/test_helpers/customer'
+require 'kiosk/test_helpers/live_server'
+
+module Kiosk
+  module TestHelpers
+    autoload :Person, 'kiosk/test_helpers/person'
+
+    # A test that tells a business story: who comes to the origin, what they
+    # ask for, what the origin answers and what they learn afterwards.
+    module Story
+      def self.included(base)
+        base.include LiveServer
+        base.public_send(base.respond_to?(:teardown) ? :teardown : :after) { @assistant&.disconnect }
+      end
+
+      # A newly registered assistant, as `as` (a demo's own Customer subclass).
+      def a_customer(as: Customer) = as.new(assistant, register)
+
+      # An assistant holding a key and no account here yet.
+      def a_newcomer(as: Customer) = as.newcomer(assistant)
+
+      # Someone with an account on the operator's site, signed in there.
+      def a_person(email:, password:) = Person.new(live_url, email:, password:)
+
+      # What the origin publishes at `path` to anyone, with no credential.
+      def published(path)
+        status, body = assistant.wire.get_json(path)
+        raise "GET #{path} with no credential answered #{status}" unless status == 200
+
+        body
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/stripe_mock.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'socket'
+require 'uri'
+
+module Kiosk
+  module TestHelpers
+    # A local stripe-mock for demo suites. A front on {url} relays to it and
+    # answers two calls as Stripe does where stripe-mock does not: a confirmed
+    # PaymentIntent create with a test card is `succeeded`, fully received, and
+    # a refund that names no charge is a 400.
+    module StripeMock
+      LOG           = '/tmp/stripe-mock.log'
+      DROPPED       = %w[accept-encoding connection content-length host transfer-encoding].freeze
+      NO_CHARGE_BODY = JSON.generate(error: {
+                                       type: 'invalid_request_error',
+                                       message: 'One of the following params should be provided for this request: ' \
+                                                'payment_intent or charge.'
+                                     })
+      NO_CHARGE = "HTTP/1.1 400 Bad Request\r\ncontent-type: application/json\r\n" \
+                  "content-length: #{NO_CHARGE_BODY.bytesize}\r\nconnection: close\r\n\r\n#{NO_CHARGE_BODY}".freeze
+
+      module_function
+
+      # The front's base URL: STRIPE_MOCK_URL when set, else a free port held
+      # for the life of this process. A suite that spawns its front stops it at
+      # exit, so each concurrent suite runs its own.
+      def url = @url ||= ENV.fetch('STRIPE_MOCK_URL') { "http://127.0.0.1:#{free_port}" }
+
+      # Reuses a front already listening on {url}; otherwise spawns stripe-mock
+      # and the front, stopped at exit.
+      #
+      # @return [String] the front's base URL
+      def start
+        return url if listening?(port)
+
+        abort 'stripe-mock not found. Install it: brew install stripe-mock' unless system('command -v stripe-mock >/dev/null 2>&1')
+
+        upstream = free_port
+        pids = spawn_processes(upstream)
+        at_exit { pids.each { stop(it) } }
+        await_ready(upstream)
+      end
+
+      def port = URI(url).port
+
+      def free_port = TCPServer.open('127.0.0.1', 0) { it.addr[1] }
+
+      def spawn_processes(upstream)
+        [spawn('stripe-mock', '-http-port', upstream.to_s, out: LOG, err: LOG),
+         spawn(RbConfig.ruby, '-I', File.expand_path('../..', __dir__), '-rkiosk/test_helpers/stripe_mock',
+               '-e', "Kiosk::TestHelpers::StripeMock.serve(#{port}, #{upstream})", out: LOG, err: LOG)]
+      end
+
+      def stop(pid)
+        Process.kill('TERM', pid)
+        Process.wait(pid)
+      rescue Errno::ESRCH, Errno::ECHILD
+        nil
+      end
+
+      def await_ready(upstream)
+        30.times do
+          return url if listening?(port) && listening?(upstream)
+
+          sleep 0.3
+        end
+        abort "stripe-mock did not become ready on #{url} — see #{LOG}"
+      end
+
+      def listening?(port)
+        TCPSocket.new('127.0.0.1', port).close
+        true
+      rescue StandardError
+        false
+      end
+
+      # Runs the front until killed.
+      def serve(port, upstream)
+        @upstream = upstream
+        server = TCPServer.new('127.0.0.1', port)
+        loop { Thread.new(server.accept) { |client| relay(client) } }
+      end
+
+      def relay(client)
+        method, path = client.gets.to_s.split
+        return unless path # a readiness check connects and hangs up
+
+        headers  = read_headers(client)
+        body     = client.read(headers['content-length'].to_i)
+        return client.write(NO_CHARGE) if chargeless_refund?(method, path, body)
+
+        relay_upstream(client, method, path, body, headers)
+      ensure
+        client.close
+      end
+
+      def relay_upstream(client, method, path, body, headers)
+        upstream = forward(method, path, body, headers)
+        answer   = upstream.body.to_s
+        answer = settled(answer) if confirmed_create?(method, path, body)
+        respond(client, upstream, answer)
+      end
+
+      def chargeless_refund?(method, path, body)
+        params = URI.decode_www_form(body.to_s).to_h
+        method == 'POST' && path == '/v1/refunds' && params['payment_intent'].to_s.empty? && params['charge'].to_s.empty?
+      end
+
+      def forward(method, path, body, headers)
+        Net::HTTP.start('127.0.0.1', @upstream) do |http|
+          http.send_request(method, path, body, headers.except(*DROPPED))
+        end
+      end
+
+      def read_headers(client)
+        headers = {}
+        while (line = client.gets) && line != "\r\n"
+          name, value = line.split(':', 2)
+          headers[name.downcase] = value.strip
+        end
+        headers
+      end
+
+      def confirmed_create?(method, path, body)
+        method == 'POST' && path == '/v1/payment_intents' &&
+          URI.decode_www_form(body.to_s).to_h['confirm'] == 'true'
+      end
+
+      def respond(client, upstream, answer)
+        client.write("HTTP/1.1 #{upstream.code} #{upstream.message}\r\n")
+        upstream.each_header { |k, v| client.write("#{k}: #{v}\r\n") unless DROPPED.include?(k) || k == 'content-encoding' }
+        client.write("content-length: #{answer.bytesize}\r\nconnection: close\r\n\r\n#{answer}")
+      end
+
+      def settled(answer)
+        intent = JSON.parse(answer)
+        return answer unless intent['object'] == 'payment_intent'
+
+        JSON.generate(intent.merge('status' => 'succeeded', 'amount_received' => intent['amount']))
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module TestHelpers
+    VERSION = '0.5.20'
+  end
+end

data/lib/kiosk/test_helpers/wire.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'kiosk/pow/equihash/solver'
+
+module Kiosk
+  module TestHelpers
+    # Any method at any path of an origin, with the whole answer returned. With
+    # `pay_tolls: true` it solves a proof-of-work toll and sends the request once more.
+    #
+    #   wire = Kiosk::TestHelpers::Wire.new(base_url: "http://127.0.0.1:3006")
+    #   status, problem = wire.post_json("/kiosk/edit_listing", { listing_id: "junk" }, Wire.bearer(token))
+    class Wire
+      # One answer: a body that is not JSON reads as `{}`, an unreachable origin as status 0.
+      Response = Data.define(:status, :headers, :body, :raw_body, :proofs) do
+        def initialize(status:, body:, headers: {}, raw_body: '', proofs: 0) = super
+
+        def [](header) = headers[header.to_s.downcase]
+
+        # Whether the client paid a proof-of-work toll and sent the request again.
+        def pow_retried? = proofs.positive?
+      end
+
+      METHODS = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        patch: Net::HTTP::Patch,
+        delete: Net::HTTP::Delete,
+        head: Net::HTTP::Head,
+        options: Net::HTTP::Options
+      }.freeze
+
+      # The scheme decides TLS.
+      def self.http_for(uri, open_timeout: nil, read_timeout: nil)
+        http = Net::HTTP.new(uri.hostname, uri.port)
+        http.use_ssl      = uri.scheme == 'https'
+        http.open_timeout = open_timeout if open_timeout
+        http.read_timeout = read_timeout if read_timeout
+        http
+      end
+
+      def self.bearer(token) = { 'Authorization' => "Bearer #{token}" }
+
+      # A solved proof of work for each challenge, as the `Kiosk-PoW` header carries them.
+      def self.solve(challenges) = challenges.map { { challenge: it, nonce: Kiosk::Pow::Equihash.solve(it) } }
+
+      attr_reader :base_url
+
+      def initialize(base_url:, pay_tolls: false, open_timeout: 10, read_timeout: 30)
+        @base_url     = base_url.to_s.chomp('/')
+        @pay_tolls    = pay_tolls
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      def bearer(token) = self.class.bearer(token)
+
+      def post_json(path, body = {}, headers = {}) = post(path, body, headers).then { [it.status, it.body] }
+
+      def get_json(path, params = {}, headers = {}) = get(path, params, headers).then { [it.status, it.body] }
+
+      def post(path, body = {}, headers = {}) = request(:post, path, body:, headers:)
+
+      def get(path, params = {}, headers = {}) = request(:get, path, params:, headers:)
+
+      def post_form(path, form, headers = {})
+        request(:post, path, headers:) { it.set_form_data(form) }
+      end
+
+      def request(method, path, body: nil, params: nil, headers: {}, &form)
+        klass = METHODS.fetch(method.to_s.downcase.to_sym) { raise ArgumentError, "unsupported HTTP method #{method.inspect}" }
+        uri = request_uri(path, params)
+        answer = deliver(klass, uri, body, headers, &form)
+        challenges = toll_challenges(answer)
+        return answer unless challenges
+
+        proofs = self.class.solve(challenges)
+        deliver(klass, uri, body, headers.merge('Kiosk-PoW' => JSON.generate(proofs)), &form).with(proofs: proofs.size)
+      end
+
+      private
+
+      def request_uri(path, params)
+        uri = URI("#{@base_url}#{path}")
+        uri.query = URI.encode_www_form(params) if params&.any?
+        uri
+      end
+
+      # The proof-of-work challenges of a toll this client pays, or nil.
+      def toll_challenges(answer)
+        return unless @pay_tolls && answer.status == 402 && answer.body.is_a?(Hash)
+
+        challenges = answer.body['challenges']
+        challenges if challenges.is_a?(Array) && challenges.any?
+      end
+
+      def deliver(klass, uri, body, headers)
+        request = klass.new(uri, body.nil? ? headers : { 'Content-Type' => 'application/json' }.merge(headers))
+        request.body = JSON.generate(body) unless body.nil?
+        yield request if block_given?
+        begin
+          answer = self.class.http_for(uri, open_timeout: @open_timeout, read_timeout: @read_timeout).request(request)
+        rescue StandardError => e
+          return Response.new(status: 0, body: { 'error' => e.class.name, 'detail' => e.message })
+        end
+        response(answer)
+      end
+
+      def response(answer)
+        raw_body = answer.body.to_s
+        body = begin
+          JSON.parse(raw_body)
+        rescue JSON::ParserError
+          {}
+        end
+        headers = answer.each_header.to_h { |name, value| [name.downcase, value] }
+        Response.new(status: answer.code.to_i, headers:, body:, raw_body:)
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'kiosk'
+
+require 'kiosk/test_helpers/version'
+require 'kiosk/test_helpers/errors'
+require 'kiosk/test_helpers/null_executor'
+require 'kiosk/test_helpers/journey'
+require 'kiosk/test_helpers/conformance'
+
+module Kiosk
+  # Test support for Kiosk operators: the journey DSL over a pluggable executor,
+  # and the conformance checks an origin runs against itself.
+  module TestHelpers
+    class << self
+      # Anything answering the {NullExecutor} contract.
+      attr_accessor :executor
+
+      def require_executor!
+        executor || raise(Errors::ExecutorNotConfigured)
+      end
+
+      def reset!
+        @executor = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,205 @@
+--- !ruby/object:Gem::Specification
+name: kiosk-test-support
+version: !ruby/object:Gem::Version
+  version: 0.5.20
+platform: ruby
+authors:
+- Phil Pirozhkov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: kiosk-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: kiosk-pow-equihash
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: |
+  kiosk-test-support is the framework-agnostic test surface a Kiosk
+  provider uses on their OWN application.
+
+  It carries two things. The CONFORMANCE CHECKS assert the four
+  properties the protocol makes normative of an origin: that its routes
+  resolve, that a verb executes, that a query answers the shape it
+  declared, and that data access is scoped to the authenticated
+  principal. They ship with a Minitest adapter and an RSpec adapter, both
+  loaded by explicit require, so the same fault reads identically in
+  either framework.
+
+  The JOURNEY DSL carries the identity-scoped call helpers
+  (`as_agent_of`, `as_user`, `as_agent`, `as_anonymous`, `query`,
+  `run_query`, `run_action`, `pay_action`, `kiosk_seed`), the pluggable
+  executor contract, a NullExecutor for self-tests, and the structured
+  error classes (`RLSDenied`, `QuotaExceeded`, `ExecutorNotConfigured`).
+  It is wired into RSpec by `kiosk-rls-rspec` and into Minitest by
+  `kiosk-rls-minitest`.
+
+  The ASSISTANT drives an origin over HTTP as an assistant does: it
+  registers, pays proof-of-work tolls, queries, runs, pays with signed
+  mandates and listens on the event stream. `Kyc` stands in for the
+  operator's KYC provider, and `StripeMock` fronts a local stripe-mock.
+
+  No Postgres, no Rails, no test-framework dependency.
+  `InProcessExecutor` and `Conformance::InProcessOrigin` run against
+  the host's kiosk-server and are required explicitly; this gem does
+  not depend on kiosk-server.
+email:
+- hello@fili.pp.ru
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/kiosk/story_spec.rb
+- lib/kiosk/story_test.rb
+- lib/kiosk/test_helpers.rb
+- lib/kiosk/test_helpers/assistant.rb
+- lib/kiosk/test_helpers/assistant/events.rb
+- lib/kiosk/test_helpers/conformance.rb
+- lib/kiosk/test_helpers/conformance/checks.rb
+- lib/kiosk/test_helpers/conformance/checks/declared_shape.rb
+- lib/kiosk/test_helpers/conformance/checks/executes.rb
+- lib/kiosk/test_helpers/conformance/checks/helpers.rb
+- lib/kiosk/test_helpers/conformance/checks/principal_scope.rb
+- lib/kiosk/test_helpers/conformance/checks/routes.rb
+- lib/kiosk/test_helpers/conformance/in_process_origin.rb
+- lib/kiosk/test_helpers/conformance/minitest.rb
+- lib/kiosk/test_helpers/conformance/null_origin.rb
+- lib/kiosk/test_helpers/conformance/outcome.rb
+- lib/kiosk/test_helpers/conformance/rspec.rb
+- lib/kiosk/test_helpers/conformance/verb.rb
+- lib/kiosk/test_helpers/customer.rb
+- lib/kiosk/test_helpers/descriptor_examples.rb
+- lib/kiosk/test_helpers/errors.rb
+- lib/kiosk/test_helpers/in_process_executor.rb
+- lib/kiosk/test_helpers/in_process_wire.rb
+- lib/kiosk/test_helpers/journey.rb
+- lib/kiosk/test_helpers/kyc.rb
+- lib/kiosk/test_helpers/live_server.rb
+- lib/kiosk/test_helpers/null_executor.rb
+- lib/kiosk/test_helpers/person.rb
+- lib/kiosk/test_helpers/small_equihash.rb
+- lib/kiosk/test_helpers/story.rb
+- lib/kiosk/test_helpers/stripe_mock.rb
+- lib/kiosk/test_helpers/version.rb
+- lib/kiosk/test_helpers/wire.rb
+homepage: https://kiosk.tech
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://kiosk.tech
+  source_code_uri: https://github.com/kiosk-hq/kiosk
+  changelog_uri: https://github.com/kiosk-hq/kiosk/blob/main/kiosk-test-support/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kiosk-hq/kiosk/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Kiosk conformance checks and journey-test DSL for RSpec and Minitest
+test_files: []