raindown 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3288235ed874ddbeae5b31b5ef6707e59864f5cca305bb9bc74fcf74a9c36366
-  data.tar.gz: c7bfc9dcdec92857c433d4abacbc80d221bb6029617972d362af43163c235c39
+  metadata.gz: 9d8b4a4baae078b6b14f7ae6fd66dde441f97776e7107a07864ca4c12beebb74
+  data.tar.gz: 582a5012c02638f89991497cc789ef9513e7c13262445784c40ddb026b246574
 SHA512:
-  metadata.gz: 1cb1aaaf0f325d154393656cad4040aa8a2205464e577ce69f23931bd2f2727d28222aba9a6d3a059bd2f7531e59050f0056b413a1a72cb72fe66e5e785b300a
-  data.tar.gz: f89b1e87119328272a1df69a6c2f9c04159f98db03c749774bac1ae533307eff32bc833b111c41ef569456ed9e0f2ec421afc938744b31102e4f6c8c848fcace
+  metadata.gz: 1e8fc0825e5462616ce435e35188f5d41b45b23fdbbb59ff840c140cf46279de4a0e696def346a92f168dc6e04e97d1bcac9e309b1db3d9219fe59eeaadad52a
+  data.tar.gz: 5025d3381c0e0e2049a6b5fe462102438226feaa2d1a563c89b34dde74b1679163071d4df43e61d3a261e489ed71a107ae925db7f4cf08f1b9e83e773b45b46c

data/lib/raindown/actions.rb

@@ -32,7 +32,7 @@ module Raindown
       raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
 
       content = Utils.read_markdown(path)
-      rewritten = EndpointRunner.new(content:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
+      rewritten = EndpointRunner.new(content:, path:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
       return false if rewritten == content
 
       File.write(path, rewritten)

data/lib/raindown/cli.rb

@@ -37,6 +37,7 @@ module Raindown
                             its extension (to allow bare directives) and can be unsaved. Add --html OUTPUT to write a file
         --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
         -h, --help          Show this message
         -v, --version       Show the version
 
@@ -52,12 +53,18 @@ 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, 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
+        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)

data/lib/raindown/endpoint/curl.rb

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
+require 'ipaddr'
 require 'json'
 require 'open3'
 require 'shellwords'
+require 'socket'
+require 'uri'
 
 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
@@ -52,9 +59,11 @@ module Raindown
     module_function
 
     # Returns the response body and the code block language for its content type.
-    def run(snippet)
+    # 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', WRITE_OUT)
       raise Error, stderr.strip.empty? ? "curl exited with #{status.exitstatus}" : stderr.strip unless status.success?
 
       body, _, content_type = stdout.rpartition(TYPE_MARKER)
@@ -66,8 +75,8 @@ module Raindown
     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 +92,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 +130,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,6 +170,50 @@ module Raindown
       value
     end
 
+    # 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 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
+
     def language(content_type)
       LANGUAGES.find { |pattern, _| content_type.match?(pattern) }&.last || ''
     end

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -4,14 +4,15 @@ require 'date'
 require_relative '../bare_directives'
 require_relative '../code_blocks'
 require_relative 'curl'
+require_relative 'endpoint_variables'
 
 module Raindown
   # Runs the curl block under an endpoint directive in a comment, or a bare one, and writes the response in the code
   # block below it,
   # followed by the date it was fetched.
-  # Only runs when that block is missing or empty, and the directive has :x/:execute or --execute is passed.
+  # Only runs when that block is missing or empty, and --execute is passed, so a file can't run requests by itself.
   # Or with only: and a directive's line index, runs just that endpoint, replacing any response it has.
-  #   <!-- endpoint: :x -->
+  #   <!-- endpoint: -->
   #   ```sh
   #   curl https://api.example.com
   #   ```
@@ -20,6 +21,8 @@ module Raindown
   #   ```
   #   <!-- raindown:fetched 2026-10-14 -->
   #   <!-- :endpoint -->
+  # Its snippet's {placeholders} are filled from EndpointVariables, and with as: login, later snippets can use its
+  # response, like {login.token}.
   # One in Antlers' delimiters, <{ endpoint: }>, only renders, so it's never run.
   class EndpointRunner
     # An endpoint's directive in Antlers' delimiters, which only renders, or in a comment, which writes its response back,
@@ -27,16 +30,16 @@ module Raindown
     DIRECTIVE = /\A {0,3}<\{\s*endpoint:(.*?)\}>[ \t]*$/
     COMMENT = /\A {0,3}<!--\s*endpoint:(.*?)-->[ \t]*$/
     END_TAG = /\A {0,3}(?:<\{\s*:endpoint\s*\}>|<!--\s*:endpoint\s*-->)[ \t]*$/
-    EXECUTE_ARGS = %w[:x :execute].freeze
     # The date a response was fetched, on the line after it.
     FETCHED = /\A {0,3}<!-- raindown:fetched [^\n]*? -->[ \t]*$/
 
     def self.rewrite(content:, path: nil, bare: false, execute: false, **)
-      new(content:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
+      new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
     end
 
-    def initialize(content:, bare: false, execute: false, only: nil)
+    def initialize(content:, path: nil, bare: false, execute: false, only: nil)
       @lines = content.lines
+      @variables = EndpointVariables.new(path:, content:)
       @bare = bare
       @execute = execute
       @only = only
@@ -71,24 +74,29 @@ module Raindown
     def fill(index, args, directive:)
       curl, output = CodeBlocks.endpoint(@lines, index)
       return index - 1 unless curl&.dig(:body)&.lstrip&.start_with?('curl')
-      return curl[:close] unless run?(args, output, directive)
+      return write_output(curl:, output:, name: response_name(args)) if run?(output, directive)
 
-      write_output(curl:, output:)
+      @variables.remember(response_name(args), output[:body]) if output
+      curl[:close]
     end
 
-    def run?(args, output, directive)
-      return directive == @only if @only
-
-      (output.nil? || output[:body].strip.empty?) && execute?(args)
+    # The name that as: gives the endpoint, for later snippets to use its response.
+    def response_name(args)
+      index = args.index('as:')
+      args[index + 1] if index
     end
 
-    def execute?(args)
-      @execute || args.intersect?(EXECUTE_ARGS)
+    def run?(output, directive)
+      return directive == @only if @only
+
+      @execute && (output.nil? || output[:body].strip.empty?)
     end
 
     # Replaces the output block and the date it was fetched, or with no block, replaces nothing just after the curl block.
-    def write_output(curl:, output:)
-      block = [*output_block(*Curl.run(curl[:body])), fetched]
+    def write_output(curl:, output:, name:)
+      body, language = Curl.run(curl[:body], @variables)
+      @variables.remember(name, body)
+      block = [*output_block(body, language), fetched]
       block.unshift("\n") unless output
       start = output ? output[:open] : curl[:close] + 1
 

data/lib/raindown/endpoint/endpoint_variables.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require_relative '../front_matter'
+require_relative 'curl'
+
+module Raindown
+  # The values that {placeholders} in an endpoint's curl snippet are replaced with, like {base_url} or {login.token}.
+  # From least to most specific: the file's front matter, the project's environment, and the responses of endpoints
+  # named with as:, read from the file as it goes. {env.NAME} is the environment variable NAME, for secrets, and an
+  # environment's values can use it too, like token: '{env.STAGING_TOKEN}'.
+  # The environment is one in .raindown/environments.yml, chosen with --env or RAINDOWN_ENV, or else the first:
+  #   local:
+  #     base_url: http://localhost:3000
+  #   staging:
+  #     base_url: https://staging.example.com
+  class EndpointVariables
+    class Error < Curl::Error; end
+
+    FILE = 'environments.yml'
+    PLACEHOLDER = /\{([A-Za-z_][\w.-]*)\}/
+
+    def initialize(path:, content:)
+      @path = path
+      @content = content
+    end
+
+    # Keeps a named endpoint's response, as its JSON's data when it's JSON, or else its text.
+    def remember(name, body)
+      return unless name
+
+      values[name] = begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body.strip
+      end
+    end
+
+    # The text with each placeholder that has a value replaced by it, and the rest left as they are. A value's own
+    # placeholders are replaced once, so an environment can read secrets like {env.TOKEN}.
+    def substitute(text, depth: 1)
+      text.gsub(PLACEHOLDER) do |placeholder|
+        value = value(Regexp.last_match(1))
+        next placeholder if value.nil?
+        next value.to_json if value.is_a?(Hash) || value.is_a?(Array)
+        next substitute(value, depth: 0) if depth.positive? && value.is_a?(String)
+
+        value.to_s
+      end
+    end
+
+    private
+
+    # Read when they're first needed, so a file without endpoints doesn't need its environment.
+    def values
+      @values ||= FrontMatter.parse(@content).first.transform_keys(&:to_s).merge(environment, 'env' => ENV.to_h)
+    end
+
+    def environment
+      folder = @path && Nodes.find_folder(File.dirname(File.expand_path(@path)))
+      file = folder && File.join(folder, FILE)
+      return {} unless file && File.exist?(file)
+
+      environments = YAML.safe_load_file(file) || {}
+      name = ENV.fetch('RAINDOWN_ENV') { environments.keys.first }
+      environments.fetch(name) { raise Error, "There's no #{name} environment in #{file}" }
+    end
+
+    # A value by its path, like login.token or users.0.id.
+    def value(name)
+      name.split('.').reduce(values) do |value, key|
+        case value
+        when Hash then value.fetch(key) { value[key.to_sym] }
+        when Array then value[Integer(key, exception: false) || value.length]
+        end
+      end
+    end
+  end
+end

data/lib/raindown/tui/project.rb

@@ -15,6 +15,7 @@ require_relative 'card'
 require_relative 'endpoint'
 require_relative '../code_blocks'
 require_relative '../endpoint/curl'
+require_relative '../endpoint/endpoint_variables'
 
 module Raindown
   module TUI
@@ -89,7 +90,7 @@ module Raindown
 
       def endpoint(path, lines, directive)
         snippet = CodeBlocks.endpoint(lines, directive.line).first&.dig(:body)
-        request = Curl.request(snippet.to_s)
+        request = Curl.request(snippet.to_s, EndpointVariables.new(path:, content: lines.join))
         Endpoint.new(project: root, path:, line: directive.line, **request.to_h) if request
       end
 

data/lib/raindown/variables.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
+require 'antlers/api'
+
 module Raindown
   # The front matter values that Antlers variables like {title} and <{ title }> render.
   # Antlers reads a variable from the binding's locals, then by sending it to the binding's receiver, which is this.
   # It's a BasicObject so a key like "hash" or "display" isn't shadowed by a method, and unknown names render nothing.
-  # Nested values work too, like {author.name} and <{ for: tag in: tags }>.
+  # Nested values are hashes and arrays like {author.name}, {tags.0} or <{ for: name, url in: links }>.
   class Variables < BasicObject
     # Braces in a value become the placeholders that render as braces, so Antlers doesn't read them as a variable.
     def self.wrap(value)
       case value
-      when ::Hash then new(value)
+      when ::Hash then value.transform_values { |item| wrap(item) }
       when ::Array then value.map { |item| wrap(item) }
       when ::String then value.gsub(/[{}]/, CODE_BRACES)
       else value
@@ -20,6 +22,7 @@ module Raindown
     def self.unwrap(value)
       case value
       when Variables then value.to_h
+      when ::Hash then value.transform_values { |item| unwrap(item) }
       when ::Array then value.map { |item| unwrap(item) }
       when ::String then value.tr(CODE_BRACES.values.join, CODE_BRACES.keys.join)
       else value
@@ -28,7 +31,8 @@ module Raindown
 
     # A variable's value, like author.name, read the way {author.name} reads it, unwrapped. Unknown names are nil.
     def self.value(variables, name)
-      unwrap(name.split('.').reduce(variables) { |value, key| value.respond_to?(key) ? value.send(key) : nil })
+      first, *path = name.split('.')
+      unwrap(::Antlers::Queries.read_path(value: variables.send(first), path:))
     end
 
     def initialize(values)

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raindown
-  VERSION = '0.9.1'
+  VERSION = '0.10.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: 1.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: 1.4.0
 - !ruby/object:Gem::Dependency
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
@@ -213,6 +213,7 @@ files:
 - lib/raindown/document.rb
 - lib/raindown/endpoint/curl.rb
 - lib/raindown/endpoint/endpoint_runner.rb
+- lib/raindown/endpoint/endpoint_variables.rb
 - lib/raindown/files.rb
 - lib/raindown/fragments.rb
 - lib/raindown/front_matter.rb
@@ -307,11 +308,11 @@ files:
 - lib/raindown/workers/worker.rb
 - lib/raindown/workers/workers.rb
 - lib/version.rb
-homepage: https://github.com/raindeer-rb/raindown
+homepage: https://github.com/rainpour/raindown
 licenses: []
 metadata:
-  homepage_uri: https://github.com/raindeer-rb/raindown
-  source_code_uri: https://github.com/raindeer-rb/raindown/src/branch/main
+  homepage_uri: https://github.com/rainpour/raindown
+  source_code_uri: https://github.com/rainpour/raindown/tree/main
 rdoc_options: []
 require_paths:
 - lib