deathking (DeathKing)

Puppet 扩展研究 - 使用 Log.io 作为即时日志输出

deathking — Mon, 21 Sep 2015 13:47:20 +0800

绪言

手里有一系列 Puppet Hacking Guide 文集，但这些都只是从“原理剖析”的层面上来解释 Puppet 的内部运行原理，虽然给出了很多有用的扩展建议，但并没有“动真格地”给出一个扩展的实例。这篇文章，就是根据一个真实的需求来扩展 Puppet。但需要说明的是，这个扩展只是为了证成“需求是可以实现的”。之所以这么说，一方面是为糟糕的代码质量开脱，另一方面，是想要强调，本文所描述的并不是最终的解决方案，希望读者不要生搬硬套！

离职前，我在团队内部做了关于《Puppet Hacking Guide - 设计理念及运行原理》的内部技术分享，在会后 Q&A 环节，我的主管提出了这么一个需求，转述如下：

考虑 Puppet 的整个运行流程，当 Agent 端在完成整个部署后，才会向报告服务器发送报告。我们希望 Agent 在部署每一个资源后，能够马上将信息（尤其是错误信息）发送给服务器，以便尽快做出应急处理等。

由于这两个月一直在读 Puppet 源码，所以对它的运行原理还是相当熟悉的，当时想了一下，说感觉不难。然后隔天上午看了悠哉悠哉看了下 Puppet 日志处理的相关源码，吃过午饭后花了半小时把这个需求实现了。比较巧合的是，那天上午逛 GitHub 的时候，偶然看到了 Log.io 这个项目，然后就决定暂时先拿 Log.io 搞。这里将整个思考过程和解决方案记录下来，以供后人将这个需求整合入现有系统时参考。

一图胜千言，上个图：

启：突破口

参加过分享会的同学可能对这张 slide 已经没有什么印象了，但是这张幻灯片里面有个关键点，是实现这个需求的突破口：

关键点就是 Puppet::Util::Log.newdestination(report) 这句代码，正如我注释里写的那样，这段代码是为日志系统“添加”一个新的目的的，也就是每次日志系统的 IO 输出都会向这个 report 对象输出一份。我们的思路就是：编写一个新的日志目的地，当然，就是往远端服务器写日志！

承：Puppet 日志系统原理

Puppet 日志系统是这样处理新消息的：

def Log.newmessage(msg)
  return if @levels.index(msg.level) < @loglevel

  queuemessage(msg) if @destinations.length == 0

  @destinations.each do |name, dest|
    dest.handle(msg)
  end
end

具体来说：

如果日志的等级小于当前等级，那么我们直接忽视它（比如调试信息 debug 级的日志，不应该出现在产品级环境中）；
如果当前没有日志输出目的地的话，我们就将日志缓存在一个队列里面；
调用日志目的地的 handle 方法，来处理日志；

这段代码给我提供了两个关键信息：

同样一条日志，可能会写往多个目的地；
重要的是 handle 方法，我们编写的目的地需要响应 handle 这个方法；

实际上，打开文件 lib/puppet/util/log/destinations.rb ，我们可以发现 Puppet 自己定义的几个目的地，下面举几个比较有意思的例子；


# Log to a transaction report.
Puppet::Util::Log.newdesttype :report do
  attr_reader :report

  match "Puppet::Transaction::Report"

  def initialize(report)
    @report = report
  end

  def handle(msg)
    @report << msg
  end
end


Puppet::Util::Log.newdesttype :file do
  require 'fileutils'

  # 有意省略了部分代码

  def handle(msg)
    @file.puts("#{msg.time} #{msg.source} (#{msg.level}): #{msg}")

    @file.flush if @autoflush
  end
end

Puppet::Util::Log.newdesttype :array do
  match "Puppet::Test::LogCollector"

  def initialize(messages)
    @messages = messages
  end

  def handle(msg)
    @messages << msg
  end
end

file 是文件读写，report 是往一个 Report 对象里面写，array 就更有意思啦，可以往一个数组里面写，也就是把日志暂存在内存里面。不过我们再次看到，关键的关键是 handle 方法，我们实现 handle 方法就好。

到了这里，我们不得不提一下实现这个需求的另一个工具：Log.io，这是一个基于 Node.js 和 socket.io 的“实时日志监控系统”。

Log.io 的部署和使用都很简单，如果要发送一条日志，那么先通过 TCP 套接字连接上服务器，然后按照下面的格式发送消息：

+log|my_stream|my_node|info|this is log message\r\n

所以我们的 handle 方法将日志信息按格式写入这样的一个 TCP 连接即可，我实现的代码大致入戏下：


Puppet::Util::Log.newdesttype :logio do

  require 'socket'

  def send_message(msgstr)
    @connection.write "#{msgstr}#{ENDLINE}"
  end

  def send_log(msg)
    send_message build_log(msg)
  end

  def build_log(msg)
    time = get_log_time(msg)
    message = filter_message(msg)
    "+log|#@stream|#@node|#{msg.level}|[#{time}] #{msg.source} #{msg.level}: #{message}"
  end

  def handle(msg)
    send_log msg
  end

  def get_log_time(msg)
    msg.time.strftime(self.class.time_format)
  end

  # Maybe you wanto filter some message such as password stuff?
  # This method should have type Puppet::Util::Log -> String
  def filter_message(msg)
    msgstr = msg.to_s
    # all another filter methd should have type String -> String
    escape_message(msgstr)
  end

  def escape_message(msgstr)
    msgstr.gsub(ENDLINE, NEWLINE)
  end

  def send_close
    send_message(build_close_message)
  end

  def build_close_message
    "-node|#@node"
  end

  def close
    send_close
    close_connection
  end

  def close_connection
    if @connection
      @connection.close
      @connection = nil
    end
  end
end

函数拆分得有点散，主要是为了实现复用和扩展，这里说一下我的考虑：

由于 Log.io 支持几种不同的消息（比如，发送日志、流的注册、节点退订等），所以在我的实现里，最基本的语义是“发送一条 Log.io 消息”，Log.io 消息被定义为“一条字符串 + 结束符\r\n”，发送消息由 send_message 方法实现；
发送日志，则交由 build_log 方法构建一条格式化的日志，考虑到可能想要过滤一些敏感信息，因此定义了一个 filter_message 方法，来实现敏感信息的过滤。现在这个方法中只是调用了 escape_message 方法，将日志中出现的 \r\n 替换为 \n，避免系统错误地将一条日志分为多条（我感觉这个设定是没有必要的……），后期可以根据需要添加过滤方法，过滤在日志系统中出现的敏感信息（文章开头的那个图，我就是定义了一个 filter_domain 方法，将所有的域名信息都替换为 ** FILTERED **）；
可以通过覆盖 get_log_time 方法来自定义日志时间的格式化，不过这个的变动似乎不大；
最后是关闭 TCP 连接，在实际关闭之前，调用 send_close 方法，向服务器发送一个节点退订的消息（似乎发不发影响都不大？）；

下面说下初始化的问题。

我们定义每个日志输出目的地时，使用的是 Puppet::Util::Log.newdesttype 方法，这个方法用到了 Ruby 元编程的技巧，用来动态地创建一个类；

def self.newdesttype(name, options = {}, &block)

  dest = genclass(
    name,
    :parent     => Puppet::Util::Log::Destination,
    :prefix     => "Dest",
    :block      => block,
    :hash       => @desttypes,
    :attributes => options
  )
  dest.match(dest.name)

  dest
end

 # Create a new log destination.
def Log.newdestination(dest)
  # 有意省略了部分代码
  begin
    if type.instance_method(:initialize).arity == 1
      @destinations[dest] = type.new(dest)
    else
      @destinations[dest] = type.new
    end
    # 有意省略了部分代码
  end
end

注意到 if type.instance_method(:initialize).arity == 1 这句代码，会检查我们自定义目的地类的 initialize 方法的参数数目，initialize 方法要么是单参的，要么是无参的。单参的时候，传递过来的是一个对象，也就是我们通过 newdesttype 只是一个中介，最终的目的地是输出化时传递给 initialize 方法的那个对象。要理解这个设定比较复杂，我们就值考虑 initialize 方法是无参时候的情况，这时候，我们定义的 newdesttype 就应该是实际的目的地了。

我的实现中是这样实现的

Puppet::Util::Log.newdesttype :logio do

  attr_accessor :stream, :node

  DEFAULT_SERVER = "logio".freeze
  DEFAULT_PORT   = 28777
  DEFAULT_STREAM = "agent".freeze

  @time_format = "%Y-%m-%d %H:%M:%S %z".freeze

  class << self
    attr_reader :time_format

    def time_format=(str)
      @time_format = str.dup.freeze
    end
  end

  def initialize
    Puppet.settings.use :agent
    setup_log Puppet[:logio_stream], Puppet[:logio_node]
    setup_connection
  end

  def setup_connection
    server  = Puppet[:logio_server] || DEFAULT_SERVER
    port    = Puppet[:logio_port]   || DEFAULT_PORT
    @connection = TCPSocket.new(server, port)
  end

  def setup_log(stream, node)
    @stream = stream || DEFAULT_STREAM
    @node = node || Puppet[:certname]
  end
end

稍微解释一下我的考虑：

由于 Log.io 发送日志消息的时候有几个必要的要素：节点名、Stream 名、日志信息，而为了发这么一条日志，我们还需要知道 Log.io 的主机名、端口号等信息，现在我们没办法从参数中取得这样的信息，那么我们只能求助于 puppet.conf 文件（这样做带来的结果就是给用户有带来了更大的灵活性）
默认的 Log.io 主机名为 logio ，这样也可以通过改 Hosts 文件来实现 Log.io 主机的定位
提供了一个 setup_log 方法，这样程序员还有机会设置发送日志的节点名和订阅的 Stream 名

为了在 puppet.conf 文件中启用这些配置项，我们还需要在 defaults.rb 文件中加入下面的代码，这些代码是自注释的（你一看就知道大概是啥意思了）：



module Puppet

  define_settings(:agent,
                  :logio => {
                      :default => false,
                      :type    => :boolean,
                      :desc    => 'Whether to use Log.io to record live log for each resource.'
                  }
  )

  define_settings(:agent,
                  :logio_server => {
                      :default => "logio",
                      :type    => :string,
                      :desc    => 'The domain or hostname or the ip address of Log.io server.'
                  }
  )

  define_settings(:agent,
                  :logio_port => {
                      :default => 28777,
                      :desc    => 'The port of Log.io server.'
                  }
  )

  define_settings(:agent,
                  :logio_node => {
                      :default => "$certname",
                      :type    => :string,
                      :desc    => "The node name which used to identify the host on Log.io"
  }
  )

  define_settings(:agent,
                  :logio_stream => {
                      :default => "agent",
                      :type    => :array,
                      :desc    => "On which stream this host push to, may be a single stream or a group of streams
                     split by ',' symbol."
                  }
  )

end

转：怎么使用呢？

这个需要根据具体需求具体判断。因为我们只关心资源应用阶段的日志，所以我把它放到了 lib/puppet/configurer.rb 文件里面的 run_interal 方法中，读者可以看到有一行形如 Puppet::Util::Log.newdestination(report) 地代码，而我们只加了一行 Puppet::Util::Log.newdestination(:logio) 。如果你关心的是整个启动过程，那么你可以把这行代码加在尽可能早的地方。

class Puppet::Configurer
  # 有意省略了部分代码
  def run_internal(options)
    # We create the report pre-populated with default settings for
    # environment and transaction_uuid very early, this is to ensure
    # they are sent regardless of any catalog compilation failures or
    # exceptions.
    options[:report] ||= Puppet::Transaction::Report.new("apply", nil, @environment, @transaction_uuid)
    report = options[:report]
    init_storage

    Puppet::Util::Log.newdestination(report)
    Puppet::Util::Log.newdestination(:logio)  # <-- 使用我们定义的日志目的地

为什么我要把这节放到“转”呢？实际上，我并不满意这个扩展。在之前我通过编写 gem 来扩展 Puppet，我甚至没有修改一行 Puppet 源码！然而这次的扩展，我们不得不修改 run_internal 的源码，添加一行代码。这让我感觉很不爽。

Puppet 有一个 Plugin Hook 机制，它会尝试搜索一个 plugin_init.rb 的文件，加载并在适当的实际，调用其中的钩子方法（碍于时间关系，这里就不深入讨论了，有兴趣的同学可以读下 lib/puppet/application.rb 文件中 plugin_hook 方法的源码）。我们似乎可以可以通过在在这个文件中加点 Trick，以实现在不修改 Puppet 源码的基础上，实现我们的功能。但是 Puppet 搜索这个文件的机制有点操蛋，它只搜索 $LOAD_PATH ，并不会搜索所有安装的 gems 的路径还有编写的 Puppet 模块的路径，导致我们的这个想法也随之告吹。

所以，如果哪位对 Puppet 有更深入研究的同学知道如何更绿色地扩展这个需求，一定要让我知道！！！

总结

碍于时间关系，这篇文章并没有条理清晰地讲解我们整个思考过程，也没有像之前系列文章那样，仔细地考察 Puppet 的底层原理，但它描绘了一个骨架，一种可行性。有智慧的人总能找到他所需要的东西！

对于 Puppet 日志系统，似乎有很多可以改进的地方，比如可以将日志记录派发到一个后台队列，异步地执行（尤其是涉及到网络操作的日志系统），这样对于有多个日志目的地的系统，性能提升还是很明显的。

我们这个简单的解决方案还有很多要改进的地方，比如：

Puppet 本身有个 HTTP 连接缓存池，不过它是构建在应用层的，我们这里用到的是 TCP 连接，处在更加底层的传输层。我们可以模仿 Puppet HTTP 连接缓存池的实现，自己实现一个 TCP 连接的缓存池；
错误处理。目前我们的实现没有考虑网络通信的错误处理，不是很健壮。

目前相关项目已通过公司开源项目开源流程和对外披露流程，具体代码可以在以下 Repo 找到：

https://github.com/DeathKing/puppet-destlogio

Puppet Hacking Guide —— Puppet 的启动：守护进程

deathking — Mon, 21 Sep 2015 13:30:27 +0800

Acknowledgment

本系列文集是在我受雇于阿里巴巴期间撰写的一系列技术文档重新整理而成，其版权属于阿里巴巴公司以及我本人。经雇主同意，现特许以技术交流为目的，在开源技术社区分享此文集。

因此您可以：在保留原作者 DeathKing 以及阿里巴巴 - 技术保障部署名的情况下，以学习交流为目的，以非盈的形式将本文以电子版或印刷版的形式分发给您的朋友，或者转载到任何一个开源社区；

以下行为是禁止的：

以盈利为目的，将文章转载到微信公众号等媒体平台；
去掉原作者 DeathKing 以及阿里巴巴 - 技术保障部的署名，以自己的名义发布本文集；

请在转载时，保留以下署名：

本系列文章作者 DeathKing
阿里巴巴技术保障部

在默认的工作流中，Puppet Agent 会以守护进程的方式运行，每 30 分钟与 Puppet Master 同步一次。为了方面交互式测试，可以在调用 Puppet 时使用 --no-daemonize 选项，这样 Puppet 则会阻止程序的后台化，日志信息会全部输出在终端中。

我们自然而然地会产生如下的疑问：

Puppet 是如何实现进程的后台化的？
调度又是体现在何处？

本文就将解答以上问题。理解后台进程的原理，将有助于我们认识 Puppet Agent 和 Master 的工作原理。

Daemon: 可后台化进程

为了避免长时间占据系统前台，周期性的任务或者网络服务器都应该实现为守护进程，放入系统后台执行。Puppet 提供的 Puppet::Daemon 类实现了可后台化（daemonized）进程。我们把这些在后台执行的、并不直接被用户操控的进程称为守护进程（Daemon Process）。我们将 Daemon 类实现的进程称为是“可后台化的”，是因为程序员可以根据需要选择是否将这个进程放入后台执行，而并非强制将进程放入后台执行。

一个守护进程必须有：

一个配置重解析器（Reparser），它需要能够重新解析配置文件并应用到系统，以应对配置文件或清单文件的修改；
（要么有）能够响应 run 方法的代理（Agent）；
（要么有）能够响应 stop、start 和 wait_for_shutdown 方法的服务器（Server）；

需要强调的是，必须至少为守护进程配置一个代理或服务器，否则 Puppet 会抛出 Puppet::DevError 异常。同时，这里的代理指的是可以被守护进程调用并自主执行的对象（可以将此处的 Agent 非正式地理解为实际的业务代码），而并非 Puppet Agent——后者是一个 Puppet 子命令程序，请读者仔细甄别两者。

代理和配置重解析器都可以按照配置文件中的设定，周期性地运行（Puppet[:filetimeout]）。考虑到在代码的执行过程中，配置文件会发生改变。因此配置解析器会在每次运行时重新解析配置文件，以更新其自身和代理的运行周期。

守护进程会调用 server.start 来启动服务器，但服务器应该自己管理运行循环（run loop），以避免阻塞守护进程的运行。同时，服务器需要有一个 wait_for_shutdown 方法来等待线程的结束。

Daemon 的层次观

Daemon 的实现用了许多基本组件，Puppet 按照一定的层次组织了这些组件：

Puppet 子命令应用程序可能会拥有一个守护进程，而守护进程的代码实体可能是一个代理或网络服务器（或者两者都有）；
守护进程用 Pidlock 来管理 PID 文件，Pidlock 更底层的实现是 Lockfile 类；
守护进程还有一个调度器（Scheduler），该调度器以作业（Job）为基本单位，调度程序运行；
调度器有个计时器（Timer），调度器根据计时器的时间戳来检查作业的调度；
每个作业负责启动代理或配置重解析器的执行；

请注意第 1 点，对于 Puppet Agent 来说，它可能会为守护进程设置一个 agent ，该代理执行的是实际与 Puppet 通信的业务代码；而对于 Puppet Master 来说，它可能会给一个守护进程设置一个 server ，以提供 HTTP API 服务，使得 Puppet Agent 能够与之通信。对于这两种分别单独设置 agent 或 server 的情况，似乎都很容易理解，那么有没有同时设置 agent 和 server 的情况呢？

答案是肯定的。Puppet 3.X 版本中提供了一个 puppet kick 命令，允许用户远程触发 Puppet Agent 的同步。其具体实现就是，在为 Puppet Agent 的后台进程设置 agent 的同时也设置 server ，从而实现对远程命令的监听。但是这个功能在 Puppet 4.X 以后就被取消了。

下图是一个非正式地 UML 图，它描绘了 Daemon 各组件之间的层次观：

注意

希望 Java 背景的读者注意到这样一个事实：Ruby 中并没有接口（Interface）这一说法，取而代之的是所谓的“鸭子类型”，或者说“面向协议”编程。在本例中，Daemon 类对于代理和服务器有特定的要求，如果按照 Java 程序员的观点，可以理解为我们有 Agent 和 Server 两个抽象类，前者包含抽象方法 run() ，而后者包含抽象方法 start()、stop()、wait_for_shutdown()，Puppet 要求传递给 Daemon 的代理或服务器需要分别实现这两个接口。
虽然我们的 UML 图是按照 Java 的观点来绘制的，但是 Ruby 并不要求有什么继承或实现关系，只要对象具有特定的方法即可。

Daemon 的数据结构及初始化

实例变量	类	初始值	说明
@scheduler	Puppet::Scheduler::Scheduler	Puppet::Scheduler::Scheduler.new	任务调度器。
@pidfile	Puppet::Util::Pidlock	由参数传递	PID 文件。
@agent	{#run}	nil	代理。
@server	{#stop, #start, #wait_for_shutdown}	nil	网络服务器。
@argv	Array	nil	命令行参数。

需要注意的是，Daemon 的初始化只完成了对 @pidfile 和 @scheduler 的设置，@agent 、@server 和 @argv 的设置由相应的 setter 方法完成。

daemonize：进程后台化

文件：lib/puppet/daemon.rb

def daemonize
  if pid = fork
    Process.detach(pid)
    exit(0)
  end

  create_pidfile

  # Get rid of console logging
  Puppet::Util::Log.close(:console)

  Process.setsid
  Dir.chdir("/")

  close_streams
end

Puppet 通过 fork、detach 方法的组合来实现进程的后台化。

fork 方法为当前进程创建一个子进程，子进程是父进程的副本，它将获得父进程数据空间、堆、栈等资源的副本。如果不是以传递代码块的方式调用 fork 方法，那么 fork 会返回两次，在父进程中，fork 方法返回子进程的进程 ID 号，而在子进程中，fork 返回 nil 。

当子进程退出以后，某些操作系统仍然会为其维护一个包含了其退出码的数据结构，如果父进程不通过 wait() 及其变种系统调用来收集这些退出状态的话，操作系统中将产生大量的僵尸进程（Zombie Process）。当我们不想显式地等待子进程结束时，可以使用 Process::detach 方法创建一个单独的 Ruby 线程，用来收集子进程的退出码。

父进程调用 exit(0) 结束自己的生命周期，因此 if..end 语句之后的代码，都是由后台进程——也就是我们创建的子进程来执行的。create_pidfile 方法用于为我们的守护进程创建 PID 文件并加锁，主要作用是保证在系统中只存在该守护进程的一个实例，同时也便于系统统一管理这些守护进程。

后续的代码分别完成：

不让日志输出到终端；
将进程设置为新的会话的领头进程，并与其父进程的会话组和进程组脱离；
将路径切换至根目录；
关闭 stdin、stdout 和 stderr 以完成进程的后台化；

start：守护进程的运转

start 方法用于启动整个守护进程的实际运转，该方法首先调用 set_signal_traps 设定进程的信号处理，然后调用 create_pidfile 方法创建 PID 文件。需要注意的是，用户可能会使用 --no-daemonize 方法要求 Puppet 不要以守护进程的方式执行，因此虽然 daemonize 方法定义了 PID 文件的创建与加锁，但它很可能没被调用，所以我们也要在 start 方法里面再次调用 create_pidfile 方法，这样可以确保进程的 PID 文件被创建且正确加锁。

文件：lib/puppet/daemon.rb

def start
  set_signal_traps

  create_pidfile

  raise Puppet::DevError, "Daemons must have an agent, server, or both" unless agent or server

  # Start the listening server, if required.
  server.start if server

  # Finally, loop forever running events - or, at least, until we exit.
  run_event_loop

  server.wait_for_shutdown if server
end

如果没有为守护进程配置代理或服务器，那么 Puppet 抛出一个异常。Puppet 要求服务器的运行循环不能阻塞守护进程的运行，所以调用 server.start 后，Puppet 进入守护进程的运行循环（run_event_loop），该循环会一直占据主线程，直到执行完毕主动退出。最后，server.wait_for_shutdown 会等待服务器的结束。

run_event_loop：主运行循环

文件：lib/puppet/daemon.rb

def run_event_loop
  agent_run = Puppet::Scheduler.create_job(Puppet[:runinterval], Puppet[:splay], Puppet[:splaylimit]) do
    # Splay for the daemon is handled in the scheduler
    agent.run(:splay => false)
  end

  reparse_run = Puppet::Scheduler.create_job(Puppet[:filetimeout]) do
    Puppet.settings.reparse_config_files
    agent_run.run_interval = Puppet[:runinterval]
    if Puppet[:filetimeout] == 0
      reparse_run.disable
    else
      reparse_run.run_interval = Puppet[:filetimeout]
    end
  end

  reparse_run.disable if Puppet[:filetimeout] == 0
  agent_run.disable unless agent

  @scheduler.run_loop([reparse_run, agent_run])
end

守护进程的主运行循环通常会创建两个作业（Job），并周期性地调用它们：

agent_run：负责调用代理的 run 方法；
reparse_run：负责重新解析配置文件，并更新 agent_run 和 reparse_run 的运行周期；

这两个作业交由调度器 @scheduler 调度，@scheduler.run_loop 会不断调度传递过来的作业，直到所有作业都变成无效为止。

这里需要提及一下 SplayJob ，如果在配置文件中启动了 splay 选项，那么 Puppet 在创建调度作业时，会则会 SplayJob 作业。SplayJob 作业在到达指定启动时间后，会随机延迟一定时间再启动，这是为了避免成千上万台 Puppet Agent 同时启动所带来的惊群效应——如此高的并发量，将对 Puppet Master 构成相当严峻的挑战！

stop：守护进程的终止

文件：lib/puppet/daemon.rb

def stop(args = {:exit => true})
  Puppet::Application.stop!

  server.stop if server

  remove_pidfile

  Puppet::Util::Log.close_all

  exit if args[:exit]
end

守护进程的终止比较容易理解，主要是：

Puppet::Application.stop!：给当前运行的应用发送停止请求；
server.stop if server：如果启动了服务器，那么就将其停止；
remove_pidfile：解锁并移除进程的 PID 文件；
Puppet::Util::Log.close_all：关闭所有的日志；
exit if args[:exit]：如果没有特别指明，那么退出进程；

需要说明的是，如果守护进程并不是放在后台执行的，此时守护进程由主线程执行。那么要在调用 stop 时，需要置 exit 一项为 true，避免退出整个 Ruby 解释器；

set_signal_traps：设置信号处理

文件：lib/puppet/daemon.rb

def set_signal_traps
  signals = {:INT => :stop, :TERM => :stop }
  # extended signals not supported under windows
  signals.update({:HUP => :restart, :USR1 => :reload, :USR2 => :reopen_logs }) unless Puppet.features.microsoft_windows?
  signals.each do |signal, method|
    Signal.trap(signal) do
      Puppet.notice "Caught #{signal}; calling #{method}"
      send(method)
    end
  end
end

set_signal_traps 方法调用 Signal.trap 方法为一些主要的信号添加处理程序。Microsoft Windows 系统并不支持 HUP、USR1 和 USR2 信号，所以对于 Windows 系统，不要处理处理信号。

Puppet Hacking Guide —— Puppet 的启动：子命令

deathking — Wed, 16 Sep 2015 09:52:55 +0800

“知己知彼，百战不殆。——《孙子·谋攻篇》”

在阿里巴巴实习期间，由于各种机缘巧合，我开始专注于研读配置自动化管理软件 Puppet。这项工作持续了两个月，期间我在内网发布过多篇技术文章，详细地剖析 Puppet 的运行原理。业已实习完毕，所有的技术文档、演示幻灯以及部分实例源码，均已通过阿里巴巴对外数据披露备案，被允许向开源社区分享这些技术文档。社区曾给了我很多帮助，我想，现在是时候我向社区尽一些绵薄之力了。

虽然没有把 Puppet 多达 10 万行的源码彻底地分析清楚，但大致的脉络已经理清。整个系列文集将会以《Puppet Hacking Guide》为总标题（致敬《Ruby Hacking Guide》），解释 Puppet 3.X 版本的内部运行原理，为用户定制 Puppet 提供指导。整个系列以我在阿里巴巴内部发表的文章为草稿，重新组织整理，以期能以一种清晰的思路引导读者理解 Puppet 源码。

尽管本文几经修改，但笔者才疏学浅，难免有所纰漏，欢迎各位指正！另外，出于职业道德，我不能向各位透露以下信息，也请各位不要打听，见谅：

Puppet 在阿里巴巴内部的使用场景；
阿里巴巴所使用的 Puppet 具体版本号；
阿里巴巴所采用的 Puppet 体系架构；

另外，如果读者所在公司有定制 Puppet 的需求，可以联系我，我可以在研究需求后，给出一些可行的方案。

Acknowledgment

以下行为是禁止的：

以盈利为目的，将文章转载到微信公众号等媒体平台；
去掉原作者 DeathKing 以及阿里巴巴 - 技术保障部的署名，以自己的名义发布本文集；

请在转载时，保留以下署名：

本系列文章作者 DeathKing
阿里巴巴技术保障部

Puppet 的启动：子命令

Puppet 的启动方式

Puppet Agent 通常通过命令行触发，而 Puppet Master 即可以通过命令行方式触发，以 WEBrick 服务器模式运行，也可以通过设置 config.ru 文件，以 Rack 中间件的形式运行。

下面的命令可以让 Puppet Master 以 WEBrick 服务器的模式启动，选项 --no-daemonize 可以阻止 Master 的后台化，在测试的时候，我们通常添加一个 --debug 选项用以设置日志等级，让 Puppet 显示更多有用的信息方便系统管理员进行调试：

$ puppet master --no-daemonize --debug

下面的命令可以启动 Agent 使之与 Master 进行通信并完成一次完整的工作流。与默认的 Agent 与 Master 每 30 分钟同步一次不同，选项 --onetime 使得 Agent 与 Master 只进行一次同步，完成后立即退出。

$ puppet agent --no-daemonize --debug --onetime

要了解 Master 和 Agent 的启动过程，就需要先知道 Puppet 中子命令的概念，使用 puppet help 可以查看 Puppet 的使用帮助：

$ puppet help

Usage: puppet <subcommand> [options] <action> [options]

Available subcommands:

  agent             The puppet agent daemon
  apply             Apply Puppet manifests locally
  ca                Local Puppet Certificate Authority management.
  # 有意省略了整个列表。

从使用帮助中，我们不难看出，跟在 puppet 命令后的参数被称作子命令（subcommand）。子命令通常对应了一个 Ruby 脚本文件或外部可执行文件。事实上，不单 agent 和 master 分别是一个 Puppet 子命令，连 help 也是 Puppet 的一个子命令，对应的是 lib/puppet/application/help.rb 文件。Puppet 将不同的功能模块抽象为子命令，并将这些子命令实现为不同的文件，这样实现和管理起来更为方便。

子命令分类

Puppet 子命令可以分为四类：

空子命令：调用 Puppet 时，如果没有指定任何子命令，Puppet 则认为调用的是空子命令；
应用子命令：存放在 puppet/application 文件夹中的脚本所对应的命令。需要注意的是，这是一个相对路径，Puppet 会在多个路径中搜索该相对路径下的文件。这类子命令的典型的代表是 agent、master 和 config 等；
外部子命令：存放在环境变量 PATH 所指示的文件夹中、以 puppet- 开头的文件所对应的命令。例如，命令行调用 puppet foo 会使 Puppet 在环境变量 PATH 所指示的文件夹中搜寻名为 puppet-foo 的可执行文件；
未知子命令：不是上述命令的其他子命令，Puppet 都将其视作未知子命令；

子命令的查找与加载

以命令行调用 Puppet 时，实际执行的是 bin\puppet 。作为整个系统的入口，这个文件却只有简单的几句代码：

文件：bin\puppet

#!/usr/bin/env ruby

# For security reasons, ensure that '.' is not on the load path
# This is primarily for 1.8.7 since 1.9.2+ doesn't put '.' on the load path
$LOAD_PATH.delete '.'

require 'puppet/util/command_line'
Puppet::Util::CommandLine.new.execute

bin\puppet 主要实例化了一个 Puppet::Util::CommandLine 对象，这个对象主要用于理清 Puppet 的调用信息：调用的是哪个命令、有哪些命令行选项等。在后面的章节中我们会发现，如果以 Rack 中间件的方式启动 Puppet Master，会用到一些 trick，这也是 CommandLine 存在的原因。

CommandLine 对象实例化完毕后，execute 方法被执行。在这个方法中，最重要的是 find_subcommand.run 语句。

文件：lib/puppet/util/command_line.rb

def execute
  Puppet::Util.exit_on_fail("initialize global default settings") do
    Puppet.initialize_settings(args)
  end

  setpriority(Puppet[:priority])

  find_subcommand.run
end

CommandLine 类的私有方法 find_command 是理解整个启动机制的关键点，Puppet 在这个方法中，通过一些规则确定子命令的分类，然后再调用子命令对应的类，加载对应的文件。

文件：lib/puppet/util/command_line.rb


private

def find_subcommand
  if subcommand_name.nil?
    NilSubcommand.new(self)
  elsif Puppet::Application.available_application_names.include?(subcommand_name)
    ApplicationSubcommand.new(subcommand_name, self)
  elsif path_to_subcommand = external_subcommand
    ExternalSubcommand.new(path_to_subcommand, self)
  else
    UnknownSubcommand.new(subcommand_name, self)
  end
end

需要强调的是，Puppet 并不是根据命令的分类去查找文件，而是根据文件查找的结果，确定命令的分类，理解这一点很重要。在深入每句代码内部之前，我们应该对 find_subcommand 方法的模式有个大概认知：查找方法，然后实例化一个对应类的对象。比较令人疑惑的是，用于实例化的参数中有一个 self 。这里的 self 就是 CommandLine 对象，我们之前已经说过，CommandLine 对象已经理清了命令行调用的信息，因此我们可以在每个 Subcommand 对象中，通过 CommandLine 对象获得调用的命令行参数等信息。

Puppet 的命令分类我们已经在前面描述了，接下来，我们将详细地讨论查找的规则。由于空子命令和未知子命令的代码比较简单，我们先行介绍，接着我们将介绍外部子命令，我们最后再来分析最为复杂的内部子命令。

空命令与未知命令

将这两个命令放在一起讨论，是因为在某种程度上，这两者是一致的，以至于 UnknownSubcommand 是 NilSubcommand 的子类。前面已经说过，如果调用 Puppet 时，没有指明任何子命令，则实例化 NilSubcommand ，如果调用的子命令既不是内部子命令，又不是外部子命令，那么则实例化 UnknownSubcommand 。两者的区别在于——考虑到puppet --version 这样的输入也是合法的，NilCommand 通常要处理 -v 或 --version 选项，即显示版本号。

文件：lib/puppet/util/command_line.rb

class NilSubcommand
  include Puppet::Util::Colors

  def initialize(command_line)
    @command_line = command_line
  end

  def run
    args = @command_line.args
    if args.include? "--version" or args.include? "-V"
      puts Puppet.version
    elsif @command_line.subcommand_name.nil? && args.count > 0
      # If the subcommand is truly nil and there is an arg, it's an option; print out the invalid option message
      puts colorize(:hred, "Error: Could not parse application options: invalid option: #{args[0]}")
      exit 1
    else
      puts "See 'puppet help' for help on available puppet subcommands"
    end
  end
end

# @api private
class UnknownSubcommand < NilSubcommand
  def initialize(subcommand_name, command_line)
    @subcommand_name = subcommand_name
    super(command_line)
  end

  def run
    puts colorize(:hred, "Error: Unknown Puppet subcommand '#{@subcommand_name}'")
    super
    exit 1
  end
end

空对象模式

可能部分读者不太理解为什么要把空子命令和未知子命令抽象分别抽象为一个类，实际上，这里用到了一种称为“空对象模式（Null Object Pattern）”的设计模式。在大多数地方，这个模式的定义非常暧昧，根据在此处的使用场景，也许按照下面的方式理解空对象模式会更好一些：

空对象模式
将对缺失对象的错误处理，封装在一个用于表征缺失对象的类的一个方法中。

你也许无法立马理解这个拗口的定义，让我们回过头来审视 find_command 方法：

def find_subcommand
   if subcommand_name.nil?
     NilSubcommand.new(self)
   # 有意省略了部分代码
   else
     UnknownSubcommand.new(subcommand_name, self)
   end
 end

想一想，我们能不能把空子命令、未知子命令的处理逻辑放在 if 子句、else 子句中呢？更进一步地，我们考虑 find_subcommand 方法的调用者，find_subcommand.run ，我们是否可以写成这样的形式呢：

if subcommand = find_subcommand
  subcommand.run
else
  # logic for object not found
end

当然，从语法角度上来说，这些都是可以的！但请思考，这样做真的合适么？这样做真的是“面向对象设计”么？答案是否定的。请看下面的调用关系，并仔细思考：

我们观察到：find_subcommand 方法的语义是查找一个特定的命令，这个命令要能够响应 run 方法。这样，当我们没有找到合适的子命令时，与其返回特殊值 nil 用于表征“对象没找到”，不如返回一个“空对象”表示“嗨，我找到了这么一个对象，但这个对象是‘空的’”。虽然后者看起来是绕了一个圈子，但两者的重要区别在于：“空对象可以响应 run 方法！因而，我们可以将错误处理的逻辑放在 run 方法中。”

下面这幅图演示了处理逻辑位置的变化，我们发现，处理逻辑被移动到了方法的内部。

空对象模式有什么好处呢？除了绕了一个圈子，我们似乎看不到任何一点好处。实际上，如果你只有一段这样的代码，是否使用了空对象模式都并没有太大的关系，但请考虑这段代码在系统的各个地方重复出现时的情景：

重复（Duplication）是一件非常危险的事，这种违背 DRY 原则的做法，很容易导致系统的不一致性。如果我们要修改失败时的逻辑，那么我们又需要在系统各个地方复制 - 粘贴大量的代码，我们能保证所有的出现都被有效地更新了吗？而考虑使用空对象模式的情景，缺失处理的代码被移动到了一个方法中，这样使得处理逻辑只有一份副本，对方法所做的修改，可以一致地应用到系统全局。

空对象模式的优势与劣势

设计模式只是一种工具，并不是最终目的，我们不能为了用设计模式而用设计模式。严肃的工程师需要仔细分析这些工具的适用场景。对于空对象模式来说，它的优势在于：

由于将逻辑封装在了一个方法中，由外部调用该方法，实践了 DRY 原则，极大程度上提高了代码的复用性；
通过合理地拆分，降低了系统耦合度，使得业务逻辑更加清晰；
由于可以在空对象的类中统一修改方法定义，避免了因为代码冗余而产生的不一致行为；

当然，空对象模式依然存在一些劣势：

不适合用在上下文高度相关的场景，因为此时我们很难对系统进行合理地拆分解耦；
可能会产生各种类型的空对象类，因此维护任务并没有消失，只是转移到对各个空对象类的维护上去了；

程序员在设计软件时，应该仔细取舍，合理地使用这些模式！

后话

理解空对象模式了么？它只是一种教条主义的繁文缛节么？如果我的解释并没有让读者信服，那么不妨聆听 Sandi Metz 在 RailsConf 2015 上的演讲 Nothing is Something ，这一定会再次震撼你的！

外部子命令

查找规则

外部子命令的查找由 external_subcommand 方法实现，如果指定的外部子命令存在（我们说过，外部子命令是一个可执行文件），则返回该可执行文件的路径。

文件：lib/puppet/util/command_line.rb


private

def find_subcommand
  # 有意省略了部分代码
  elsif path_to_subcommand = external_subcommand
    ExternalSubcommand.new(path_to_subcommand, self)
  # 有意省略了部分代码
end

Puppet 会以 puppet-<subcommand> 作为文件名，在 PATH 环境变量中的指定的路径下进行查找。例如，当我们在命令行调用 puppet foo 启动 Puppet 时，Puppet 会尝试在 PATH 所对应的路径中，寻找名为 puppet-foo 的可执行文件。对于 Windows 系统，Puppet 会尝试为 puppet-foo 文件加上 .COM、.EXE、.BAT、.CMD 等 Windows 可执行文件的后缀名进行查找。

外部命令路径的解析由 Puppet::Util.which 方法提供。它实现了一个类似于 UNIX 系统中 which 命令，可以传递给该方法一个绝对路径，或者命令名。如果找到该命令，则返回对应的绝对路径，否则抛出异常。

执行

def run
  Kernel.exec(@path_to_subcommand, *@command_line.args)
end

Ruby 解释器不对外部命令的执行负责，直接调用 Kernel.exec，用外部命令的进程替换掉当前 Puppet 的进程。

小实验：用 Puppet 执行外部命令

首先，让我们为 top 命令创建一个别名：

$ which top
/usr/bin/top

$ sudo ln -s /usr/bin/top /usr/bin/puppet-top

现在，调用 puppet top ，我们马上就进入了 top 命令。这个小实验为扩展 Puppet 提供了一些思路，但考虑到执行外部命令时，Puppet 会让出控制权，因此这样的扩展是及其有限的。

应用子命令

查找规则

在讨论完三种相对简单的子命令后，我们将关注的焦点移动到相对复杂的内部子命令中。首先，“应用子命令”可能不是一个很好的名字，也许叫做“内部子命令（InternalSubcommand）”更佳合适。这是因为 ApplicationSubcommand 所对应的文件会被 Ruby 解释器加载，并在 Puppet 程序的上下文中继续执行——这与替换掉 Puppet 进程执行的外部子命令形成了鲜明对比。

文件：lib/puppet/util/command_line.rb


private

def find_subcommand
  # 有意省略了部分代码
  elsif Puppet::Application.available_application_names.include?(subcommand_name)
    ApplicationSubcommand.new(subcommand_name, self)
  # 有意省略了部分代码
end

类方法 Puppet::Application.avaliable_application_names 可以根据搜索查找到的文件，返回所有可以使用的子命令的名字构成的数组。如果 <subcommand> 存在于这个数组中，那么它就被定义为一个应用子命令。下面是 avaliable_application_names 方法的定义：

文件：lib/puppet/application.rb


@loader = Puppet::Util::Autoload.new(self, 'puppet/application')

  # 有意省略了部分代码

  # @return [Array<String>] the names of available applications
  # @api public
  def available_application_names
    @loader.files_to_load.map do |fn|
      ::File.basename(fn, '.rb')
    end.uniq
  end

puppet/application 文件夹下的脚本文件所对应的子命令都是应用命令，例如，子命令 agent 就与 puppet/application/agent.rb 文件相对应。需要注意的是，Puppet 利用了一个 Puppet::Util::Autoload 类的对象 @loader 来执行目录查找，而 Autoload 对象的默认查找的路径包括：

gem_directories：当前系统安装的所有 gem 的路径；
module_directories(env)：安装的所有 Puppet 模块的路径；
libdirs：Puppet lib 文件夹的路径，默认值是 $vardir/lib；
$LOAD_PATH：Ruby 的文件加载路径；

理解应用子命令的查找规则后，我们开始考虑应用子命令的加载与执行。

加载

由于 Autoload 类的设计，脚本文件的内容还需要满足一些约束：

必须定义在 Puppet::Application 命名空间下；
必须是 Puppet::Application 的子类；
必须采用驼峰式大小写风格书写类名；

也就是说，应用子命令 my_subcommand 应该对应：

puppet/application/my_subcommand.rb 文件；
文件中应该包含这样的类定义： class Puppet::Application::MySubcommand < Puppet::Application ；

如果 my_subcommand 对应的是一个有效的应用子命令，那么 Puppet 就使用一个 ApplicationSubcommand 来加载它。ApplicationSubcommand#run 方法会被调用，在此方法中，代码 Puppet::Application.find 方法用于找到 @subcommand_name 所对应的 Ruby 文件，加载该 Ruby 文件，并返回在该 Ruby 文件中定义的类。这样做之所以可行，是因为就像我们前面所解释的那样，文件名和文件内容之间需要满足一定的映射关系。类似的技巧在很多 Ruby 项目中使用。

文件：lib/puppet/util/command_line.rb

class ApplicationSubcommand
  def run
    # 有意省略了部分代码

    app = Puppet::Application.find(@subcommand_name).new(@command_line)
    Puppet::Plugins.on_application_initialization(:application_object => @command_line)

    app.run
  end
end

随后的 new 会实例化该类的一个对象，并且，Puppet 会将 @command_line 作为参数传递给 new 方法，这样，我们编写的子命令就可以通过解析 @command_line 来处理命令行参数。

实例化完成以后，加载过程完成，调用 app.run，进入到子命令的执行。程序的控制权转移到 Puppet::Application 类及其特定子类。

执行

Puppet 所有的应用命令都继承自 Puppet::Application 类，而子类大多没有覆盖父类的 run 方法，因此我们有必要考察一下 Application 类是如何定义命令的执行的。

文件：lib/puppet/application.rb

def run

  exit_on_fail("get application-specific default settings") do
    plugin_hook('initialize_app_defaults') { initialize_app_defaults }
  end

  Puppet.push_context(Puppet.base_context(Puppet.settings), "Update for application settings (#{self.class.run_mode})")

  configured_environment_name = Puppet[:environment]
  if self.class.run_mode.name == :agent
    configured_environment = Puppet::Node::Environment.remote(configured_environment_name)
  else
    configured_environment = Puppet.lookup(:environments).get!(configured_environment_name)
  end
  configured_environment = configured_environment.override_from_commandline(Puppet.settings)

  # Setup a new context using the app's configuration
  Puppet.push_context({ :current_environment => configured_environment },
                  "Update current environment from application's configuration")

  require 'puppet/util/instrumentation'
  Puppet::Util::Instrumentation.init

  exit_on_fail("initialize")                                   { plugin_hook('preinit')       { preinit } }
  exit_on_fail("parse application options")                    { plugin_hook('parse_options') { parse_options } }
  exit_on_fail("prepare for execution")                        { plugin_hook('setup')         { setup } }
  exit_on_fail("configure routes from #{Puppet[:route_file]}") { configure_indirector_routes }
  exit_on_fail("log runtime debug info")                       { log_runtime_environment }
  exit_on_fail("run")                                          { plugin_hook('run_command')   { run_command } }
end

这里用到了模板方法的模式，run 方法定义了子类方法执行的步骤，子类只需要完成或实现这些方法即可：

这里有必要明确地提一下 exit_on_fail 这个方法，这个方法由模块 Puppet::Util 提供。由于在顶层环境抛出异常会导致 Ruby 解释器退出，所以 Puppet 特意封装了 exit_on_fail 这个方法。我们可以将想要执行的代码作为代码块传递给 exit_on_fail ，后者会帮我们做异常处理。

文件：lib/puppet/util.rb

# Executes a block of code, wrapped with some special exception handling.  Causes the ruby interpreter to
#  exit if the block throws an exception.
#
# @api public
# @param [String] message a message to log if the block fails
# @param [Integer] code the exit code that the ruby interpreter should return if the block fails
# @yield
def exit_on_fail(message, code = 1)
  yield
# First, we need to check and see if we are catching a SystemExit error.  These will be raised
#  when we daemonize/fork, and they do not necessarily indicate a failure case.
rescue SystemExit => err
  raise err

# Now we need to catch *any* other kind of exception, because we may be calling third-party
#  code (e.g. webrick), and we have no idea what they might throw.
rescue Exception => err
  ## NOTE: when debugging spec failures, these two lines can be very useful
  #puts err.inspect
  #puts Puppet::Util.pretty_backtrace(err.backtrace)
  Puppet.log_exception(err, "Could not #{message}: #{err}")
  Puppet::Util::Log.force_flushqueue()
  exit(code)
end
module_function :exit_on_fail

回到 run 方法中来，在它定义的几个步骤中，除 run_command 方法外，其它几个方法都在 Application 中定义好了，子类只需要根据具体需求覆盖这些方法即可。而 run_command 方法通过一些 Ruby 技巧，间接实现了 Java 中的抽象方法的效果——如果子类没有实现该方法，程序就会抛出异常——这意味着子类必须实现该方法。因此，我们需要尤为关注这个方法。

def main
  raise NotImplementedError, "No valid command or main"
end

def run_command
  main
end

子类可以根据需要选择覆盖 main 方法或 run_command 方法实现实际的执行结果。

小实验：以应用子命令的方式扩展 Puppet

在“查找规则”小节中，我们介绍 Puppet 会从四个路径搜索应用子命令，这为我们扩展 Puppet 提供给了无穷的想象力。在本节中，我们将简单介绍，如何通过编写 Ruby Gem 来实现一个 Puppet 应用子命令。

首先，我们需要新建一个 Ruby Gem，我们可以利用 Bundler 来创建一个 Gem 骨架：

$ bundler gem my_app

然后新建 lib/puppet/application 目录，并在该目录下新建 my_app.rb 文件。作为示例，这里在文件中输入下面的内容，其中，options 是在 Application 类中定义的用于参数处理的方法，Puppet 的参数处理机制，我们会在后面的文章中讨论：

class Puppet::Application::MyApp < Puppet::Application

  option("--from [NAME]") do |name|
    options[:from] = name
  end

  def main
    from = options[:from] || "my customize application subcommmand"
    puts "Greet from #{from}."
  end

end

打包并安装 Gem。

$ gem build my_app.gemspec
$ gem install my_app-0.1.0.gem

这时候就可以尝试运行我们自定义的应用命令了！

$ puppet my_app --from me
Greet from me.

$ puppet my_app
Greet from my customize application subcommmand.

这里只是演示了通过编写 Ruby Gem 来扩展 Puppet 应用子命令，之所以这样做，很大程度上是为了代码分发。实际上，我们还可以利用 Puppet 的插件同步（PluginSync）机制来实现类似的扩展。

Puppet 对扩展友好，并预留了各种扩展方式。读者完全可以发挥想象力，利用 Ruby 的动态特性，通过继承等手段（合理使用猴子补丁也无妨），根据需要定制 Puppet！

`plugin_hook` 模式

读者也许会注意到 plugin_hook 这个方法，这个方法用到了许多 Ruby 黑魔法实现了一个非常灵活的效果。例如，考虑代码：

文件：lib/puppet/application.rb，有意重新编排了格式

exit_on_fail("initialize") do
  plugin_hook('preinit') do
    preinit
  end
end

它完成了这样几个步骤：

plugin_hook 会首先向 Puppet 所有已载入的插件广播，即，调用他们的 before_application_preinit 方法。
然后执行传递给它的 preinit 方法，并记录该方法的返回值。
此后，再调用所有插件的 after_application_preinit 方法。
最后，返回刚才调用的 preinit 方法的返回值。

对于有元编程经验的程序员来说，理解 plugin_hook 方法的实现并不构成问题，它的实现代码如下：

def plugin_hook(step,&block)
  Puppet::Plugins.send("before_application_#{step}",:application_object => self)
  x = yield
  Puppet::Plugins.send("after_application_#{step}",:application_object => self, :return_value => x)
  x
end
private :plugin_hook

需要说明的是，这个设计最初是为扩展 Puppet 而预留的，但实际上它并没有多大的用处。首先，Puppet 会在几个目录中搜索 plugin_init.rb 文件，但初始搜索路径只有 $LOAD_PATH ，这是非常有限的。其次，这个功能已经在 4.X 系统中被去掉了。

结语

在这篇文章中，我们讨论了 Puppet 的启动过程，了解了 Puppet 中四类命令的查找与加载。请读者仔细理解其中的运行机制，我们将在后面的章节中，继续介绍 Agent 和 Master 的启动过程。

关于 OpenSSL 的 verify_callback 的疑惑

deathking — Thu, 30 Jul 2015 11:30:06 +0800

verify_callback 指定的回调函数，是用于验证的，还是验证后处理的？下面的文档抄录自 OpenSSL 文档 set peer certificate verification parameters ，Ruby Doc 关于这个问题描述地不是很详细。

The actual verification procedure is performed either using the built-in verification procedure or using another application provided verification function set with SSL_CTX_set_cert_verify_callback. ... The verify_callback function is used to control the behaviour when the SSL_VERIFY_PEER flag is set.

如果是验证后处理的，但在读 Puppet 源码的时候，发现即使 preverify_ok 为 true 也要再检查 peer。preverify_ok = valid_peer? 不太明白为什么要这样做。
如果是这个回调函数负责 peer 的验证，那么这个 preverify_ok 的值是怎么确定的？

def call(preverify_ok, store_context)
  # We must make a copy since the scope of the store_context will be lost
  # across invocations of this method.
  if preverify_ok
    current_cert = store_context.current_cert
    @peer_certs << Puppet::SSL::Certificate.from_instance(current_cert)

    # If we've copied all of the certs in the chain out of the SSL library
    if @peer_certs.length == store_context.chain.length
      # (#20027) The peer cert must be issued by a specific authority
      preverify_ok = valid_peer?
    end
  else
    error = store_context.error || 0
    error_string = store_context.error_string || "OpenSSL error #{error}"

    case error
    when OpenSSL::X509::V_ERR_CRL_NOT_YET_VALID
      # current_crl can be nil
      # https://github.com/ruby/ruby/blob/ruby_1_9_3/ext/openssl/ossl_x509store.c#L501-L510
      crl = store_context.current_crl
      if crl
        if crl.last_update && crl.last_update < Time.now + FIVE_MINUTES_AS_SECONDS
          Puppet.debug("Ignoring CRL not yet valid, current time #{Time.now.utc}, CRL last updated #{crl.last_update.utc}")
          preverify_ok = true
        else
          @verify_errors << "#{error_string} for #{crl.issuer}"
        end
      else
        @verify_errors << error_string
      end
    else
      current_cert = store_context.current_cert
      @verify_errors << "#{error_string} for #{current_cert.subject}"
    end
  end
  preverify_ok
rescue => ex
  @verify_errors << ex.message
  false
end

关于 Bootstrap nav-pill active 属性问题

deathking — Thu, 30 Oct 2014 14:40:54 +0800

现在我有这样的胶囊式导航栏，我是用 active_link_to 来判断按钮与当前页面的关系，并生成相应的 active 属性。

我想说的是，每次生成这个 nav，就要调用 7 次 active_link_to 这个 helper，感觉很费时，而且也很不必要。

有什么跟好的解决办法吗？（先不考虑 DRY 的问题）

<ul class="nav nav-pills">
  <%= active_link_to fa_icon('home', text: ' 课程主页', class: 'fa-fw fa-lg'), home_course_path(@course), wrap_tag: :li %>
  <%= active_link_to fa_icon('files-o', text: ' 课件资料', class: 'fa-fw fa-lg'), docs_course_path(@course), wrap_tag: :li  %>
  <%= active_link_to fa_icon('comments-o', text: ' 讨论专区', class: 'fa-fw fa-lg'), forum_course_path(@course), wrap_tag: :li  %>
  <%= active_link_to fa_icon('edit', text: ' 课程作业', class: 'fa-fw fa-lg'), assmt_course_path(@course), wrap_tag: :li  %>
  <%= active_link_to fa_icon('book', text: ' 课程维基', class: 'fa-fw fa-lg'), wiki_course_path(@course), wrap_tag: :li  %>
  <%= active_link_to fa_icon('group', text: ' 成员', class: 'fa-fw fa-lg'), members_course_path(@course), wrap_tag: :li  %>
  <%= active_link_to fa_icon('gears', text: ' 课程管理', class: 'fa-fw fa-lg'), admin_course_path(@course), wrap_tag: :li  %>
</ul>

[已解决] 提交使用 js 动态创建的表单，如何添加 CSRF_TOKEN？

deathking — Thu, 28 Aug 2014 23:36:24 +0800

因为某些原因，我需要用 js 创建一个 form，然后自行提交，但是遇到InvalidAuthenticityToken。

不是 Ajax 提交。关键代码如下，页面里面有个 button，然后点击时执行testPost()。

// from https://stackoverflow.com/questions/133925/javascript-post-request-like-a-form-submit
function post(path, params, method) {
    method = method || "post"; // Set method to post by default if not specified.

    // The rest of this code assumes you are not using a library.
    // It can be made less wordy if you use one.
    var form = document.createElement("form");
    form.setAttribute("method", method);
    form.setAttribute("action", path);

    for(var key in params) {
        if(params.hasOwnProperty(key)) {
            var hiddenField = document.createElement("input");
            hiddenField.setAttribute("type", "hidden");
            hiddenField.setAttribute("name", key);
            hiddenField.setAttribute("value", params[key]);

            form.appendChild(hiddenField);
         }
    }

    document.body.appendChild(form);
    form.submit();
}

function testPost() {
    post("/books", {foo: "bar"});
}

解决方案：

在 post 中加入authenticity_token项，其值是 head 中的元数据 csrf-token 的值（由 Rails 生成）。

var token = $('meta[name="csrf-token"]').attr('content');

将特定网页结点与对应 CSS 一同抓取

deathking — Sat, 08 Feb 2014 10:31:16 +0800

现在有个比较特别地需求，假设我要抓取网页中的一个特定结点，比如id="content"的div吧，我想连同它对应的 CSS 规则也一同抓取下来。现在的想法是，先用nokogiri抓取 DOM Tree，然后用css_parser读里面的 CSS 文件，自己再做一个 match。但这样做开销似乎太大了，所以想通过操作 WebKit 来取出 RenderTree。

有更好地办法么？

Mavericks 下安装 do_postgres 失败

deathking — Wed, 22 Jan 2014 00:36:45 +0800

背景

由于要部署在 Heroku 上，所以必须要用 PostgreSQL。就有了这样的依赖关系：data_mapper -> dm-postgres-adapter -> do_postgres。但是安装do_postgres的时候总提示找不到某些头文件。这下问题就来了，我用两种策略在本机上安装 PostgreSQL：

PostgreSQL.app(PostgreSQL93)

直接安装不行，所以要手动指定include，于是我尝试了：

$ sudo gem install dm-postgres-adapter -- --with-pgsql-server-include=/usr/Applications/Postgres93.app/Contents/MacOS/include
$ sudo gem install dm-postgres-adapter -- --with-pgsql-server-include=/usr/Applications/Postgres93.app/Contents/MacOS/include/postgresql
$ sudo gem install dm-postgres-adapter -- --with-pgsql-server-include=/usr/Applications/Postgres93.app/Contents/MacOS/include/postgresql/server

都得到提示：

checking for main() in -lpq... yes
checking for libpq-fe.h... no

改用`brew install postgres`依旧无果

用brew安装的 PostgreSQL 是9.2.4版的，再次尝试安装 gem，情况貌似有所好转：

checking for main() in -lpq... yes
checking for libpq-fe.h... yes
checking for libpq/libpq-fs.h... yes
checking for postgres.h... yes
checking for mb/pg_wchar.h... no

情况如这位哥们儿所说，mb/pg_wchar.h确实存在，但有 error，但出错的地方不一样。


have_header: checking for mb/pg_wchar.h... -------------------- no

"xcrun clang -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/include/ruby-2.0.0/universal-darwin13 -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/include/ruby-2.0.0/ruby/backward -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/include/ruby-2.0.0 -I. -I/usr/local/Cellar/postgresql/9.2.4/include -I/usr/local/Cellar/postgresql/9.2.4/include/server -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE -D_DARWIN_UNLIMITED_SELECT -D_REENTRANT    -g -Os -pipe -DHAVE_NO_DATETIME_NEWBANG     -c conftest.c"
In file included from conftest.c:3:
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:303:16: warning: type specifier missing, defaults to 'int' [-Wimplicit-int]
typedef bool (*mbcharacter_incrementer) (unsigned char *mbstr, int len);
              ~^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:303:9: warning: type specifier missing, defaults to 'int' [-Wimplicit-int]
typedef bool (*mbcharacter_incrementer) (unsigned char *mbstr, int len);
~~~~~~~ ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:303:14: error: function cannot return function type 'int (unsigned char *, int)'
typedef bool (*mbcharacter_incrementer) (unsigned char *mbstr, int len);
             ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:328:2: error: unknown type name 'uint32'
        uint32          utf;                    /* UTF-8 */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:329:2: error: unknown type name 'uint32'
        uint32          code;                   /* local code */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:337:2: error: unknown type name 'uint32'
        uint32          code;                   /* local code */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:338:2: error: unknown type name 'uint32'
        uint32          utf;                    /* UTF-8 */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:346:2: error: unknown type name 'uint32'
        uint32          utf1;                   /* UTF-8 code 1 */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:347:2: error: unknown type name 'uint32'
        uint32          utf2;                   /* UTF-8 code 2 */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:348:2: error: unknown type name 'uint32'
        uint32          code;                   /* local code */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:356:2: error: unknown type name 'uint32'
        uint32          code;                   /* local code */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:357:2: error: unknown type name 'uint32'
        uint32          utf1;                   /* UTF-8 code 1 */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:358:2: error: unknown type name 'uint32'
        uint32          utf2;                   /* UTF-8 code 2 */
        ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:416:8: error: unknown type name 'mbcharacter_incrementer'
extern mbcharacter_incrementer pg_database_encoding_character_incrementer(void);
       ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:456:27: error: function cannot return function type 'bool' (aka 'int (int *)')
extern bool pg_verifymbstr(const char *mbstr, int len, bool noError);
                          ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:457:28: error: function cannot return function type 'bool' (aka 'int (int *)')
extern bool pg_verify_mbstr(int encoding, const char *mbstr, int len,
                           ^
/usr/local/Cellar/postgresql/9.2.4/include/server/mb/pg_wchar.h:485:28: error: function cannot return function type 'bool' (aka 'int (int *)')
extern bool pg_utf8_islegal(const unsigned char *source, int length);
                           ^
2 warnings and 15 errors generated.
checked program was:
/* begin */
1: #include "ruby.h"
2: 
3: #include <mb/pg_wchar.h>
/* end */

--------------------

不得不说，被彻底恶心到了。

有人清楚 RHG (Ruby Hacking Guide) 中文化的情况么？

deathking — Thu, 18 Apr 2013 22:13:51 +0800

这是一本很好的书，貌似翻译项目停滞了很久，这么多年都没看到更新了。有谁了解具体的情况么？

http://axgle.github.io/rhg/

[更新] 探寻 Ruby 原力——SICP 公开课中英双语字幕

deathking — Thu, 04 Apr 2013 10:43:41 +0800

[SICP] 计算机程序的构造和解释

探寻 Ruby 的祖宗之一——Lisp 的魔力

不知道怎么在帖内嵌入 Flash 视频，直接放 Youku 专辑地址吧： http://www.youku.com/playlist_show/id_18958522.html

拖了一年有余了，终于更新了，真是泪流满面。

Lec2a：高阶过程
Lec2b：复合数据

高阶过程介绍了如何抽象地思考，复合数据介绍了如何对数据建立抽象屏障。

想了很久，要不要把这个东西在这里放出来。一来是 SICP 用的是 Scheme，不是 Ruby，所以放在 Ruby-China 似乎不是很好。但转念一想，Ruby 确实从 Lisp 里面“借”来很多东西，很多是 Ruby 对 Lisp 思想的延续。我当初接触 Ruby 时，花了很久的时间才体会到了 Ruby 的思想，然而，当我后面看到 SICP 这本书，接触到 Lisp 这个老前辈时，发现他留下了 Ruby 太多太多的珍宝：

代码和数据之间没有不可逾越的鸿沟
- 符号（Symbol）
高阶函数
- Ruby 里面的块、lambda 方法
- Lisp 里面的 lambda 过程
通过提供一致的接口实现的数据抽象
- Ruby 的鸭子类型
可变参数
- Lisp 里的点
- Ruby 里面的星
元语言抽象
- 用 Lisp 构建 Lisp 或其它语言
- Ruby 是一门很好的 DSL 语言

例如，作为 OOP 语言的 Ruby 所强调的“模板方法”这种设计模式，很早就体现在 Lisp 所强调的“提取公共模式”的抽象方法上了。所以，我决定还是放出这个系列视频，让大家同我们一起去探寻其中蕴涵的思想。

本视频由
哈尔滨工业大学 IBM 技术中心 FoOTOo 实验室负责统筹翻译
哈尔滨工业大学清影 PT 压制小组进行压制和后期制作。

由于我们都是高校学生，所以只能利用课余时间进行翻译工作。在加上校正、打轴、后期等字幕制作工作较为繁琐，所以进度很慢。整个翻译项目托管在：https://github.com/FoOTOo/Learning-SICP。欢迎大家给我们提出意见和简易，并对翻译错误或者可以提高的地方进行指正！

DeathKing

将一个 Ruby 脚本置为服务，调用该脚本则调用该服务

deathking — Sat, 26 Jan 2013 01:21:54 +0800

先说一下需求吧。假设我有一个脚本叫poj.rb吧，他完成下面的功能：

poj.rb get 1001 ：从我设定的网站获取id为1001的网页；
poj.rb submit 1001.c ：将1001.c文件提交；

我现在想说的是，这个脚本初始化需要消耗一定的资源，而调用的频率也非常高，因此，我希望初始化一次而响应参数多次。也许有人说你可以这样实现：

# 初始化
init()

# 获得输入
while str = gets
  # 处理str
end

但实际的需求不允许我这样，我想要实现类似于git的效果，也就是在终端中这样：

$ git add README.md
$ git commit -m 'first commit'
$ 
$ poj.rb get 1001
$ poj.rb submit 1001.pas

因此，我想让hoj.rb在第一次运行后就成为daemon，以后在shell调用poj.rb时，不会新建一个实例，而是把消息发送给之前创建好的daemon。

我目前能想到的方法是用Daemons这个 gem，但是使用Daemons.daemonize方法似乎不起作用。所以想问下各位：

daemons这个库应该如何实现这个功能；
daemons如果不能实现这个功能，那么ruby能么？要如何实现呢？

如何 alias 一个类方法或者模块方法呢？

deathking — Tue, 03 Jul 2012 15:51:59 +0800

module Foo

  def self.bar
    "bar"
  end

  alias foobar bar  #=> undefined bar method
  alias self.foobar self.bar #=> Syntax Error

end

可以用 alias 来操作模块方法么？

deathking (DeathKing)

Puppet 扩展研究 - 使用 Log.io 作为即时日志输出

绪言

启：突破口

承：Puppet 日志系统原理

转：怎么使用呢？

总结

Puppet Hacking Guide —— Puppet 的启动：守护进程

Acknowledgment

Daemon: 可后台化进程

Daemon 的层次观

注意

Daemon 的数据结构及初始化

daemonize：进程后台化

start：守护进程的运转

run_event_loop：主运行循环

stop：守护进程的终止

set_signal_traps：设置信号处理

Puppet Hacking Guide —— Puppet 的启动：子命令

Acknowledgment

Puppet 的启动：子命令

Puppet 的启动方式

子命令分类

子命令的查找与加载

空命令与未知命令

空对象模式

空对象模式的优势与劣势

后话

外部子命令

查找规则

执行

小实验：用 Puppet 执行外部命令

应用子命令

查找规则

加载

执行

小实验：以应用子命令的方式扩展 Puppet

plugin_hook 模式

结语

关于 OpenSSL 的 verify_callback 的疑惑

关于 Bootstrap nav-pill active 属性问题

[已解决] 提交使用 js 动态创建的表单，如何添加 CSRF_TOKEN？

解决方案：

将特定网页结点与对应 CSS 一同抓取

Mavericks 下安装 do_postgres 失败

背景

PostgreSQL.app(PostgreSQL93)

改用brew install postgres依旧无果

有人清楚 RHG (Ruby Hacking Guide) 中文化的情况么？

[更新] 探寻 Ruby 原力——SICP 公开课中英双语字幕

[SICP] 计算机程序的构造和解释

探寻 Ruby 的祖宗之一——Lisp 的魔力

将一个 Ruby 脚本置为服务，调用该脚本则调用该服务

如何 alias 一个类方法或者模块方法呢？

`plugin_hook` 模式

改用`brew install postgres`依旧无果