klarlack 0.0.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Max Schöfmann
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,43 @@
+= klarlack
+
+Klarlack is a ruby client library for the varnish administration interface.
+
+See also: http://www.varnish-cache.org
+
+Please note: You need at least version 2.0.3 of varnish for purging to work.
+
+=== Installation
+
+  sudo gem install schoefmax-klarlack --source=http://gems.github.com
+
+=== Example
+
+Lets purge all blog posts from the cache...
+
+  require 'rubygems'
+  require 'klarlack'
+
+  varnish = Varnish::Client.new '127.0.0.1:6082'
+  # the regexp is not a ruby regexp, just a plain string varnishd understands
+  varnish.purge :url, "^/posts/.*"
+
+In a Rails app, you might want to use use this in a cache sweeper.
+
+=== Specs
+
+Start up a local varnishd with <tt>-T 127.0.0.1:6082</tt>. Then run
+
+  spec spec
+
+=== TODO
+
+* Support authentication when varnishd is started with <tt>-S</tt>
+* Make parameter manipulation/display more friendly
+
+=== WTF?
+
+http://dict.leo.org/?search=klarlack
+
+=== Copyright
+
+Copyright (c) 2009 Max Schöfmann. Distributed under the MIT-License

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "klarlack"
+    gem.summary = %Q{ruby client for varnishd's admin interface}
+    gem.email = "max@pragmatic-it.de"
+    gem.homepage = "http://github.com/schoefmax/klarlack"
+    gem.authors = ["Max Schöfmann"]
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "klarlack #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 0
+:patch: 2

data/lib/klarlack.rb

@@ -0,0 +1,8 @@
+require 'socket'
+require 'varnish/socket_factory'
+require 'varnish/client'
+
+module Varnish
+  class Error < StandardError; end
+  VERSION = '0.0.1'
+end

data/lib/varnish/client.rb

@@ -0,0 +1,258 @@
+module Varnish
+  class Client
+    # Default management port of varnishd
+    DEFAULT_PORT = 6082
+
+    # We assume varnishd on localhost
+    DEFAULT_HOST = 'localhost'
+
+    DEFAULT_OPTS = {
+      :keep_alive => false,
+      :timeout    => 1
+    }
+
+    # timeout in seconds when connecting to varnishd. Default is 1
+    attr_accessor :timeout
+
+    # set to true, to keep the connection alive. Default is false
+    attr_accessor :keep_alive
+
+    # hostname or IP-address of varnishd. Default is "localhost"
+    attr_accessor :host
+
+    # port number of varnishd. Default is 6082
+    attr_accessor :port
+
+    # Examples:
+    # 
+    #   Varnish::Client.new "127.0.0.1"
+    #   Varnish::Client.new "mydomain.com:6082"
+    #   Varnish::Client.new :timeout => 5
+    #   Varnish::Client.new "10.0.0.3:6060", :timeout => nil, :keep_alive => true
+    #
+    # === Configuration options
+    #
+    # +timeout+:: if specified (seconds), calls to varnish
+    #             will be wrapped in a timeout, default is 1 second.
+    #             Disable with <tt>:timeout => nil</tt>
+    # +keep_alive+:: if true, the connection is kept alive by sending
+    #                ping commands to varnishd every few seconds
+    def initialize(*args)
+      opts = {}
+
+      case args.length
+      when 0
+        self.server = DEFAULT_HOST
+      when 1
+        arg = args[0]
+        case arg
+        when String
+          self.server = arg
+        when Hash
+          self.server = DEFAULT_HOST
+          opts = arg
+        end
+      when 2
+        self.server = args[0]
+        opts = args[1]
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.length} for 2)"
+      end
+
+      opts = DEFAULT_OPTS.merge(opts)
+      @timeout     = opts[:timeout]
+      @keep_alive  = opts[:keep_alive]
+
+      @mutex = Mutex.new
+    end
+
+    # Set the varnishd management host and port.
+    # Expects a string as "hostname" or "hostname:port"
+    def server=(server)
+      @host, @port = server.split(':')
+      @port = (@port || DEFAULT_PORT).to_i
+      server
+    end
+
+    # Returns the varnishd management host and port as "hostname:port"
+    def server
+      "#{@host}:#{@port}"
+    end
+
+    # Manipulate the VCL configuration
+    # 
+    #  .vcl :load, <configname>, <filename>
+    #  .vcl :inline, <configname>, <quoted_VCLstring>
+    #  .vcl :use, <configname>
+    #  .vcl :discard, <configname>
+    #  .vcl :list
+    #  .vcl :show, <configname>
+    #
+    # Returns an array of VCL configurations for :list, and the servers
+    # response as string otherwise
+    #
+    # Ex.:
+    #   v = Varnish::Client.new
+    #   v.vcl :list
+    #   #=> [["active", 0, "boot"]]
+    #   
+    #   v.vcl :load, "newconf", "/etc/varnish/myconf.vcl"
+    #
+    # 
+    def vcl(op, *params)
+      response = cmd("vcl.#{op}", *params)
+      case op
+      when :list
+        response.split("\n").map do |line|
+          a = line.split(/\s+/, 3)
+          [a[0], a[1].to_i, a[2]]
+        end
+      else
+        response
+      end
+    end
+
+    # Purge objects from the cache or show the purge queue.
+    #
+    #  .purge :url, <regexp>
+    #  .purge :hash, <regexp>
+    #  .purge :list
+    #  .purge <costum-field> <args>
+    #
+    # +op+:: :url, :hash, :list or a custom field
+    # +regexp+:: a string containing a varnish compatible regexp
+    #
+    # Returns true for purging, returns an array containing the purge queue
+    # for :list
+    #
+    # Ex.:
+    #   v = Varnish::Client.new
+    #   v.purge :url, '.*'
+    #
+    #   v.purge :list
+    #   #=> [[1, "req.url ~ .*"]]
+    #
+    def purge(op, *regexp_or_args)
+      c = [:url, :hash, :list].include?(op) ? "purge.#{op}" : "purge #{op}"
+      response = cmd(c, *regexp_or_args)
+      case op
+      when :list
+        response.split("\n").map do |line|
+          a = line.split("\t")
+          [a[0].to_i, a[1]]
+        end
+      else
+        bool response
+      end
+    end
+
+    # Ping the server to keep the connection alive
+    def ping(timestamp = nil)
+      cmd("ping", timestamp)
+    end
+
+    # Returns a hash of status information
+    #
+    # Ex.:
+    #   v = Varnish::Client.new
+    #   v.stats
+    #   => {"Total header bytes"=>0, "Cache misses"=>0 ...}
+    def stats
+      result = cmd("stats")
+      Hash[*result.split("\n").map { |line|
+          stat = line.strip!.split(/\s+/, 2)
+          [stat[1], stat[0].to_i]
+        }.flatten
+      ]
+    end
+
+    # Set and show parameters
+    #
+    #  .param :show, [-l], [<param>]
+    #  .param :set, <param>, <value>
+    def param(op, *args)
+      cmd("param.#{op}", *args)
+    end
+
+    # Returns the status string from varnish.
+    # See also #running? and #stopped?
+    def status
+      cmd("status")
+    end
+
+    def start
+      bool cmd("start")
+    end
+
+    def stop
+      bool cmd("stop")
+    end
+
+    def running?
+      bool status =~ /running/
+    end
+
+    def stopped?
+      bool status =~ /stopped/
+    end
+
+    # close the connection to varnishd.
+    # Note that the connection will automatically be re-established
+    # when another command is issued.
+    def disconnect
+      if connected?
+        @conn.write "quit\n"
+        @conn.gets
+        @conn.close unless @conn.closed?
+      end
+    end
+    
+    def connected?
+      bool @conn && !@conn.closed?
+    end
+
+    private
+
+    # Sends a command to varnishd.
+    # Raises an Varnish::Error when a non-200 status is returned
+    # Returns the response text
+    def cmd(name, *params)
+      @mutex.synchronize do
+        connect unless connected?
+        @conn.write "#{name} #{params.join(' ')}\n"
+        status, length = @conn.gets.split # <status> <content_length>\n
+        content = @conn.read(length.to_i + 1) # +1 = \n
+        content.chomp!
+        raise Error, "Command #{name} returned with status #{status}: #{content}" if status.to_i != 200
+        content
+      end
+    end
+
+    def connect
+      @conn = SocketFactory.tcp_socket(@host, @port, @timeout)
+
+      # If keep alive, we ping the server every few seconds.
+      if @keep_alive
+        varnish = self
+        Thread.new do
+          while(true) do
+            if varnish.connected?
+              varnish.ping
+              sleep 5
+            else
+              break
+            end
+          end
+        end
+      end
+
+      @conn
+    end
+
+    # converts +value+ into a boolean
+    def bool(value)
+      !!value
+    end
+    
+  end
+end

data/lib/varnish/socket_factory.rb

@@ -0,0 +1,57 @@
+module Varnish
+  # Wrapper around Ruby's Socket.
+  #
+  # Uses Mike Perhams superior (in both reliability and
+  # performance) connection technique with proper timeouts:
+  # See: http://github.com/mperham/memcache-client
+  class SocketFactory
+
+    begin
+      # Try to use the SystemTimer gem instead of Ruby's timeout library
+      # when running on something that looks like Ruby 1.8.x. See:
+      # http://ph7spot.com/articles/system_timer
+      # We don't want to bother trying to load SystemTimer on jruby and
+      # ruby 1.9+.
+      if !defined?(RUBY_ENGINE)
+        require 'system_timer'
+        Timer = SystemTimer
+      else
+        require 'timeout'
+        Timer = Timeout
+      end
+    rescue LoadError => e
+      $stderr.puts "[klarlack] Could not load SystemTimer gem, falling back to Ruby's slower/unsafe timeout library: #{e.message}"
+      require 'timeout'
+      Timer = Timeout
+    end
+
+    def self.tcp_socket(host, port, timeout = nil)
+      addr = Socket.getaddrinfo(host, nil)
+      sock = Socket.new(Socket.const_get(addr[0][0]), Socket::SOCK_STREAM, 0)
+
+      if timeout
+        secs = Integer(timeout)
+        usecs = Integer((timeout - secs) * 1_000_000)
+        optval = [secs, usecs].pack("l_2")
+        sock.setsockopt Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, optval
+        sock.setsockopt Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, optval
+
+        # Socket timeouts don't work for more complex IO operations
+        # like gets which lay on top of read. We need to fall back to
+        # the standard Timeout mechanism.
+        sock.instance_eval <<-EOR
+          alias :blocking_gets :gets
+          def gets
+            Timer.timeout(#{timeout}) do
+              self.blocking_gets
+            end
+          end
+        EOR
+      end
+      sock.connect(Socket.pack_sockaddr_in(port, addr[0][3]))
+      sock.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+      sock
+    end
+
+  end
+end

data/spec/klarlack_spec.rb

@@ -0,0 +1,154 @@
+require 'spec/spec_helper'
+
+describe Varnish::Client do
+  
+  before(:each) do
+    @varnish = Varnish::Client.new "127.0.0.1:6082"
+  end
+
+  describe '(connection handling)' do
+
+    it 'should not be connected on object instantiation' do
+      @varnish.connected?.should be_false
+    end
+
+    it 'should not raise an error when trying to disconnect a non-connected client' do
+      lambda { @varnish.disconnect }.should_not raise_error
+    end
+
+    it 'should automatically connect when a command is issued' do
+      @varnish.ping
+      @varnish.connected?.should be_true
+    end
+
+    it 'should use timeouts when sending commands' do
+      Varnish::SocketFactory::Timer.should_receive(:timeout).and_return("200 0")
+      @varnish.timeout = 10
+      @varnish.ping
+    end
+
+    it 'should be possible to disable timeouts' do
+      Varnish::SocketFactory::Timer.should_not_receive(:timeout)
+      @varnish.timeout = nil
+      @varnish.ping
+    end
+
+    it '#disconnect should close the connection' do
+      @varnish.ping
+      @varnish.connected?.should be_true
+      @varnish.disconnect
+      @varnish.connected?.should be_false
+    end
+
+    it 'given keep_alive is set, the connection should be kept alive with pings' do
+      @varnish.keep_alive = true
+      @varnish.should_receive :ping
+      @varnish.send :connect
+    end
+
+    it 'given keep_alive is not set, no pings should be sent to varnishd' do
+      @varnish.keep_alive = false
+      @varnish.should_not_receive :ping
+      @varnish.send :connect
+    end
+
+    it '#server should return the host and port for the connection' do
+      @varnish.host = "foohost"
+      @varnish.port = 1234
+      @varnish.server.should == "foohost:1234"
+    end
+
+    it '#server= should set the host and port for the connection' do
+      @varnish.server = "blahost:9876"
+      @varnish.host.should == "blahost"
+      @varnish.port.should == 9876
+    end
+
+  end
+
+  describe '(commands)' do
+
+    before(:each) do
+      ensure_started
+    end
+
+    # ... the specs for #param, #purge and #vcl could be better ...
+
+    it '#param should send the param command to varnishd' do
+      @varnish.param(:show).should_not be_empty
+    end
+
+    it '#purge should allow purging by url, hash and custom fields' do
+      @varnish.purge(:url, '^/articles/.*').should be_true
+      @varnish.purge(:hash, 12345).should be_true
+      @varnish.purge("req.http.host", "~", "www.example.com").should be_true
+    end
+
+    it '#purge with :list should return an array with queued purges' do
+      @varnish.purge(:url, '^/posts/.*')
+      list = @varnish.purge(:list)
+      list.last[0].should be_kind_of(Integer)
+      list.last[1].should == "req.url ~ ^/posts/.*"
+    end
+
+    it '#vcl with :list should return an array of VCL configurations' do
+      list = @varnish.vcl(:list)
+      list.should_not be_empty
+      list.should be_kind_of(Array)
+      list.first[0].should be_kind_of(String)
+      list.first[1].should be_kind_of(Integer)
+      list.first[2].should be_kind_of(String)
+    end
+
+    it '#ping should send a ping to the server and return a string containing the response' do
+      @varnish.ping.should =~ /^PONG \d+/
+    end
+
+
+    it '#status should return a string explaining the daemons status' do
+      @varnish.status.should =~ /running|stopped|stopping|starting/
+    end
+
+    it "#stats should return a hash containing status information" do
+      stats = @varnish.stats
+      stats.should_not be_empty
+      stats.values.each {|v| v.should be_kind_of(Integer) }
+      stats.keys.each {|k| k.should_not be_empty }
+    end
+
+  end
+  
+  describe '(daemon lifecycle)' do
+    
+    it '#start, #stop, #running?, #stopped? should bahave as advertised' do
+      ensure_stopped # issues #stop
+      @varnish.stopped?.should be_true
+      @varnish.running?.should be_false
+      ensure_started # issues #start
+      @varnish.stopped?.should be_false
+      @varnish.running?.should be_true
+    end
+    
+    it 'starting an already started daemon should raise an error' do
+      ensure_started
+      lambda { @varnish.start }.should raise_error(Varnish::Error)
+    end
+    
+    it 'stopping an already stopped daemon should raise an error' do
+      ensure_stopped
+      lambda { @varnish.stop }.should raise_error(Varnish::Error)
+    end
+    
+  end
+  
+  def ensure_started
+    @varnish.start if @varnish.stopped?
+    while(!@varnish.running?) do sleep 0.1 end
+  end
+  
+  def ensure_stopped
+    @varnish.stop if @varnish.running?
+    while(!@varnish.stopped?) do sleep 0.1 end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'klarlack'

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: klarlack
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- "Max Sch\xC3\xB6fmann"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-24 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: 
+email: max@pragmatic-it.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- lib/klarlack.rb
+- lib/varnish/client.rb
+- lib/varnish/socket_factory.rb
+- spec/klarlack_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/schoefmax/klarlack
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: ruby client for varnishd's admin interface
+test_files: 
+- spec/klarlack_spec.rb
+- spec/spec_helper.rb