pantry 0.0.0 → 0.1.0

data/lib/pantry/logger.rb

@@ -0,0 +1,78 @@
+module Pantry
+
+  # Access Pantry's logger.
+  def self.logger
+    @@logger ||= Pantry::Logger.new
+  end
+
+  def self.logger=(logger)
+    @@logger = logger
+  end
+
+  # Wrapper around the Celluloid's logging system. Depending on the passed in
+  # config, will send to STDOUT, Syslog, or a given file.
+  # See Celluloid::Logger for API (should be the same as Ruby's Logger API)
+  class Logger
+
+    def initialize(config = Pantry.config)
+      logger =
+        if config.log_to.nil? || config.log_to == "stdout"
+          ::Logger.new(STDOUT)
+        elsif config.log_to == "syslog"
+          ::Syslog::Logger.new(config.syslog_program_name)
+        else
+          ::Logger.new(config.log_to)
+        end
+
+      logger.level = log_level(config.log_level)
+      Celluloid.logger = logger
+    end
+
+    # Turn off all logging entirely
+    def disable!
+      Celluloid.logger = NullLogger.new
+    end
+
+    # Forward all methods on to the internal Celluloid Logger.
+    def method_missing(*args)
+      Celluloid.logger.send(*args) if Celluloid.logger
+    end
+
+    protected
+
+    def log_level(log_level_string)
+      case log_level_string.to_s
+      when "debug"
+        ::Logger::DEBUG
+      when "info"
+        ::Logger::INFO
+      when "warn"
+        ::Logger::WARN
+      when "error"
+        ::Logger::ERROR
+      when "fatal"
+        ::Logger::FATAL
+      else
+        raise "Unknown log level given: #{log_level_string}"
+      end
+    end
+
+  end
+
+  # Because Celluloid tries to log things on shut-down that throw
+  # tons of exceptions if the logger is nil
+  class NullLogger
+    def debug(*args)
+    end
+
+    def info(*args)
+    end
+
+    def warn(*args)
+    end
+
+    def error(*args)
+    end
+  end
+
+end

data/lib/pantry/message.rb

@@ -0,0 +1,134 @@
+module Pantry
+
+  # A Message is the container for all network communication between Clients and Servers.
+  # Messages know what stream they've been sent down, have a type to differentiate them
+  # from each other, and an arbitrarily large body.
+  #
+  # Every message has three sections, the stream, metadata, and body. The stream defines
+  # where the message needs to go. The metadata defines information about the message, its
+  # type, if it needs a response, and anything else that doesn't go in the body.
+  # The body is the request message itself and can be one or many parts.
+  class Message
+
+    # Unique identifier for this Message. Automatically generated
+    attr_reader :uuid
+
+    # Where or who is this message intended for (Can be an identity or a stream)
+    # Defaults to the catch-all stream `""`
+    attr_accessor :to
+
+    # Who is this message coming from (Should be an identity)
+    attr_accessor :from
+
+    # What type of message are we?
+    attr_accessor :type
+
+    # The full, raw body of the message.
+    attr_accessor :body
+
+    attr_accessor :custom_metadata
+
+    attr_writer :requires_response
+
+    def initialize(message_type = nil)
+      @type = message_type
+      @body = []
+      @to   = ""
+
+      @requires_response = false
+      @forwarded         = false
+
+      @custom_metadata   = {}
+
+      @uuid = SecureRandom.uuid
+    end
+
+    # Set the source of this message either by an object that responds to #identity
+    # or a string.
+    def from=(source)
+      if source.respond_to?(:identity)
+        @from = source.identity
+      else
+        @from = source
+      end
+    end
+
+    def from_server?
+      @from == Pantry::SERVER_IDENTITY
+    end
+
+    # Flag this message as requiring a response
+    def requires_response!
+      @requires_response = true
+    end
+
+    # Does this message require a response message?
+    def requires_response?
+      @requires_response
+    end
+
+    # Has this message been forwarded through the Server?
+    # This flag is checked when the message comes back through the Server,
+    # which lets it know if the message needs to continue back to another Client.
+    def forwarded!
+      @forwarded = true
+    end
+
+    def forwarded?
+      @forwarded
+    end
+
+    # Set custom metadata on this message.
+    def []=(key, val)
+      @custom_metadata[key] = val
+    end
+
+    # Access value from the custom metadata
+    def [](key)
+      @custom_metadata[key]
+    end
+
+    # Build a copy of this message to use when responding
+    # to the message
+    def build_response
+      response = self.clone
+      response.body = []
+      response.to   = self.from
+      response.from = self.to
+      response.requires_response = false
+      response.custom_metadata   = self.custom_metadata.clone
+      response
+    end
+
+    # Add a message part to this Message's body
+    def <<(part)
+      @body << part
+    end
+
+    # Return all of this message's metadata as a hash
+    def metadata
+      {
+        :uuid              => self.uuid,
+        :type              => self.type,
+        :from              => self.from,
+        :to                => self.to || "",
+        :requires_response => self.requires_response?,
+        :forwarded         => self.forwarded?,
+        :custom            => @custom_metadata
+      }
+    end
+
+    # Given a hash, pull out the parts into local variables
+    def metadata=(hash)
+      @uuid              = hash[:uuid]
+      @type              = hash[:type]
+      @from              = hash[:from]
+      @to                = hash[:to] || ""
+      @requires_response = hash[:requires_response]
+      @forwarded         = hash[:forwarded]
+      @custom_metadata   = hash[:custom]
+    end
+
+  end
+
+end

data/lib/pantry/multi_command.rb

@@ -0,0 +1,36 @@
+module Pantry
+
+  # A MultiCommand allows specifying multiple Commands to be run in succession.
+  # Each command class given in .performs will have it's #perform executed and
+  # the return values will be grouped together in a single return Message.
+  #
+  # It's currently expected that each Command executed is done when it's #perform
+  # returns.
+  class MultiCommand < Command
+
+    # MultiCommand.performs takes a list of Command class constants.
+    def self.performs(command_classes = [])
+      @command_classes = command_classes
+    end
+
+    def self.command_classes
+      @command_classes
+    end
+
+    # Iterate through each Command class and run that Command with the
+    # given message. The results of each Command will be combined into a single
+    # array return value and thus a single response Message back to the requester.
+    def perform(message)
+      Pantry.logger.debug("[#{client.identity}] Running MultiCommands")
+
+      self.class.command_classes.map do |command_class|
+        Pantry.logger.debug("[#{client.identity}] Running #{command_class}")
+        command = command_class.new
+        command.server_or_client = server_or_client
+        command.perform(message)
+      end
+    end
+
+  end
+
+end

data/lib/pantry/server.rb

@@ -0,0 +1,132 @@
+module Pantry
+
+  # The Pantry Server.
+  class Server
+    include Celluloid
+    finalizer :shutdown
+
+    attr_accessor :identity
+
+    attr_reader :client_registry
+
+    def initialize(network_stack_class = Communication::Server)
+      @commands = CommandHandler.new(self, Pantry.server_commands)
+      @identity = current_hostname
+      @clients  = []
+
+      @client_registry = ClientRegistry.new
+
+      @networking = network_stack_class.new_link(self)
+    end
+
+    # Start up the networking stack and start the server
+    def run
+      Pantry.set_proc_title("pantry server #{Pantry::VERSION}")
+      @networking.run
+      Pantry.logger.info("[#{@identity}] Server running")
+    end
+
+    # Close down networking and clean up resources
+    def shutdown
+      Pantry.logger.info("[#{@identity}] Server Shutting Down")
+    end
+
+    # Mark an authenticated client as checked-in
+    def register_client(client)
+      Pantry.logger.info("[#{@identity}] Received client registration :: #{client.identity}")
+      @client_registry.check_in(client)
+    end
+
+    # Generate new authentication credentials for a client.
+    # Returns a Hash containing the credentials required for the client to
+    # connect and authenticate with this Server
+    def create_client
+      @networking.create_client
+    end
+
+    # Return ClientInfo on which Client sent the given Message
+    def client_who_sent(message)
+      @client_registry.find(message.from)
+    end
+
+    # Broadcast a +message+ to all clients who match the given +filter+.
+    # By default all clients will be notified.
+    def publish_message(message, filter = Communication::ClientFilter.new)
+      Pantry.logger.debug("[#{@identity}] Publishing #{message.inspect} to #{filter.stream.inspect}")
+      message.to = filter.stream
+      @networking.publish_message(message)
+    end
+
+    # Callback from the network when a message is received unsolicited from a client.
+    # If the message received is unhandleable by this Server, the message is forwarded
+    # on down to the clients who match the message's +to+.
+    def receive_message(message)
+      Pantry.logger.debug("[#{@identity}] Received message #{message.inspect}")
+      if @commands.can_handle?(message)
+        results = @commands.process(message)
+
+        if message.requires_response?
+          Pantry.logger.debug("[#{@identity}] Returning results #{results.inspect}")
+          send_results_back_to_requester(message, results)
+        end
+      else
+        matched_clients = @client_registry.all_matching(message.to).map(&:identity)
+
+        Pantry.logger.debug("[#{@identity}] Forwarding message on. Expect response from #{matched_clients.inspect}")
+        send_results_back_to_requester(message, matched_clients, true)
+        forward_message(message)
+      end
+    end
+
+    # Send a Pantry::Message but mark it as requiring a response.
+    # This will set up and return a Celluloid::Future that will contain the
+    # response once it is available.
+    def send_request(client, message)
+      message.requires_response!
+      message.to = client.identity
+
+      Pantry.logger.debug("[#{@identity}] Sending request #{message.inspect}")
+
+      @networking.send_request(message)
+    end
+
+    # Start a FileService::SendFile worker to upload the contents of the
+    # file at +file_path+ to the equivalent ReceiveFile at +receiver_uuid+.
+    # Using this method requires asking the receiving end (Server or Client) to receive
+    # a file first, which will return the +receiver_uuid+ and +file_uuid+ to use here.
+    def send_file(file_path, receiver_uuid, file_uuid)
+      @networking.send_file(file_path, receiver_uuid, file_uuid)
+    end
+
+    # Set up a FileService::ReceiveFile worker to begin receiving a file with
+    # the given size and checksum. This returns an informational object with
+    # the new receiver's identity and the file UUID so a SendFile worker knows who
+    # to send the file contents to.
+    def receive_file(file_size, file_checksum)
+      @networking.receive_file(file_size, file_checksum)
+    end
+
+    protected
+
+    def current_hostname
+      Socket.gethostname
+    end
+
+    def send_results_back_to_requester(message, results, client_response_list = false)
+      response_message = message.build_response
+      response_message.from = Pantry::SERVER_IDENTITY
+      response_message[:client_response_list] = client_response_list
+
+      [results].flatten(1).each do |entry|
+        response_message << entry
+      end
+
+      @networking.publish_message(response_message)
+    end
+
+    def forward_message(message)
+      @networking.forward_message(message)
+    end
+
+  end
+end

data/lib/pantry/test/acceptance.rb

@@ -0,0 +1,83 @@
+#
+# Require this file to grab the Pantry acceptance test environment.
+# Acceptance tests run a full network of server and multiple clients,
+# and are normally run via a CLI.
+#
+
+require 'pantry'
+require 'celluloid/test'
+require 'pantry/test/support/minitest'
+require 'pantry/test/support/matchers'
+require 'pantry/test/support/mock_ui'
+require 'pantry/test/support/fake_fs'
+
+# Catch and show all exceptions thrown during a test run
+$all_exceptions = []
+Celluloid.exception_handler do |exception|
+  $all_exceptions << exception
+end
+
+Minitest.after_run do
+  $all_exceptions.each do |exception|
+    puts exception
+    puts exception.backtrace.join("\n")
+    puts ""
+  end
+end
+
+# Set up a Server-only echo command so we can differentiate between
+# Client requests and Server requests in the acceptance tests.
+class ServerEchoCommand < Pantry::Commands::Echo
+end
+
+module PantryAcceptanceHelpers
+  def configure_pantry(ports_start_at: 10101, heartbeat: 300, security: nil)
+    Pantry.config.server_host  = "127.0.0.1"
+    Pantry.config.pub_sub_port = ports_start_at
+    Pantry.config.receive_port = ports_start_at + 1
+    Pantry.config.file_service_port = ports_start_at + 2
+    Pantry.config.client_heartbeat_interval = heartbeat
+    Pantry.config.response_timeout = 5
+    Pantry.config.security = security
+
+    begin
+      Pantry.add_server_command(ServerEchoCommand)
+    rescue Pantry::DuplicateCommandError
+      # Already registered
+    end
+  end
+
+  # Set up a fully functional Server + 2 Client environment on the given ports
+  # Make sure that the ports given are different for each test or port-conflict
+  # errors will happen. Tests should also have a wide enough range between their ports,
+  # to ensure there's room for the current setup and any later expansion (10 is a good number).
+  #
+  # This helper exposes @server, @client1, and @client2 for use in tests
+  def set_up_environment(ports_start_at: 10101, heartbeat: 300, security: nil)
+    Celluloid.boot
+
+    configure_pantry(ports_start_at: ports_start_at, heartbeat: heartbeat, security: security)
+
+    @server = Pantry::Server.new
+    @server.identity = "Test Server"
+    @server.run
+
+    @client1 = Pantry::Client.new identity: "client1", application: "pantry", environment: "test", roles: ["app1"]
+    @client1.run
+
+    @client2 = Pantry::Client.new identity: "client2", application: "pantry", environment: "test", roles: ["app2"]
+    @client2.run
+  end
+
+  def after_teardown
+    @client1.shutdown if @client1
+    @client2.shutdown if @client2
+    @server.shutdown  if @server
+
+    Celluloid.shutdown rescue nil
+  end
+end
+
+class Minitest::Test
+  include PantryAcceptanceHelpers
+end