設定ファイルとしてYAMLを扱うことが多いため、yamlを便利に扱うためにyaml_vaultとyaml_masterというgemを作っている。
yaml_vaultはYAMLの特定キーを暗号化・複合化するためのgemで、yaml_masterはmasterファイルとして指定されたyamlから一部のキーだけを切り出して別ファイルに書き出したり、まとめて設定ファイルを生成したりするためのgemだ。
そして、最近この二つのgemを改修するためにRubyのYAML生成処理を調べたので、その知見をまとめておく。
yaml_vaultは元々の動作では暗号化したり複合化したりすると、YAMLのエイリアス記法が展開されてしまうという動作上の限界があった。
こういうのが
default: &default
adapter: mysql
encoding: utf8mb4
username root
production
<<: *default
password: secretpass
こうなる
default: &default
adapter: mysql
encoding: utf8mb4
username root
production:
adapter: mysql
encoding: utf8mb4
username root
password: <encrypted string>
また、yaml_masterは外部ファイルをincludeするための仕組みを実装していたのだが、それだとエイリアス記法が共有できないという限界があった。
yaml_master:
db: db.yml
default: &default
adapter: mysql
encoding: utf8mb4
username root
data
!include production.yml
# production.yml
production:
<<: *default
password: secretpass
こういう書き方をするとアンカーが見つからなくてエラーになる。
この二つの問題を解決するには、YAMLのASTを構築する段階で既に必要な処理が終わってる状態を作る必要がある。
RubyのYAMLライブラリはpsychというバックエンドライブラリが実際の処理をしている。今回、AST構築処理を弄るためにどこに処理を差し込めばいいかを調べた。
psychはPsych::ParserというクラスがYAMLのトークナイズをしてハンドラクラスのイベントハンドラメソッドを呼び出す。例えば処理対象がsequenceだったらstart_sequenceとend_sequenceを呼ぶ。
Psych::TreeBuilder < Psych::Handlerというクラスはイベントハンドラメソッドで、Psych::Nodes::<NodeType>クラスのインスタンスを生成し、YAMLのASTを構築する。
Psych::TreeBuilderの実装は以下の様になっている。
# frozen_string_literal: false
require 'psych/handler'
module Psych
###
# This class works in conjunction with Psych::Parser to build an in-memory
# parse tree that represents a YAML document.
#
# == Example
#
# parser = Psych::Parser.new Psych::TreeBuilder.new
# parser.parse('--- foo')
# tree = parser.handler.root
#
# See Psych::Handler for documentation on the event methods used in this
# class.
class TreeBuilder < Psych::Handler
# Returns the root node for the built tree
attr_reader :root
# Create a new TreeBuilder instance
def initialize
@stack = []
@last = nil
@root = nil
end
%w{
Sequence
Mapping
}.each do |node|
class_eval %{
def start_#{node.downcase}(anchor, tag, implicit, style)
n = Nodes::#{node}.new(anchor, tag, implicit, style)
@last.children << n
push n
end
def end_#{node.downcase}
pop
end
}
end
###
# Handles start_document events with +version+, +tag_directives+,
# and +implicit+ styling.
#
# See Psych::Handler#start_document
def start_document version, tag_directives, implicit
n = Nodes::Document.new version, tag_directives, implicit
@last.children << n
push n
end
###
# Handles end_document events with +version+, +tag_directives+,
# and +implicit+ styling.
#
# See Psych::Handler#start_document
def end_document implicit_end = !streaming?
@last.implicit_end = implicit_end
pop
end
def start_stream encoding
@root = Nodes::Stream.new(encoding)
push @root
end
def end_stream
pop
end
def scalar value, anchor, tag, plain, quoted, style
s = Nodes::Scalar.new(value,anchor,tag,plain,quoted,style)
@last.children << s
s
end
def alias anchor
@last.children << Nodes::Alias.new(anchor)
end
private
def push value
@stack.push value
@last = value
end
def pop
x = @stack.pop
@last = @stack.last
x
end
end
end
使う時はこんな感じ。
YAML::Parser.new(YAML::TreeBuilder.new).parse(yaml)
処理スタックを積みながら、ノードを生成しているだけなので簡単な作りになっている。
このクラスを継承して独自の処理を挟み込むことで、ASTを構築する段階で任意のフィルター処理を実行できる。
yaml_vaultではこの様な実装をしている。
require 'yaml'
module YamlVault
class YAMLTreeBuilder < YAML::TreeBuilder
def initialize(target_paths, cryptor, mode)
super()
@path_stack = []
@target_paths = target_paths
@cryptor = cryptor
@mode = mode
end
def start_document(*)
result = super
@path_stack.push "$"
result
end
def end_document(*)
@path_stack.pop
super
end
def start_mapping(*)
if YAML::Nodes::Sequence === @last
current_path = @last.children.size
@path_stack << current_path
end
super
end
def end_mapping(*)
@path_stack.pop
super
end
def start_sequence(*)
if YAML::Nodes::Sequence === @last
current_path = @last.children.size
@path_stack << current_path
end
super
end
def end_sequence(*)
@path_stack.pop
super
end
def scalar(value, anchor, tag, plain, quoted, style)
result = super
case @last
when YAML::Nodes::Sequence
current_path = @last.children.size - 1
@path_stack << current_path
when YAML::Nodes::Mapping
if @last.children.size.odd?
@path_stack << value
return result
end
end
if match_path?
if @mode == :encrypt
if tag
result.value = @cryptor.encrypt("#{tag} #{value}")
result.tag = nil
result.plain = true
else
result.value = @cryptor.encrypt(value)
end
else
decrypted_value = @cryptor.decrypt(value).to_s
if decrypted_value =~ /\A(!.*?)\s+(.*)\z/
result.tag = $1
result.plain = false
result.value = $2
else
result.value = decrypted_value
end
end
end
@path_stack.pop
result
end
def alias(anchor)
@path_stack.pop
super
end
private
def match_path?
@target_paths.any? do |target_path|
target_path.each_with_index.all? do |path, i|
if path == "*"
true
else
if path.is_a?(Regexp)
path.match(@path_stack[i])
else
path == @path_stack[i]
end
end
end
end
end
end
end
各イベントの処理を上書きして、独自のパススタックを積み、終端であるスカラー値まで到達したら、対象のキーパスを確認して暗号化・複合化の処理を行い、値を差し替える。
この時、valueはまだRubyオブジェクトに変換する前なので文字列のままになっている。
こうやって生成したASTはPsych::Nodes::Stream#to_yamlメソッドを呼ぶことで、ほぼ元のフォーマットを維持したままYAMLとして出力することができる。(流石に空行とかは消えるし、インデントスタイルもちょっと変わる場合がある)
また、YAMLはタグと呼ばれる機能がある。例えば!ruby/range 1..10の様に書くことができる。RubyのYAMLパーサーは、このタグを利用してYAMLが直接サポートしないオブジェクトをYAMLに埋め込むことができる。この例だとパース後にRubyオブジェクトに変換する際に1..10のRangeオブジェクトとして受け取ることができる。
上記実装例のscalarメソッドにはtag="!ruby/range" value="1..10"という値が渡ってくる。
その他、YAMLの書式のバリエーションによって、plain, quoted, styleの値が変わる。どういう書式がどの値になるかは、実際に何かのYAMLをパースさせてppで確認するのが楽だろう。
このタグを利用してyaml_masterの外部ファイルinclude機能も実装できた。
require 'yaml'
require 'pathname'
class YamlMaster::YAMLTreeBuilder < YAML::TreeBuilder
def initialize(master_path, properties, parser)
super()
@master_path = master_path
@parser = parser
end
def scalar(value, anchor, tag, plain, quoted, style)
case tag
if "!include"
ensure_tag_argument(tag, value)
path = Pathname(value)
path = path.absolute? ? path : @master_path.dirname.join(path)
tree = YAML.parse(File.read(path))
@last.children << tree.children[0]
else
super
end
end
private
def ensure_tag_argument(tag, value)
if value.empty?
mark = @parser.mark
$stderr.puts "tag format error"
$stderr.puts "#{tag} requires 1 argument at #{mark.line}:#{mark.column}"
exit 1
end
end
end
!includeタグが見つかったら、valueになっている値をファイル名として読み込んだ後YAML.parseをしてインクルード対象のASTを取得する。その後、スカラ値の代わりにそのAST自体を処理中のノードの子として突っ込む。
こうすることで、!include foo.yamlと書いた箇所は、そのままYAMLを記述した場合と完全に同じになる。
結果、ファイルを分割しながら、ベースのファイルにあるエイリアスを共有することができた。
ただし、そうやって書いたファイルは単独では読み込めなくなる。
上記の実装例は見易くするために色々省略をしているが、これを利用すればERBを使わなくても環境変数で値を置き換えたり、外部のテキストファイルから内容を読み込んで差し込む、といった機能が実現できる。
あんまり独自機能をYAMLに足してしまうと、他人に分かりにくくなるので、程々にしておいた方が良いものではあるが、TreeBuilderを弄ることで割と簡単にYAMLのパース結果を弄れるということを覚えておくと、役に立つかもしれない。