qpid_proton 0.9.0 → 0.10

data/lib/core/transport.rb

@@ -0,0 +1,411 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+module Qpid::Proton
+
+  # A transport is used by a connection to interface with the network.
+  #
+  # A transport is associated with, at most, one Connection.
+  #
+  # == Client And Server Mode
+  #
+  # Initially, a transport is configured to be a client tranpsort. It can be
+  # configured to act as a server when it is created.
+  #
+  # A client transport initiates outgoing connections.
+  #
+  # A client transport must be configured with the protocol layers to use and
+  # cannot configure itself automatically.
+  #
+  # A server transport accepts incoming connections. It can automatically
+  # configure itself to include the various protocol layers depending on the
+  # incoming protocol headers.
+  #
+  # == Tracing Data
+  #
+  # Data can be traced into and out of the transport programmatically by setting
+  # the #trace level to one of the defined trace values (TRACE_RAW, TRACE_FRM or
+  # TRACE_DRV). Tracing can also be turned off programmatically by setting the
+  # #trace level to TRACE_OFF.
+  #
+  # @example
+  #
+  #   # turns on frame tracing
+  #   @transport.trace = Qpid::Proton::Transport::TRACE_FRM
+  #
+  #   # ... do something where the frames are of interest, such as debugging
+  #
+  #   # turn tracing off again
+  #   @transport.trace = Qpid::Proton::Transport::TRACE_NONE
+  #
+  # Tracing can also be enabled from the command line by defining the similarly
+  # named environment variable before starting a Proton application:
+  #
+  # @example
+  #
+  #   # enable tracing from the command line
+  #   PN_TRACE_FRM=1 ruby my_proton_app.rb
+  #
+  class Transport
+
+    # @private
+    include Util::Engine
+
+    # Turn logging off entirely.
+    TRACE_OFF = Cproton::PN_TRACE_OFF
+    # Log raw binary data into/out of the transport.
+    TRACE_RAW = Cproton::PN_TRACE_RAW
+    # Log frames into/out of the transport.
+    TRACE_FRM = Cproton::PN_TRACE_FRM
+    # Log driver related events; i.e., initialization, end of stream, etc.
+    TRACE_DRV = Cproton::PN_TRACE_DRV
+
+    # @private
+    CLIENT = 1
+    # @private
+    SERVER = 2
+
+    # @private
+    include Util::SwigHelper
+
+    # @private
+    PROTON_METHOD_PREFIX = "pn_transport"
+
+    # @!attribute channel_max
+    #
+    # @return [Fixnum] The maximum allowed channel.
+    #
+    proton_accessor :channel_max
+
+    # @!attribute [r] remote_channel_max
+    #
+    # @return [Fixnum] The maximum allowed channel of a transport's remote peer.
+    #
+    proton_caller :remote_channel_max
+
+    # @!attribute max_frame_size
+    #
+    # @return [Fixnum] The maximum frame size.
+    #
+    proton_accessor :max_frame_size
+
+    # @!attribute [r] remote_max_frame_size
+    #
+    # @return [Fixnum] The maximum frame size of the transport's remote peer.
+    #
+    proton_reader :remote_max_frame_size
+
+    # @!attribute idle_timeout
+    #
+    # @return [Fixnum] The idle timeout.
+    #
+    proton_accessor :idle_timeout
+
+    # @!attribute [r] remote_idle_timeout
+    #
+    # @return [Fixnum] The idle timeout for the transport's remote peer.
+    #
+    proton_accessor :remote_idle_timeout
+
+    # @!attribute [r] capacity
+    #
+    # If the engine is in an exception state such as encountering an error
+    # condition or reaching the end of stream state, a negative value will
+    # be returned indicating the condition.
+    #
+    # If an error is indicated, further deteails can be obtained from
+    # #error.
+    #
+    # Calls to #process may alter the value of this value. See #process for
+    # more details
+    #
+    # @return [Fixnum] The amount of free space for input following the
+    # transport's tail pointer.
+    #
+    proton_caller :capacity
+
+    # @!attribute [r] head
+    #
+    # This referneces queued output data. It reports the bytes of output data.
+    #
+    # Calls to #pop may alter this attribute, and any data it references.
+    #
+    # @return [String] The transport's head pointer.
+    #
+    proton_caller :head
+
+    # @!attribute [r] tail
+    #
+    # The amount of free space following this data is reported by #capacity.
+    #
+    # Calls to #process may alter the value of this attribute.
+    #
+    # @return [String] The transport's tail pointer.
+    #
+    proton_caller :tail
+
+    # @!attribute [r] pending
+    #
+    # If the ending is in an exceptional state, such as encountering an error
+    # condition or reachign the end of the stream state, a negative value will
+    # be returned indicating the condition.
+    #
+    # If an error is indicated, further details can be obtained from #error.
+    #
+    # Calls to #pop may alter the value of this pointer as well.
+    #
+    # @return [Fixnum] The number of pending output bytes following the header
+    # pointer.
+    #
+    # @raise [TransportError] If any error other than an end of stream occurs.
+    #
+    proton_caller :pending
+
+    # @!attribute [r] closed?
+    #
+    # A transport is defined to be closed when both the tail and the head are
+    # closed. In other words, when both #capacity < 0 and #pending < 0.
+    #
+    # @return [Boolean] Returns true if the tranpsort is closed.
+    #
+    proton_caller :closed?
+
+    # @!attribute [r] frames_output
+    #
+    # @return [Fixnum] The number of frames output by a transport.
+    #
+    proton_reader :frames_output
+
+    # @!attribute [r] frames_input
+    #
+    # @return [Fixnum] The number of frames input by a transport.
+    #
+    proton_reader :frames_input
+
+    # @private
+    include Util::ErrorHandler
+
+    can_raise_error :process, :error_class => TransportError
+    can_raise_error :close_tail, :error_class => TransportError
+    can_raise_error :pending, :error_class => TransportError, :below => Error::EOS
+    can_raise_error :close_head, :error_class => TransportError
+
+    # @private
+    include Util::Wrapper
+
+    # @private
+    def self.wrap(impl)
+      return nil if impl.nil?
+
+      self.fetch_instance(impl, :pn_transport_attachments) || Transport.new(nil, impl)
+    end
+
+    # Creates a new transport instance.
+    #
+    # @param mode [Fixnum] The transport mode, either CLIENT or SERVER
+    # @param impl [pn_transport_t] Should not be used.
+    #
+    # @raise [TransportError] If the mode is invalid.
+    #
+    def initialize(mode = nil, impl = Cproton.pn_transport)
+      @impl = impl
+      if mode == SERVER
+        Cproton.pn_transport_set_server(@impl)
+      elsif (!mode.nil? && mode != CLIENT)
+        raise TransportError.new("cannot create transport for mode: #{mode}")
+      end
+      self.class.store_instance(self, :pn_transport_attachments)
+    end
+
+    # Returns whether the transport has any buffered data.
+    #
+    # @return [Boolean] True if the transport has no buffered data.
+    #
+    def quiesced?
+      Cproton.pn_transport_quiesced(@impl)
+    end
+
+    # Returns additional information about the condition of the transport.
+    #
+    # When a TRANSPORT_ERROR event occurs, this operaiton can be used to
+    # access the details of the error condition.
+    #
+    # The object returned is valid until the Transport is discarded.
+    #
+    def condition
+      condition_to_object Cproton.pn_transport_condition(@impl)
+    end
+
+    # Binds to the given connection.
+    #
+    # @param connection [Connection] The connection.
+    #
+    def bind(connection)
+      Cproton.pn_transport_bind(@impl, connection.impl)
+    end
+
+    # Unbinds from the previous connection.
+    #
+    def unbind
+      Cproton.pn_transport_unbind(@impl)
+    end
+
+    # Updates the transports trace flags.
+    #
+    # @param level [Fixnum] The trace level.
+    #
+    # @see TRACE_OFF
+    # @see TRACE_RAW
+    # @see TRACE_FRM
+    # @see TRACE_DRV
+    #
+    def trace(level)
+      Cproton.pn_transport_trace(@impl, level)
+    end
+
+    # Return the AMQP connection associated with the transport.
+    #
+    # @return [Connection, nil] The bound connection, or nil.
+    #
+    def connection
+      Connection.wrap(Cproton.pn_transport_connection(@impl))
+    end
+
+    # Log a message to the transport's logging mechanism.
+    #
+    # This can be using in a debugging scenario as the message will be
+    # prepended with the transport's identifier.
+    #
+    # @param message [String] The message to be logged.
+    #
+    def log(message)
+      Cproton.pn_transport_log(@impl, message)
+    end
+
+    # Pushes the supplied bytes into the tail of the transport.
+    #
+    # @param data [String] The bytes to be pushed.
+    #
+    # @return [Fixnum] The number of bytes pushed.
+    #
+    def push(data)
+      Cproton.pn_transport_push(@impl, data, data.length)
+    end
+
+    # Process input data following the tail pointer.
+    #
+    # Calling this function will cause the transport to consume the specified
+    # number of bytes of input occupying the free space following the tail
+    # pointer. It may also change the value for #tail, as well as the amount of
+    # free space reported by #capacity.
+    #
+    # @param size [Fixnum] The number of bytes to process.
+    #
+    # @raise [TransportError] If an error occurs.
+    #
+    def process(size)
+      Cproton.pn_transport_process(@impl, size)
+    end
+
+    # Indicate that the input has reached EOS (end of stream).
+    #
+    # This tells the transport that no more input will be forthcoming.
+    #
+    # @raise [TransportError] If an error occurs.
+    #
+    def close_tail
+      Cproton.pn_transport_close_tail(@impl)
+    end
+
+    # Returns the specified number of bytes from the transport's buffers.
+    #
+    # @param size [Fixnum] The number of bytes to return.
+    #
+    # @return [String] The data peeked.
+    #
+    # @raise [TransportError] If an error occurs.
+    #
+    def peek(size)
+      cd, out = Cproton.pn_transport_peek(@impl, size)
+      return nil if cd == Qpid::Proton::Error::EOS
+      raise TransportError.new if cd < -1
+      out
+    end
+
+    # Removes the specified number of bytes from the pending output queue
+    # following the transport's head pointer.
+    #
+    # @param size [Fixnum] The number of bytes to remove.
+    #
+    def pop(size)
+      Cproton.pn_transport_pop(@impl, size)
+    end
+
+    # Indicate that the output has closed.
+    #
+    # Tells the transport that no more output will be popped.
+    #
+    # @raise [TransportError] If an error occurs.
+    #
+    def close_head
+      Cproton.pn_transport_close_head(@impl)
+    end
+
+    # Process any pending transport timer events.
+    #
+    # This method should be called after all pending input has been
+    # processed by the transport (see #input), and before generating
+    # output (see #output).
+    #
+    # It returns the deadline for the next pending timer event, if any
+    # art present.
+    #
+    # @param now [Time] The timestamp.
+    #
+    # @return [Fixnum] If non-zero, the expiration time of the next pending
+    #   timer event for the transport. The caller must invoke #tick again at
+    #   least once at or before this deadline occurs.
+    #
+    def tick(now)
+      Cproton.pn_transport_tick(@impl, now)
+    end
+
+    def sasl
+      SASL.new(self)
+    end
+
+    # Creates, or returns an existing, SSL object for the transport.
+    #
+    # @param domain [SSLDomain] The SSL domain.
+    # @param session_details [SSLDetails] The SSL session details.
+    #
+    # @return [SSL] The SSL object.
+    #
+    def ssl(domain = nil, session_details = nil)
+      @ssl ||= SSL.create(self, domain, session_details) if @ssl.nil?
+    end
+
+    # @private
+    def ssl?
+      !@ssl.nil?
+    end
+
+  end
+
+end

data/lib/core/url.rb

@@ -0,0 +1,77 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+module Qpid::Proton
+
+  class URL
+
+    attr_reader :scheme
+    attr_reader :username
+    attr_reader :password
+    attr_reader :host
+    attr_reader :port
+    attr_reader :path
+
+    def initialize(url = nil, options = {})
+      options[:defaults] = true
+
+      if url
+        @url = Cproton.pn_url_parse(url)
+        if @url.nil?
+          raise ::ArgumentError.new("invalid url: #{url}")
+        end
+      else
+        @url = Cproton.pn_url
+      end
+      @scheme = Cproton.pn_url_get_scheme(@url)
+      @username = Cproton.pn_url_get_username(@url)
+      @password = Cproton.pn_url_get_password(@url)
+      @host = Cproton.pn_url_get_host(@url)
+      @port = Cproton.pn_url_get_port(@url)
+      @path = Cproton.pn_url_get_path(@url)
+      defaults
+    end
+
+    def port=(port)
+      if port.nil?
+        Cproton.pn_url_set_port(@url, nil)
+      else
+        Cproton.pn_url_set_port(@url, port)
+      end
+    end
+
+    def port
+      Cproton.pn_url_get_port(@url).to_i
+    end
+
+    def to_s
+      "#{@scheme}://#{@username.nil? ? '' : @username}#{@password.nil? ? '' : '@' + @password + ':'}#{@host}:#{@port}/#{@path}"
+    end
+
+    private
+
+    def defaults
+      @scheme = @scheme || "ampq"
+      @host = @host || "0.0.0.0"
+      @port = @port || 5672
+    end
+
+  end
+
+end