roby 0.8.0 → 3.0.0

data/lib/roby/interface/job.rb

@@ -0,0 +1,47 @@
+module Roby
+    module Interface
+        # A task service that is used to tag tasks that are job in the plan.
+        # Only the tasks that provide Job, are missions and have a non-nil
+        # {#job_id} argument are proper jobs.
+        task_service 'Job' do
+            # The job ID
+            #
+            # If non-nil, it is used to refer to the job in various Interface
+            # APIs. Otherwise, the task will not be considered a proper job at
+            # all
+            #
+            # It is nil by default if Conf.app.auto_allocate_job_ids? is false
+            # )which is the default). Otherwise, {#initialize} will
+            # auto-allocate a job ID using {#allocate_job_id}.
+            #
+            # @return [Integer,nil]
+            argument :job_id, default: nil
+
+            def self.allocate_job_id
+                @@job_id += 1
+            end
+            @@job_id = 0
+
+            # Automatically allocate a job ID
+            #
+            # @return [Integer]
+            def allocate_job_id
+                self.job_id ||= Job.allocate_job_id
+            end
+
+            # @return [String] the job name as should be displayed by the job
+            #   management API
+            def job_name
+                to_s
+            end
+
+            def initialize(arguments = Hash.new)
+                super
+                if Conf.app.auto_allocate_job_ids? && !job_id
+                    allocate_job_id
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/interface/rest.rb

@@ -0,0 +1,10 @@
+require 'eventmachine'
+require 'rack'
+require 'thin'
+require 'rest-client'
+require 'grape'
+
+require 'roby/interface/rest/server'
+require 'roby/interface/rest/helpers'
+require 'roby/interface/rest/api'
+

data/lib/roby/interface/rest/api.rb

@@ -0,0 +1,29 @@
+module Roby
+    module Interface
+        module REST
+            # The endpoints
+            class API < Grape::API
+                version 'v1', using: :header, vendor: :syskit
+                format :json
+
+                helpers Helpers
+
+                params do
+                    optional :value, type: Integer, default: 20
+                end
+                get 'ping' do
+                    if !interface
+                        error!({error: 'Internal Error', details: 'no attached Roby interface'}, 500)
+                    end
+                    params[:value]
+                end
+
+                # Quits the Roby app
+                post 'quit' do
+                    interface.quit
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/interface/rest/helpers.rb

@@ -0,0 +1,24 @@
+module Roby
+    module Interface
+        module REST
+            module Helpers
+                def interface
+                    env['roby.interface']
+                end
+
+                def roby_app
+                    @roby_app ||= interface.app
+                end
+
+                def roby_storage
+                    env['roby.storage']
+                end
+
+                def execution_engine
+                    @execution_engine ||= interface.execution_engine
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/interface/rest/server.rb

@@ -0,0 +1,212 @@
+module Roby
+    module Interface
+        module REST
+            # A thin-based server class that provides the REST API in-process
+            class Server
+                # The application that is being exposed by this server
+                attr_reader :app
+
+                # The host the server is bound to
+                #
+                # @return [String]
+                attr_reader :host
+
+                # The port the server is bound to
+                #
+                # If zero is originally given to {#initialize} for a TCP server
+                # setup, this will be changed to the actual port number when it
+                # is known
+                #
+                # @return [Integer]
+                attr_reader :port
+
+                # Create a new server
+                #
+                # @param [Roby::Application] the application this server will
+                #   be exposing
+                # @param [String] host the host the server should bind to. Either
+                #   an IP for a TCP server, or a path to a UNIX socket
+                # @param [Integer] port the port the server should bind to if it
+                #   is a TCP server. Set to zero to auto-allocate. Ignored if 'host'
+                #   is the path to a UNIX socket.
+                def initialize(app, host: '0.0.0.0', port: Roby::Interface::DEFAULT_REST_PORT,
+                               api: REST::API)
+                    @app = app
+                    @host = host
+                    @interface = Interface.new(app)
+                    @wait_start = Concurrent::IVar.new
+
+                    api = self.class.attach_api_to_interface(api, @interface)
+                    rack_app = Rack::Builder.new do
+                        yield(self) if block_given?
+
+                        map '/api' do
+                            run api
+                        end
+                    end
+                    @server = Thin::Server.new(host, port, rack_app, signals: false)
+                    @server.silent = true
+                    if @server.backend.respond_to?(:port)
+                        @original_port = port
+                        if port != 0
+                            @port = port
+                        end
+                    else
+                        @original_port = @port = nil
+                    end
+                end
+
+                # @api private
+                #
+                # Helper method that transforms a Grape API class so that it
+                # gets an #interface accessor that provides the interface
+                # object the API is meant to work on
+                def self.attach_api_to_interface(api, interface)
+                    storage = Hash.new
+                    Class.new do
+                        define_method(:call) do |env|
+                            env['roby.interface'] = interface
+                            env['roby.storage'] = storage
+                            api.call(env)
+                        end
+                    end.new
+                end
+
+                # Starts the server
+                #
+                # @param [Numeric,nil] wait_timeout how long the method should
+                #   wait for the server to be started and functional. Set to
+                #   zero to not wait at all, and nil to wait forever
+                # @raise [Timeout] if wait_timeout is non-zero and the timeout
+                #   was reached while waiting for the server to start
+                def start(wait_timeout: 5)
+                    @server_thread = create_thin_thread(@server, @wait_start)
+                    if wait_timeout != 0
+                        wait_start(timeout: wait_timeout)
+                    end
+                end
+
+                # Whether the server is running
+                def running?
+                    @server_thead && @server_thread.alive?
+                end
+
+                # @api private
+                #
+                # Create the underlying thread that starts the thin server
+                def create_thin_thread(server, sync)
+                    Thread.new do
+                        server.backend.start do
+                            if server.backend.respond_to?(:port)
+                                sync.set(server.backend.port)
+                            else
+                                sync.set(nil)
+                            end
+                        end
+                    end
+                end
+
+                # The server port
+                #
+                # If the port given to {#initialize} was zero, the method will
+                # return the actual port only if the server is fully started.
+                # Set timeout to a value greater than zero or nil to
+                # synchronize on it.
+                #
+                # @param [Integer,nil] timeout how long the method is allowed
+                #   to wait for the server to start, in case the original port
+                #   was set to zero
+                # @raise [Timeout]
+                def port(timeout: 0)
+                    if @port
+                        return @port
+                    elsif !@original_port
+                        return nil
+                    else
+                        wait_start(timeout: timeout)
+                        @port = @wait_start.value!
+                    end
+                end
+
+                # Exception raised by the methods that could time out
+                class Timeout < RuntimeError; end
+
+                # Wait for the server to be properly booted
+                #
+                # @param [Numeric,nil] timeout how long the method is allowed to block
+                #   waiting for the server to start. Set to zero to not wait at all
+                #   and nil to wait forever
+                # @raise [Timeout]
+                def wait_start(timeout: 10)
+                    @wait_start.wait(timeout)
+                    if !@wait_start.complete?
+                        raise Timeout, "timed out while waiting for the server to start"
+                    end
+                end
+
+                # Asks the server to stop
+                #
+                # @param [Numeric,nil] join_timeout how long the method is allowed
+                #   to block waiting for the thread to stop. Set to zero to not
+                #   wait at all, and nil to wait forever
+                # @raise [Timeout]
+                def stop(join_timeout: 10)
+                    EventMachine.next_tick { @server.stop! }
+                    if join_timeout != 0
+                        join(timeout: join_timeout)
+                    end
+                end
+
+                # Waits for the server to stop
+                #
+                # @param [Numeric,nil] timeout how long the method is allowed
+                #   to block waiting for the thread to stop. Set to zero to not
+                #   wait at all, and nil to wait forever
+                # @raise [Timeout]
+                def join(timeout: nil)
+                    if timeout
+                        if !@server_thread.join(timeout)
+                            raise Timeout, "timed out while waiting for the server to stop"
+                        end
+                    else
+                        @server_thread.join
+                    end
+                end
+
+                # Exception raised by {#server_alive?} if there is a server at
+                # the expected host and port, but not a Roby REST server
+                class InvalidServer < RuntimeError; end
+
+                # (see Server.server_alive?)
+                def server_alive?
+                    if !@wait_start.complete?
+                        return false
+                    else
+                        self.class.server_alive?('localhost', port)
+                    end
+                end
+
+                # Tests whether the server is actually alive
+                #
+                # It accesses the 'ping' endpoint and verifies its result
+                #
+                # @raise InvalidServer if there is a server at the expected
+                #   host and port, but not a Roby REST server
+                def self.server_alive?(host, port)
+                    test_value = rand(10)
+                    returned_value = RestClient.
+                        get("http://#{host}:#{port}/api/ping", params: { value: test_value })
+                    if test_value != Integer(returned_value)
+                        raise InvalidServer, "unexpected server answer to 'ping', expected #{test_value} but got #{returned_value}"
+                    end
+                    true
+                rescue Errno::ECONNREFUSED => e
+                    false
+                rescue RestClient::Exception => e
+                    raise InvalidServer, "unexpected server answer to 'ping': #{e}"
+                end
+            end
+        end
+    end
+end
+

data/lib/roby/interface/server.rb

@@ -0,0 +1,154 @@
+module Roby
+    module Interface
+        # The server-side object allowing to access an interface (e.g. a Roby app)
+        # through any communication channel
+        class Server
+            # @return [DRobyChannel] the IO to the client
+            attr_reader :io
+            # @return [Interface] the interface object we are giving access to
+            attr_reader :interface
+            # @return [String] a string that allows the user to identify the client
+            attr_reader :client_id
+            # @return [Boolean] whether the messages should be
+            #   forwarded to our clients
+            attr_predicate :notifications_enabled?, true
+
+            # @param [DRobyChannel] io a channel to the server
+            # @param [Interface] interface the interface object we give remote
+            #   access to
+            def initialize(io, interface, main_thread: Thread.current)
+                @notifications_enabled = true
+                @io = io
+                @interface = interface
+                @main_thread = main_thread
+                @pending_notifications = Queue.new
+
+                interface.on_cycle_end do
+                    write_packet(
+                        [
+                            :cycle_end,
+                            interface.execution_engine.cycle_index,
+                            interface.execution_engine.cycle_start
+                        ], defer_exceptions: true)
+                end
+                interface.on_notification do |*args|
+                    if notifications_enabled?
+                        @pending_notifications << args
+                    end
+                    if Thread.current == @main_thread
+                        flush_pending_notifications
+                    end
+                end
+                interface.on_ui_event do |*args|
+                    write_packet([:ui_event, *args], defer_exceptions: true)
+                end
+                interface.on_job_notification do |*args|
+                    write_packet([:job_progress, *args], defer_exceptions: true)
+                end
+                interface.on_exception do |*args|
+                    write_packet([:exception, *args], defer_exceptions: true)
+                end
+            end
+
+            def flush_pending_notifications
+                notifications = []
+                until @pending_notifications.empty?
+                    notifications << @pending_notifications.pop
+                end
+                notifications.each do |args|
+                    write_packet([:notification, *args], defer_exceptions: true)
+                end
+            end
+
+            def to_io
+                io.to_io
+            end
+
+            def handshake(id)
+                @client_id = id
+                Roby::Interface.info "new interface client: #{id}"
+                [interface.actions, interface.commands]
+            end
+
+            def enable_notifications
+                self.notifications_enabled = true
+            end
+
+            def disable_notifications
+                self.notifications_enabled = false
+            end
+
+            def closed?
+                io.closed?
+            end
+
+            def close
+                io.close
+            end
+
+            def process_batch(path, calls)
+                calls.map do |p, m, *a|
+                    process_call(path + p, m, *a)
+                end
+            end
+
+            def process_call(path, name, *args)
+                if path.empty? && respond_to?(name)
+                    send(name, *args)
+                else
+                    receiver = path.inject(interface) do |obj, subcommand|
+                        obj.send(subcommand)
+                    end
+                    receiver.send(name, *args)
+                end
+            end
+
+            def has_deferred_exception?
+                @deferred_exception
+            end
+
+            def write_packet(call, defer_exceptions: false)
+                return if has_deferred_exception?
+
+                flush_pending_notifications
+                io.write_packet(call)
+            rescue Exception => e
+                if defer_exceptions
+                    @deferred_exception = e
+                else raise
+                end
+            end
+
+            # Process one command from the client, and send the reply
+            def poll
+                raise @deferred_exception if has_deferred_exception?
+
+                path, m, *args = io.read_packet
+                return unless m
+
+                begin
+                    reply =
+                        if m == :process_batch
+                            process_batch(path, args.first)
+                        else
+                            process_call(path, m, *args)
+                        end
+
+                    true
+                rescue Exception => e
+                    write_packet([:bad_call, e])
+                    return
+                end
+
+                begin
+                    write_packet([:reply, reply])
+                rescue ComError
+                    raise
+                rescue Exception => e
+                    write_packet([:protocol_error, e])
+                    raise
+                end
+            end
+        end
+    end
+end