url_tracker 1.0 → 1.1

data/lib/url_tracker/client.rb

@@ -0,0 +1,109 @@
+module UrlTracker
+
+  # Class who deals with requesting information to the server, such as
+  # track a new URL, list all currently tracked links, stop tracking something, etc.
+  class Client
+    include SocketCommunication
+
+    require 'optparse'
+    require 'ostruct'
+
+    def initialize(socket_file = '/tmp/_ut.sock')
+      connect(socket_file)
+    rescue Errno::ENOENT
+      STDERR.puts 'Connection error. Is the server running?'
+      exit(1)
+    end
+
+    # Sends a message to the server asking to track a new URL. Format
+    # of the message:
+    #
+    #   "track {{URL}}"
+    def track(url)
+      write("track #{url}")
+      next_message == 'ok'
+    end
+
+    # Asks the server for all the URLs currently being tracked. Expects a
+    # string back, with URLs separated by commas.
+    def list
+      write('list')
+      next_message.split(',')
+    end
+
+    # Tells the server to stop tracking the given URL. Returns true if the
+    # operation was successful
+    def release(url)
+      write("release #{url}")
+      next_message == 'ok'
+    end
+
+    # Tells the server to shutdown
+    def shutdown
+      write('shutdown')
+    end
+
+    # Calls one of the methods above according to the options passed.
+    # Available options:
+    #
+    #   -t, --track URL   #=> Starts tracking URL
+    #   -l, --list        #=> List currently tracked URLs
+    #   -r, --release URL #=> Releases URL, not tracking it any more
+    #
+    # +params+ can also be a hash, in which case it will be considered already parsed.
+    def run(params)
+      options = parse(params)
+
+      output = case options.action
+        when :track   then track(options.url)
+        when :list    then list
+        when :release then release(options.url)
+      end
+    end
+
+
+  private
+
+    def parse(argv)
+      return OpenStruct.new(argv) if argv.kind_of?(Hash)
+
+      options = OpenStruct.new
+      options.action = :nothing
+
+      opts = OptionParser.new do |opts|
+        opts.banner = 'Usage: ut [options]'
+        opts.separator ''
+        opts.separator 'Available options:'
+
+        opts.on('-t', '--track URL', 'Start tracking URL') do |url|
+          options.url    = prepare_url(url)
+          options.action = :track
+        end
+
+        opts.on('-l', '--list', 'List currently tracked URLs') do |list|
+          options.action = :list
+        end
+
+        opts.on('-r', '--release URL', 'Release URL, not tracking it any more') do |url|
+          options.url    = url
+          options.action = :release
+        end
+
+        opts.on_tail('-h', '--help', 'Show this message') do
+          puts opts
+          exit(0)
+        end
+      end
+
+      opts.parse!(argv)
+
+      options
+    end
+
+    def prepare_url(url)
+      url.tap { url.prepend('http://') unless url.start_with?('http://') }
+    end
+
+  end
+
+end

data/lib/url_tracker/page.rb

@@ -0,0 +1,69 @@
+require 'net/http'
+
+module UrlTracker
+
+  # Class representing a single web page to be tracked. It is capable of fetching
+  # the page's content and verifying if it was changed since last time it was fetched
+  class Page
+    attr_reader :uri
+
+    # Creates a new instance of UrlTracker::Page. The first argument is the URI that
+    # corresponds to the page and will be lazily fetched. The second parameter 
+    # is an object that is responsible for fetching the page itself. It mus respond
+    # to the +get+ method with the given +uri+ parameter and return a string
+    # with the page contents; this parameter defaults to +Net::HTTP+, so you should
+    # by default pass +uri+ as an instance of +URI::Generic+
+    def initialize(uri, page_fetcher = Net::HTTP)
+      @uri          = uri.dup
+      @page_fetcher = page_fetcher
+    end
+
+    # Returns a string containing the page content. If not yet fetched, this method
+    # will fetch the page for you.
+    def content
+      @content ||= fetch
+    end
+
+    # This method returns a string containing the page content, but always fetches
+    # the page again
+    def content!
+      @content = fetch
+    end
+
+    # Verifies if a page has changed since last the last time it was fetched
+    def changed?
+      if @content # we have a cached copy
+        old_content = @content
+        @content = fetch
+        @content != old_content
+      else
+        @content = fetch
+        false
+      end
+    end
+
+    # Two pages are considered the same if they have the same URI. Right, that
+    # might not be true if the content is different (which shouldn't if you are
+    # building a RESTful service), but we will just ignore that and pretend we
+    # we live in a better world.
+    def eql?(other)
+      @uri.eql?(other.uri)
+    end
+
+    def ==(other)
+      @uri == other.uri
+    end
+
+    def hash
+      @uri.hash
+    end
+
+  private
+
+    def fetch
+      @page_fetcher.get(@uri)
+    end
+
+  end
+
+end

data/lib/url_tracker/periodic.rb

@@ -0,0 +1,129 @@
+module UrlTracker
+
+  require 'eventmachine'
+
+  # Small class wrapping EventMachine calls to programatically
+  # execute code blocks.
+  class Periodic
+
+    # maybe consider :day in the future
+    TIME_UNITS = {
+      minute: 60,
+      minutes: 60,
+      hour:   60*60,
+      hours:   60*60
+    }
+
+    # Creates a new instance of UrlTracker::Periodic and starts the event loop.
+    def initialize
+      @named_tasks = {}
+      start_event_loop
+    end
+
+    # Register a new task to be executed in a specified amount of time.
+    # Examples:
+    #
+    #   p = UrlTracker::Periodic.new
+    #   p.every(:minute)    { do_something }    #=> executed every minute
+    #   p.every(2, :minutes) { do_something }   #=> executed every 2 minutes
+    #   p.every(4, :hours)   { do_something }   #=> executed every 4 hours
+    def every(*args, &block)
+      time = 1
+
+      case args.first
+        when Integer then time  = args[0]*seconds_for(args[1])
+        when Symbol  then time *= seconds_for(args[0])
+        else raise "Invalid period #{args[0].inspect}"
+      end
+
+      task = { every: time, task: block }
+      task.merge!(name: @name) if named_task?
+
+      schedule_task(task)
+      @name = nil
+
+      time
+    end
+
+    # Returns named tasks registered.
+    # Example
+    #
+    #   p = UrlTracker::Periodic.new
+    #   p.task(:foo).every(:minute)     { do_something}
+    #   p.task(:bar).every(2, :minute)  { do_other_thing }
+    #   p.named_tasks #=> [:foo, :bar]
+    def named_tasks
+      task_names
+    end
+
+    # Removes a task named +name+, so that it will no longer run
+    def remove_task(name)
+      raise "Unregistered task #{name.inspect}" unless @named_tasks.include?(name)
+
+      unschedule_task(name)
+    end
+
+    # Restarts the event loop
+    def restart
+      stop if running?
+      start_event_loop
+    end
+
+    # Checks if the tasks are running
+    def running?
+      @event_thread.alive?
+    end
+
+    # Stop all scheduled tasks
+    def stop
+      @event_thread.terminate
+      @event_thread.join
+    end
+
+    # Used for creating named tasks or, in other words, tasks that can be removed
+    # later using #remove
+    def task(name)
+      @name = name.to_s
+      self
+    end
+
+  private
+
+    def named_task?
+      !@name.nil?
+    end
+
+    def seconds_for(time_unit)
+      raise "Unkown time unit #{time_unit.inspect}" unless TIME_UNITS.include?(time_unit)
+      TIME_UNITS[time_unit]
+    end
+
+    # +task+ is expected to be in the format:
+    #
+    #   { every: 60, task: #<Proc:0x...> }
+    #
+    # for a task to be run every minute, for example.
+    def schedule_task(t)
+      periodic_timer = EM.add_periodic_timer(t[:every], &t[:task])
+      @named_tasks[@name] = periodic_timer if named_task?
+    end
+
+    def start_event_loop
+      # start the event loop in a separate thread
+      @event_thread = Thread.new { EM.run }
+
+      # Wait for the reactor to be ready
+      while !@event_thread.stop?; end
+    end
+
+    def task_names
+      @named_tasks.keys
+    end
+
+    def unschedule_task(name)
+      EM.cancel_timer(@named_tasks.delete(name))
+    end
+
+  end
+
+end

data/lib/url_tracker/server.rb

@@ -0,0 +1,150 @@
+module UrlTracker
+
+  require 'optparse'
+  require 'ostruct'
+  require 'logger'
+  require 'pathname'
+
+  # Class that waits for messages on a given socket and responds back to clients.
+  # It can track URLs, list currently tracked URLs and stop tracking.
+  # The interval between consecutive checks for change in the pages is customizable.
+  class Server
+    include SocketCommunication
+
+    # Initializes a new server which logs its activities using the passed logger object.
+    # Defaults to Ruby's Logger class. Log level defaults to +Logger::INFO+ and you can
+    # override it by setting the URL_TRACKER_DEBUG environment variable
+    def initialize(logger=Logger.new(STDERR))
+      setup_signals
+      @logger = logger
+      @logger.level = level_from_env || Logger::INFO
+    end
+
+    # Main server method. Loops forever, waiting for new connections, and
+    # checking new messages. Takes the appropriate action according to what is
+    # received, such as a new URL to track.
+    def loop_forever
+      running = true
+
+      while wait_for_connection
+        @logger.info("New client connected")
+        command, *arguments = next_message.split
+        @logger.debug "#{command} received"
+        response = case command
+          when /^track$/i    then track(arguments.first)
+          when /^list$/i     then list
+          when /^release$/i  then release(arguments.first)
+        end
+
+        write(response) unless response.nil?
+      end
+    rescue => e
+      @logger.error("An error occurred when waiting for new connections!\n\t#{e.inspect}\n\t#{e.backtrace.join("\n\t")}")
+    end
+
+    # Track an URL
+    def track(uri)
+      @logger.info("Tracking URL #{uri}")
+      UrlTracker.track_uri(uri)
+    end
+
+    # List tracked URLs
+    def list
+      UrlTracker.list_all
+    end
+
+    # Release an URL
+    def release(uri)
+      @logger.info("Releasing URL #{uri}")
+      UrlTracker.release_uri(uri)
+    end
+
+    # Runs the server, according to the argv options passed.
+    # Possible options:
+    #
+    #   -s, --socket [FILE] #=> Uses FILE as socket file for communication
+    #   -f, --fork          #=> Forks and works as a daemon
+    #
+    # +params+ can also be a hash, containing the parsed information to the server.
+    def run(params)
+      @logger.info "UrlTracker #{UrlTracker::VERSION} starting. Log level is #{@logger.level.inspect}."
+
+      options = parse(params)
+      @socket_file = options.socket_file
+      @pid         = nil
+
+      bind(@socket_file)
+
+      @logger.info "Server starting at socket #{Pathname.new(@socket_file).realpath.to_s}"
+
+      if options.fork
+        @pid = fork { loop_forever }
+        @logger.info "Forking to background. Child pid #{@pid}"
+      else
+        loop_forever
+      end
+    end
+
+    # Stops the current server
+    def stop
+      @pid ? Process.kill('TERM', @pid) : close_connection
+    end
+
+  private
+
+    def parse(argv)
+      return OpenStruct.new(argv) if argv.kind_of?(Hash)
+
+      options = OpenStruct.new
+      options.socket_file = '/tmp/_ut.sock'
+      options.fork        = false
+
+      opts = OptionParser.new do |opts|
+        opts.banner = 'Usage: utd [options]'
+        opts.separator ''
+        opts.separator 'Available options:'
+
+        opts.on('-s', '--socket FILE', 'Uses FILE as a socket. Defaults to /tmp/_ut.sock') do |socket_file|
+          options.socket_file = socket_file
+        end
+
+        opts.on('-f', '--fork', 'Forks and works as a daemon') do |f|
+          options.fork = f
+        end
+
+        opts.on_tail('-h', '--help', 'Show this message') do
+          puts opts
+          exit(0)
+        end
+      end
+
+      opts.parse!(argv)
+
+      options
+    end
+
+    def setup_signals
+      ['INT', 'TERM', 'QUIT'].each do |signal|
+        Signal.trap(signal) do
+          stop
+          @logger.info "SIG#{signal} received. Bye."
+          exit(0)
+        end
+      end
+    end
+
+    # Retrieves log level from DEBUG environment variable
+    def level_from_env
+      case ENV['URL_TRACKER_DEBUG']
+        when 'debug'   then Logger::DEBUG
+        when 'error'   then Logger::ERROR
+        when 'fatal'   then Logger::FATAL
+        when 'info'    then Logger::INFO
+        when 'warning' then Logger::WARN
+        else                nil
+      end
+    end
+
+  end
+
+end

data/lib/url_tracker/socket_communication.rb

@@ -0,0 +1,75 @@
+module UrlTracker
+
+  require 'socket'
+
+  # Implements communication via Unix sockets.
+  module SocketCommunication
+    attr_writer :path # path to the socket file
+
+    InvalidSocketError = Class.new(StandardError)
+
+    # Messages received cannot be longer than 1024 bytes
+    MAX_MESSAGE_LENGTH = 1024
+
+    # Max connections to be queued before accept
+    MAX_CONN_QUEUE = 10
+
+    # Connects to the Unix socket. Returns true if the connection was successful.
+    # Otherwise an exception is thrown. This method cannot be called if +bind+ was
+    # already called; neither can you call +bind+ if you call this method.
+    def connect(path)
+      raise_socket_error_if { defined? @socket }
+      @socket = Socket.new(:UNIX, :SOCK_STREAM, 0)
+      @socket.connect addrinfo_for(path)
+      true
+    end
+
+    # Binds the given path, creating a Unix socket. As with connect, you cannot use
+    # this method if already called +connect+ before. After this method is called,
+    # the socket will be waiting for connections.
+    def bind(path)
+      raise_socket_error_if { defined? @socket }
+      @socket_file = path
+      @socket = Socket.new(:UNIX, :SOCK_STREAM, 0)
+      @socket.bind addrinfo_for(@socket_file)
+      @socket.listen(MAX_CONN_QUEUE)
+      true
+    end
+
+    # Waits for a connection in the binded socket
+    def wait_for_connection
+      @current_client = @socket.accept.first
+    end
+
+    # Writes to the socket, returning the number of bytes sent. This method can
+    # only be called before +connect+ or +wait_for_connection+, otherwise you
+    # will get an exception
+    def write(message)
+      socket = (defined? @current_client) ? @current_client : @socket
+      socket.send(message, 0)
+    end
+
+    # Waits for a message. Blocks until it is received.
+    def next_message
+      socket = (defined? @current_client) ? @current_client : @socket
+      socket.recvfrom(MAX_MESSAGE_LENGTH).first
+    end
+
+    def close_connection
+      defined?(@socket) && !@socket.closed? && @socket.close
+      File.unlink(@socket_file) if defined?(@socket_file) && File.exists?(@socket_file)
+    end
+
+  private
+
+    def raise_socket_error_if(&block)
+      raise InvalidSocketError if block.call
+    end
+
+    def addrinfo_for(path)
+      Addrinfo.unix(path)
+    end
+
+  end
+
+end

data/lib/url_tracker/version.rb

@@ -0,0 +1,5 @@
+module UrlTracker
+
+  VERSION = '1.1'
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: url_tracker
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -68,6 +68,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/url_tracker.rb
+- lib/url_tracker/socket_communication.rb
+- lib/url_tracker/server.rb
+- lib/url_tracker/periodic.rb
+- lib/url_tracker/client.rb
+- lib/url_tracker/page.rb
+- lib/url_tracker/version.rb
 - bin/ut
 - bin/utd
 - test/test_server.rb
@@ -91,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1259474569283625211
+      hash: -1434435919243475892
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -100,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1259474569283625211
+      hash: -1434435919243475892
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23