raindown 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3288235ed874ddbeae5b31b5ef6707e59864f5cca305bb9bc74fcf74a9c36366
-  data.tar.gz: c7bfc9dcdec92857c433d4abacbc80d221bb6029617972d362af43163c235c39
+  metadata.gz: 1dffe3184c451794454149de18701ac6bd1afc2674b6a41385773d0f052bb2e5
+  data.tar.gz: 4e49463244dffc8e9b39873e2137f072f8632daec02c314d928fe09bbb115fd5
 SHA512:
-  metadata.gz: 1cb1aaaf0f325d154393656cad4040aa8a2205464e577ce69f23931bd2f2727d28222aba9a6d3a059bd2f7531e59050f0056b413a1a72cb72fe66e5e785b300a
-  data.tar.gz: f89b1e87119328272a1df69a6c2f9c04159f98db03c749774bac1ae533307eff32bc833b111c41ef569456ed9e0f2ec421afc938744b31102e4f6c8c848fcace
+  metadata.gz: 9502a0acb5cca634c884f74b8f2fc3e3a83c3fbe5bc635df7fccb779147718563a0a44679b3b3e6a1cf9da9e691026ff55953fc9a6b0aafad9cc48444eec12c6
+  data.tar.gz: dc928865b0da23c1b3dd67d859e94a3e718fe370b3d21d9344060cd5019e82fd5cce029b56d6008632690f9f1cc6f782cd41a8c38ca6d233bd06336f29fb7077

data/lib/raindown/actions.rb

@@ -12,6 +12,7 @@ module Raindown
   # Each returns true when the file changed, and raises when it can't, for the tool to show.
   module Actions
     class NotAnEndpoint < StandardError; end
+    class FailedCheck < StandardError; end
 
     # Editors that open a file at a line with "path:line" rather than "+line path".
     PATH_LINE_EDITORS = %w[hx helix subl zed].freeze
@@ -26,17 +27,22 @@ module Raindown
       Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
     end
 
-    # Runs one endpoint's request and writes its response, replacing any response it had.
+    # Runs one endpoint's request and writes its response, replacing any response it had, then raises when the response
+    # fails its checks, like status: 200.
     def execute(path, directive)
-      raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
-      raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
-
+      check_runnable(directive)
       content = Utils.read_markdown(path)
-      rewritten = EndpointRunner.new(content:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
-      return false if rewritten == content
+      runner = EndpointRunner.new(content:, path:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1)
+      rewritten = runner.rewrite
+      File.write(path, rewritten) unless rewritten == content
+      raise FailedCheck, runner.failures.join("\n") if runner.failures.any?
 
-      File.write(path, rewritten)
-      true
+      rewritten != content
+    end
+
+    def check_runnable(directive)
+      raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
+      raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
     end
 
     # The command that opens the file at a line in the person's editor, like ["vim", "+12", "notes.md"].

data/lib/raindown/bare_directives.rb

@@ -2,6 +2,7 @@
 
 require_relative 'code_blocks'
 require_relative 'directives'
+require_relative 'endpoint/schema_block'
 require_relative 'front_matter'
 
 module Raindown
@@ -10,6 +11,8 @@ module Raindown
   # matter, or with the --bare flag. Nodes like toc: and files: are handled by NodeBlocks, before the rest.
   # Template directives, like if: and for:, are always in Antlers' delimiters, so they're never bare.
   #
+  # A bare schema: shows in bold, with its fields in a code block below it.
+  #
   # Bare directives have no end tag. A bare endpoint closes itself after its curl snippet and response, so where it
   # needs more than that, write it in comments with an end tag instead:
   #   <!-- endpoint: -->
@@ -65,6 +68,9 @@ module Raindown
     # Returns the index of the last line it handled. That's the directive itself, so the lines it holds
     # are expanded too, and a bare directive inside it closes before it does.
     def expand_line(lines, index)
+      schema = SchemaBlock.at(lines, index, bare: true)
+      return expand_schema(lines, index, schema) if schema
+
       match = lines[index].match(LINE)
       return index unless match
 
@@ -73,6 +79,14 @@ module Raindown
       index
     end
 
+    # Returns the index of the code block's last line.
+    def expand_schema(lines, index, schema)
+      indent = schema.fields.first.to_s[/\A[ \t]*/]
+      block = [Directives.marker(lines[index], shown: true), "\n```\n", *schema.fields.map { it.delete_prefix(indent) }, "```\n"]
+      lines[index..schema.last] = block
+      index + block.length - 1
+    end
+
     # The end tag after the block, then the end tag in bold, as a bare directive's shown.
     def close_block(lines, index, indent:, keyword:)
       last = public_send(BLOCK_KEYWORDS[keyword], lines, index + 1) || index

data/lib/raindown/cli.rb

@@ -5,7 +5,9 @@ require 'trees'
 require_relative '../raindown'
 require_relative '../version'
 require_relative 'blueprints'
+require_relative 'editing'
 require_relative 'rewriter'
+require_relative 'server'
 require_relative 'watcher/file_watcher'
 require_relative 'watcher/supervisor'
 
@@ -28,15 +30,22 @@ module Raindown
                             PATH is a file, or a directory (default: current directory) whose projects with a
                             .raindown folder are watched
         init [DIRECTORY]    Create a .raindown folder for the project's config and nodes (default: current directory)
+        server              Keep Raindown loaded for an editor, answering a JSON request a line on stdin with its HTML,
+                            or its Markdown as it would be written back, like --stdin and --stdin --rewrite
         blueprints            Save the blueprints in Claude Code's last reply to .raindown/blueprints.md, for the terminal
                             UI's Blueprints page, as a Stop hook that's given the hook's JSON
 
       Options:
-        --html [OUTPUT]     Render FILE to HTML once, writing to OUTPUT or else printing to stdout
+        --html [OUTPUT]     Render FILE to HTML once, writing to OUTPUT, or to stdout without one or with -, then exit with 1
+                            if its endpoint responses fail their status: or schema: checks
         --stdin             Render Markdown from stdin to HTML once, without formatting FILE, which only needs
                             its extension (to allow bare directives) and can be unsaved. Add --html OUTPUT to write a file
+        --rewrite           With --stdin, print its Markdown as it would be written back to FILE, without writing
+                            FILE, for editors like Obsidian. Add -x to run its endpoints
         --bare              Allow bare directives like :toc in Markdown files
         -x, --execute       Run endpoint curl snippets that have no output yet, as files are written back
+        --env NAME          Fill endpoint snippets from the NAME environment in .raindown/environments.yml and
+                            environments.local.yml
         -h, --help          Show this message
         -v, --version       Show the version
 
@@ -52,12 +61,20 @@ module Raindown
 
     # A path opens the terminal UI, or after "watch" it's watched, and with --html or --stdin it's rendered. The flags
     # are keyword arguments, in any order, like -x for x:, and --html is the OUTPUT when it's given one.
-    line(':path') do |path, html: nil, stdin: false, bare: false, execute: false, x: false| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
-      execute { open_path(path, html:, stdin:, bare:, execute: execute || x) }
+    line(':path') do |path, html: nil, stdin: false, rewrite: false, bare: false, execute: false, x: false, env: nil| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
+      execute do
+        ENV['RAINDOWN_ENV'] = env if env
+        next rewrite_stdin(path, bare:, execute: execute || x) if stdin && rewrite
+
+        open_path(path, html:, stdin:, bare:, execute: execute || x)
+      end
     end
 
-    line('watch :path') do |path, bare: false, execute: false, x: false|
-      execute { watch(path, bare:, execute: execute || x) }
+    line('watch :path') do |path, bare: false, execute: false, x: false, env: nil|
+      execute do
+        ENV['RAINDOWN_ENV'] = env if env
+        watch(path, bare:, execute: execute || x)
+      end
     end
 
     def self.run(argv)
@@ -80,6 +97,7 @@ module Raindown
       if argv.intersect?(%w[-v --version]) then puts(VERSION)
       elsif argv.first == 'init' && argv.size <= 2 then init(argv[1])
       elsif argv == ['blueprints'] then Blueprints.save(JSON.parse($stdin.read))
+      elsif argv == ['server'] then serve
       else return false
       end
 
@@ -101,8 +119,10 @@ module Raindown
 
       FileUtils.mkdir_p(folder)
       File.write(config, CONFIG)
+      gitignore = File.join(folder, '.gitignore')
+      File.write(gitignore, "#{EndpointVariables::LOCAL_FILE}\n") unless File.exist?(gitignore)
       puts "Created #{config}"
-      puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/nodes'
+      puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/components'
     end
 
     # The terminal UI loads curses, so it's only required when it starts. Without a terminal, the path's watched instead.
@@ -116,9 +136,9 @@ module Raindown
     class << self
       private
 
-      # Endpoints run while formatting, which --stdin skips, so -x can't go with it.
+      # Endpoints run while formatting, which --stdin skips, so -x can't go with it. --html - prints, like --html.
       def open_path(path, html:, stdin:, bare:, execute:)
-        output = html unless html == true
+        output = html unless [true, '-'].include?(html)
         abort("-x runs endpoints as the file's formatted, which --stdin doesn't do\n\n#{USAGE}") if stdin && execute
         return render_stdin(path, output, bare:) if stdin
         return render(path, output, bare:, execute:) if html
@@ -134,12 +154,28 @@ module Raindown
         metadata = Pages.for(path)
         Rewriter.update(path:, bare:, execute:, metadata:)
         write(output, Raindown.render_file(path:, bare:, metadata:))
+        check_endpoints(path, bare:)
+      end
+
+      # Endpoint responses that fail their checks, like status: 200, are listed, and fail the command, for CI.
+      def check_endpoints(path, bare:)
+        failures = EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare:)
+        return if failures.empty?
+
+        warn(*failures.map { "Endpoint check failed: #{it}" })
+        exit 1
+      end
+
+      # The Markdown from stdin written back as it would be to the file, and its failed endpoint checks, for an editor
+      # to apply to what it's editing.
+      def rewrite_stdin(path, bare:, execute:)
+        rewritten = Editing.rewrite_markdown($stdin.read, path:, bare:, execute:)
+        $stdout.write(rewritten[:output])
+        warn(*rewritten[:warnings])
       end
 
       def render_stdin(path, output = nil, bare: false, **)
-        Nodes.load(path)
-        write(output, Raindown.render(markdown: $stdin.read, metadata: Pages.for(path), bare: bare || BareDirectives.file?(path),
-                                      **Config.render_options(path)))
+        write(output, Editing.render_markdown($stdin.read, path:, bare:))
       end
 
       # Watching only writes back to the files, while --html and --stdin render HTML.
@@ -151,6 +187,13 @@ module Raindown
         Watcher::FileWatcher.new(path:, bare:, execute:).start
       end
 
+      # The answers have stdout to themselves, so what nodes print goes to stderr.
+      def serve
+        output = $stdout.dup
+        $stdout.reopen($stderr)
+        Server.new(output:).start
+      end
+
       def write(output, html)
         output ? File.write(output, html) : puts(html)
       end

data/lib/raindown/directives.rb

@@ -31,16 +31,20 @@ module Raindown
     # Whether the directive's line is bare, without delimiters, so it shows in bold.
     def bare?(line) = text(line) == line.strip
 
-    # A directive's line as a marker: in bold when it's shown, like a bare directive, or else hidden.
+    # A directive's line as a marker: in bold when it's shown, like a bare directive, or else hidden. Its braces are
+    # hidden from Antlers like code's, so a shown chart: {stats} shows as it's written.
     def marker(line, shown: bare?(line))
-      text = text(line).gsub('--', '- -')
+      text = text(line).gsub('--', '- -').gsub(/[{}]/, CODE_BRACES)
       return "<!-- raindown:hidden #{text} -->" unless shown
 
       "<!-- raindown:directive #{text} -->"
     end
 
+    # The braces' entities, like code's, are kept as they are.
     def render(html)
-      html.gsub(HIDDEN, '').gsub(MARKER) { "<p><strong>#{CGI.escapeHTML(::Regexp.last_match(1).to_s)}</strong></p>" }
+      html.gsub(HIDDEN, '').gsub(MARKER) do
+        "<p><strong>#{CGI.escapeHTML(::Regexp.last_match(1).to_s).gsub(/&amp;(#12[35];)/, '&\1')}</strong></p>"
+      end
     end
   end
 end

data/lib/raindown/editing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../raindown'
+require_relative 'rewriter'
+
+module Raindown
+  # What an editor asks of Raindown about Markdown it's editing, which needn't be saved: its HTML, or the Markdown as it
+  # would be written back to the file, with its failed endpoint checks. "raindown FILE --stdin" and "raindown server"
+  # both answer with it.
+  module Editing
+    module_function
+
+    def render_markdown(markdown, path:, bare: false)
+      Nodes.load(path)
+      Raindown.render(markdown:, metadata: Pages.for(path), bare: bare || BareDirectives.file?(path), **Config.render_options(path))
+    end
+
+    def rewrite_markdown(markdown, path:, bare: false, execute: false)
+      Nodes.load(path)
+      rewritten = Rewriter.rewrite(content: markdown, path:, bare:, execute:, metadata: Pages.for(path))
+      { output: rewritten, warnings: EndpointRunner.failures(content: rewritten, path:, bare:).map { "Endpoint check failed: #{it}" } }
+    end
+  end
+end

data/lib/raindown/endpoint/curl.rb

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
-require 'json'
+require 'ipaddr'
 require 'open3'
 require 'shellwords'
+require 'socket'
+require 'uri'
+require_relative 'curl_response'
 
 module Raindown
   # Runs a curl snippet with the curl binary. There's no shell, so pipes, redirects and variables don't apply.
   # Snippets come from files that anyone (or any agent) may have written, so only options that make an HTTP request
   # are allowed: nothing that reads or writes local files, loads a config, or uses another protocol.
+  # Link-local addresses, like the cloud metadata service at 169.254.169.254, are refused, as they can give out
+  # credentials, and redirects aren't followed (no -L), so a URL can't redirect there either.
   module Curl
     class Error < StandardError; end
     Request = Data.define(:method, :url)
 
     TIMEOUT = '30'
+    # The variables curl reads a proxy from, which then looks the names up rather than curl.
+    PROXY_VARIABLES = %w[http_proxy https_proxy HTTPS_PROXY all_proxy ALL_PROXY].freeze
     # --disable must come first and skips ~/.curlrc. The protocol options stop redirects to file:// and the like.
     SAFE_OPTIONS = ['--disable', '--proto', '=http,https', '--proto-redir', '=http,https'].freeze
 
@@ -21,7 +28,7 @@ module Raindown
 
     # Options without a value.
     FLAGS = {
-      '-G' => '--get', '-I' => '--head', '-L' => '--location', '-i' => '--include', '-k' => '--insecure',
+      '-G' => '--get', '-I' => '--head', '-i' => '--include', '-k' => '--insecure',
       '-f' => '--fail', '-g' => '--globoff', '-s' => '--silent', '-S' => '--show-error'
     }.freeze
     LONG_FLAGS = (FLAGS.values + %w[--compressed --http1.1 --http2]).freeze
@@ -41,33 +48,24 @@ module Raindown
       '--data-urlencode' => :no_urlencoded_file
     }.freeze
 
-    # Separates the response body from the content type that --write-out appends.
-    TYPE_MARKER = "\n--raindown-content-type--"
-    WRITE_OUT = "#{TYPE_MARKER}%{content_type}".freeze # rubocop:disable Style/FormatStringToken -- curl's syntax, not Ruby's
-    LANGUAGES = {
-      /json/ => 'json', /xml/ => 'xml', /html/ => 'html', /javascript/ => 'javascript',
-      /css/ => 'css', /yaml/ => 'yaml', %r{\Atext/plain} => 'text'
-    }.freeze
-
     module_function
 
-    # Returns the response body and the code block language for its content type.
-    def run(snippet)
+    # Returns the Response, with the code block language for its content type.
+    # Placeholders like {base_url} are replaced from the variables, word by word, so a value can't add options.
+    def run(snippet, variables = nil)
+      args = arguments(snippet, variables)
       stdout, stderr, status = Open3.capture3('curl', *SAFE_OPTIONS, '--silent', '--show-error', '--max-time', TIMEOUT,
-                                              *arguments(snippet), '--write-out', WRITE_OUT)
+                                              *resolve_options(args), *args, '--write-out', Response::WRITE_OUT)
       raise Error, stderr.strip.empty? ? "curl exited with #{status.exitstatus}" : stderr.strip unless status.success?
 
-      body, _, content_type = stdout.rpartition(TYPE_MARKER)
-      language = language(content_type)
-
-      [language == 'json' ? pretty_json(body) : body, language]
+      Response.parse(stdout)
     rescue Errno::ENOENT
       raise Error, 'curl is not installed'
     end
 
     # The snippet's method and URL, like GET https://httpbin.org/uuid, or nil when it can't be read.
-    def request(snippet)
-      args = arguments(snippet)
+    def request(snippet, variables = nil)
+      args = arguments(snippet, variables)
       Request.new(method: request_method(args), url: args.find { it.match?(URL) })
     rescue Error
       nil
@@ -83,8 +81,9 @@ module Raindown
       'GET'
     end
 
-    def arguments(snippet)
+    def arguments(snippet, variables = nil)
       words = Shellwords.split(snippet.gsub(/\\\r?\n/, ' ').strip.delete_prefix('$ '))
+      words = words.map { variables.substitute(it) } if variables
       raise Error, 'Endpoint snippets must start with curl' unless words.first == 'curl'
       raise Error, 'Endpoint snippets must be a single curl command' if words.intersect?(OPERATORS)
 
@@ -120,7 +119,7 @@ module Raindown
       [option, value(option, words.shift)]
     end
 
-    # Short flags can be grouped like -sSL, and a short option's value can be attached like -XPOST.
+    # Short flags can be grouped like -sS, and a short option's value can be attached like -XPOST.
     def short_options(word, words)
       letters = word.delete_prefix('-')
       args = []
@@ -160,14 +159,48 @@ module Raindown
       value
     end
 
-    def language(content_type)
-      LANGUAGES.find { |pattern, _| content_type.match?(pattern) }&.last || ''
+    # Resolves each URL's host and pins curl to the address it was checked at, like --resolve api.io:443:203.0.113.5,
+    # so the name can't point somewhere else by the time curl looks it up. A host that's already an IP isn't pinned,
+    # and behind a proxy, which looks names up itself, only a host that's an IP is checked.
+    def resolve_options(args)
+      args.grep(URL).flat_map { pin_option(URI.parse(it)) }
+    rescue URI::InvalidURIError => e
+      raise Error, "Can't read the URL: #{e.message}"
+    end
+
+    def pin_option(uri)
+      raise Error, "#{uri} has no host" if uri.hostname.to_s.empty?
+      return [] if proxy? && !ip?(uri.hostname)
+
+      address = allowed_address(uri.hostname)
+      return [] if ip?(uri.hostname)
+
+      pinned = address.to_s
+      pinned = "[#{pinned}]" if address.ipv6?
+      ['--resolve', "#{uri.hostname}:#{uri.port}:#{pinned}"]
+    end
+
+    # Any way of writing an IP, like 169.254.169.254 or 2852039166, found without a DNS lookup.
+    def ip?(host)
+      Addrinfo.getaddrinfo(host, nil, nil, :STREAM, nil, Socket::AI_NUMERICHOST)
+      true
+    rescue SocketError
+      false
     end
 
-    def pretty_json(body)
-      JSON.pretty_generate(JSON.parse(body))
-    rescue JSON::ParserError
-      body
+    def proxy?
+      PROXY_VARIABLES.any? { !ENV[it].to_s.empty? }
+    end
+
+    # The host's first address, unless any of them is link-local.
+    def allowed_address(host)
+      addresses = Addrinfo.getaddrinfo(host, nil, nil, :STREAM).map { IPAddr.new(it.ip_address.sub(/%.*/, '')).native }
+      blocked = addresses.find(&:link_local?)
+      raise Error, "Endpoint snippets can't request link-local addresses, like cloud metadata at #{blocked}" if blocked
+
+      addresses.first
+    rescue SocketError => e
+      raise Error, "Can't resolve #{host}: #{e.message}"
     end
   end
 end

data/lib/raindown/endpoint/curl_response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Raindown
+  module Curl
+    # A response's body, its code block language, and its status code and time, like 200 in 142 milliseconds,
+    # read from what curl prints with --write-out WRITE_OUT.
+    class Response < Data.define(:body, :language, :status, :milliseconds)
+      # Separates the response body from the status, time and content type that --write-out appends.
+      INFO_MARKER = "\n--raindown-response-info--"
+      WRITE_OUT = "#{INFO_MARKER}%{http_code} %{time_total} %{content_type}".freeze # rubocop:disable Style/FormatStringToken -- curl's syntax, not Ruby's
+      LANGUAGES = {
+        /json/ => 'json', /xml/ => 'xml', /html/ => 'html', /javascript/ => 'javascript',
+        /css/ => 'css', /yaml/ => 'yaml', %r{\Atext/plain} => 'text'
+      }.freeze
+
+      # JSON is pretty-printed, and other bodies are kept as they are.
+      def self.parse(stdout)
+        body, _, info = stdout.rpartition(INFO_MARKER)
+        status, seconds, content_type = info.split(' ', 3)
+        language = LANGUAGES.find { |pattern, _| content_type.to_s.match?(pattern) }&.last || ''
+
+        new(body: language == 'json' ? pretty_json(body) : body, language:, status: status.to_i,
+            milliseconds: (seconds.to_f * 1000).round)
+      end
+
+      def self.pretty_json(body)
+        JSON.pretty_generate(JSON.parse(body))
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/raindown/endpoint/endpoint_args.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'schema_block'
+
+module Raindown
+  # An endpoint directive's arguments: as: names its response for later snippets, and status: and schema: are what its
+  # response is checked against, like "as: user status: 200 schema: Schema[id: Integer, email: String | nil]".
+  # A schema is a LowType type, read without running it, and is written with Schema[] rather than {}, which Antlers reads,
+  # or names a SchemaBlock, like schema: 'User' or schema: Array[User].
+  class EndpointArgs < Data.define(:name, :status, :schema)
+    KEYWORDS = %w[as: status: schema:].freeze
+
+    def self.parse(text, schemas: {})
+      values = keyword_values(text.to_s)
+      new(name: values['as'], status: values['status']&.then { Integer(it, exception: false) },
+          schema: values['schema']&.then { SchemaBlock.resolve(it, schemas) })
+    end
+
+    # Each keyword's words, up to the next keyword outside brackets, so a schema's own keys, like Schema[status: Integer],
+    # stay in it.
+    def self.keyword_values(text)
+      values = {}
+      key = nil
+      depth = 0
+
+      text.split.each do |word|
+        next values[key = word.delete_suffix(':')] = [] if depth.zero? && KEYWORDS.include?(word)
+        next unless key
+
+        values[key] << word
+        depth += word.count('[(') - word.count('])')
+      end
+
+      values.transform_values { it.join(' ') }
+    end
+
+    # What's wrong with a response, like "expected status 200, received 404" or "id: expected Integer, received "1"".
+    # A response fetched before statuses were kept has no status to check.
+    def failures(body:, status:)
+      failures = []
+      failures << "expected status #{self.status}, received #{status}" if self.status && status && status != self.status
+      failures.concat(schema_failures(body)) if schema
+      failures
+    end
+
+    private
+
+    # LowType is only loaded for an endpoint with a schema.
+    def schema_failures(body)
+      require 'lowtype'
+
+      Low::TypeParser.parse(schema).errors(data(body)).map do |node|
+        "#{node.path.to_s.empty? ? 'response' : node.path}: expected #{node.expected}, received #{node.received}"
+      end
+    rescue Low::ParseError => e
+      ["schema: #{e.message}"]
+    end
+
+    def data(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body.strip
+    end
+  end
+end