qpid_proton 0.18.1 → 0.19.0

data/lib/core/tracker.rb

@@ -0,0 +1,45 @@
+# 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
+
+  # Track the {Transfer::State} of a sent message.
+  class Tracker < Transfer
+    # @return [Sender] The parent {Sender} link.
+    def sender() link; end
+
+    # Re-delivery modifications sent by the receiver in {Delivery#release}
+    # @return [Hash] See the {Delivery#release} +opts+ parameter.
+    # @return [nil] If no modifications were requested by the receiver.
+    def modifications()
+      return nil if (state != MODIFIED)
+      d = Cproton.pn_delivery_remote(@impl)
+      {
+       :failed => Cproton.pn_disposition_is_failed(d),
+       :undeliverable => Cproton.pn_disposition_is_undeliverable(d),
+       :annotations => Codec::Data.to_object(Cproton.pn_disposition_annotations(d))
+      }
+    end
+
+    # Abort a partially-sent message.
+    # The tracker can no longer be used after calling {#abort}.
+    def abort()
+      Cproton.pn_delivery_abort(@impl)
+    end
+  end
+end

data/lib/core/transfer.rb

@@ -0,0 +1,121 @@
+# 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
+
+  # Status of a message transfer on a {Link}
+  # Common base class for {Tracker} and {Delivery}.
+  class Transfer
+    include Util::Deprecation
+
+    # @!private
+    PROTON_METHOD_PREFIX = "pn_delivery"
+    # @!private
+    include Util::Wrapper
+
+    def self.wrap(impl)
+      return unless impl
+      self.fetch_instance(impl, :pn_delivery_attachments) ||
+        (Cproton.pn_link_is_sender(Cproton.pn_delivery_link(impl)) ? Tracker : Delivery).new(impl)
+    end
+
+    def initialize(impl)
+      @impl = impl
+      @inspect = nil
+      self.class.store_instance(self, :pn_delivery_attachments)
+    end
+
+    public
+
+    # AMQP Delivery States describing the outcome of a message transfer
+    module State
+      # Message was successfully processed by the receiver
+      ACCEPTED = Cproton::PN_ACCEPTED
+
+      # Message rejected as invalid and unprocessable by the receiver.
+      REJECTED = Cproton::PN_REJECTED
+
+      # Message was not (and will not be) processed by the receiver, but may be
+      # acceptable if re-delivered to another receiver
+      RELEASED = Cproton::PN_RELEASED
+
+      # Like {RELEASED}, but there are modifications (see {Tracker#modifications})
+      # that must be applied to the message by the {Sender} before re-delivering it.
+      MODIFIED = Cproton::PN_MODIFIED
+
+      # Partial message data received. Only used during link recovery.
+      RECEIVED =  Cproton::PN_RECEIVED
+    end
+
+    include State
+
+    # @return [String] Unique ID for the transfer in the context of the {#link}
+    def id() Cproton.pn_delivery_tag(@impl); end
+
+    # @deprecated use {#id}
+    deprecated_alias :tag, :id
+
+    # @return [Boolean] True if the transfer has is remotely settled.
+    proton_caller :settled?
+
+    # @return [Integer] Remote state of the transfer, one of the values in {State}
+    def state() Cproton.pn_delivery_remote_state(@impl); end
+
+    # @return [Link] The parent link.
+    def link() Link.wrap(Cproton.pn_delivery_link(@impl)); end
+
+    # @return [Session] The parent session.
+    def session() link.session; end
+
+    # @return [Connection] The parent connection.
+    def connection() self.session.connection; end
+
+    # @return [Transport] The parent connection's transport.
+    def transport() self.connection.transport; end
+
+    # @deprecated internal use only
+    proton_caller :writable?
+    # @deprecated internal use only
+    proton_caller :readable?
+    # @deprecated internal use only
+    proton_caller :updated?
+    # @deprecated internal use only
+    proton_caller :clear
+    # @deprecated internal use only
+    proton_caller :pending
+    # @deprecated internal use only
+    proton_caller :partial?
+    # @deprecated internal use only
+    def update(state) Cproton.pn_delivery_update(@impl, state); end
+    # @deprecated internal use only
+    proton_caller :buffered?
+    # @deprecated internal use only
+    def local_state() Cproton.pn_delivery_local_state(@impl); end
+    # @deprecated use {#state}
+    deprecated_alias :remote_state, :state
+    # @deprecated internal use only
+    def settle(state = nil)
+      update(state) unless state.nil?
+      Cproton.pn_delivery_settle(@impl)
+      @inspect = inspect # Save the inspect string, the delivery pointer will go bad.
+    end
+
+    def inspect() @inspect || super; end
+    def to_s() inspect; end
+  end
+end

data/lib/core/transport.rb

@@ -1,4 +1,3 @@
-#--
 # 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
@@ -15,57 +14,18 @@
 # 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
-  #
+  # @deprecated all important features are available from {#Connection}
   class Transport
+    include Util::Deprecation
 
     # @private
-    include Util::Engine
+    PROTON_METHOD_PREFIX = "pn_transport"
+    # @private
+    include Util::Wrapper
 
     # Turn logging off entirely.
     TRACE_OFF = Cproton::PN_TRACE_OFF
@@ -76,22 +36,13 @@ module Qpid::Proton
     # 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"
+    proton_get :user
 
     # @!attribute channel_max
     #
     # @return [Integer] The maximum allowed channel.
     #
-    proton_accessor :channel_max
+    proton_set_get :channel_max
 
     # @!attribute [r] remote_channel_max
     #
@@ -102,26 +53,34 @@ module Qpid::Proton
     # @!attribute max_frame_size
     #
     # @return [Integer] The maximum frame size.
-    #
-    proton_accessor :max_frame_size
+    proton_set_get :max_frame
+    proton_get :remote_max_frame
 
     # @!attribute [r] remote_max_frame_size
     #
     # @return [Integer] The maximum frame size of the transport's remote peer.
     #
-    proton_reader :remote_max_frame_size
+    proton_get :remote_max_frame_size
 
     # @!attribute idle_timeout
     #
-    # @return [Integer] The idle timeout.
+    # @deprecated use {Connection#open} with the +:idle_timeout+ option to set
+    # the timeout, and {Connection#idle_timeout} to query the remote timeout.
+    #
+    # The Connection timeout values are in *seconds* and are automatically
+    # converted.
+    #
+    # @return [Integer] The idle timeout in *milliseconds*.
     #
-    proton_accessor :idle_timeout
+    proton_set_get :idle_timeout
 
-    # @!attribute [r] remote_idle_timeout
+    # @!attribute [r] remote_idle_timeout in milliseconds
+    #
+    # @deprecated Use {Connection#idle_timeout} to query the remote timeout.
     #
     # @return [Integer] The idle timeout for the transport's remote peer.
     #
-    proton_accessor :remote_idle_timeout
+    proton_set_get :remote_idle_timeout
 
     # @!attribute [r] capacity
     #
@@ -190,49 +149,34 @@ module Qpid::Proton
     #
     # @return [Integer] The number of frames output by a transport.
     #
-    proton_reader :frames_output
+    proton_get :frames_output
 
     # @!attribute [r] frames_input
     #
     # @return [Integer] The number of frames input by a transport.
     #
-    proton_reader :frames_input
+    proton_get :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)
+      self.fetch_instance(impl, :pn_transport_attachments) || Transport.new(impl)
     end
 
     # Creates a new transport instance.
-    #
-    # @param mode [Integer] 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)
+    def initialize(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
 
+    # Set server mode for this tranport - enables protocol detection
+    # and server-side authentication for incoming connections
+    def set_server() Cproton.pn_transport_set_server(@impl); end
+
     # Returns whether the transport has any buffered data.
     #
     # @return [Boolean] True if the transport has no buffered data.
@@ -241,15 +185,15 @@ module Qpid::Proton
       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.
-    #
+    # @return [Condition, nil] transport error condition or nil if there is no error.
     def condition
-      condition_to_object Cproton.pn_transport_condition(@impl)
+      Condition.convert(Cproton.pn_transport_condition(@impl))
+    end
+
+    # Set the error condition for the transport.
+    # @param c [Condition] The condition to set
+    def condition=(c)
+      Condition.assign(Cproton.pn_transport_condition(@impl), c)
     end
 
     # Binds to the given connection.
@@ -400,7 +344,7 @@ module Qpid::Proton
     # @return [SSL] The SSL object.
     #
     def ssl(domain = nil, session_details = nil)
-      @ssl ||= SSL.create(self, domain, session_details) if @ssl.nil?
+      @ssl ||= SSL.create(self, domain, session_details)
     end
 
     # @private
@@ -408,6 +352,27 @@ module Qpid::Proton
       !@ssl.nil?
     end
 
-  end
+    # @private
+    # Options are documented {Connection#open}, keep that consistent with this
+    def apply opts
+      sasl if opts[:sasl_enabled]                                 # Explicitly enabled
+      unless opts.include?(:sasl_enabled) && !opts[:sasl_enabled] # Not explicitly disabled
+        sasl.allowed_mechs = opts[:sasl_allowed_mechs] if opts.include? :sasl_allowed_mechs
+        sasl.allow_insecure_mechs = opts[:sasl_allow_insecure_mechs] if opts.include? :sasl_allow_insecure_mechs
+      end
+      self.channel_max= opts[:max_sessions] if opts.include? :max_sessions
+      self.max_frame = opts[:max_frame_size] if opts.include? :max_frame_size
+      # NOTE: The idle_timeout option is in Numeric *seconds*, can be Integer, Float or Rational.
+      # This is consistent with idiomatic ruby.
+      # The transport #idle_timeout property is in *milliseconds* passed direct to C.
+      # Direct use of the transport is deprecated.
+      self.idle_timeout= (opts[:idle_timeout]*1000).round if opts.include? :idle_timeout
+      self.ssl(opts[:ssl_domain]) if opts[:ssl_domain]
+    end
 
+    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
+  end
 end

data/lib/core/uri.rb

@@ -0,0 +1,73 @@
+# 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.
+
+
+require 'uri'
+
+# Extend the standard ruby {URI} with AMQP and AMQPS schemes
+module URI
+  # AMQP URI scheme for the AMQP protocol
+  class AMQP < Generic
+    DEFAULT_PORT = 5672
+
+    # @return [String] The AMQP address is the {#path} stripped of any leading "/"
+    def amqp_address() path[0] == "/" ? path[1..-1] : path; end
+  end
+  @@schemes['AMQP'] = AMQP
+
+  # AMQPS URI scheme for the AMQP protocol over TLS
+  class AMQPS < AMQP
+    DEFAULT_PORT = 5671
+  end
+  @@schemes['AMQPS'] = AMQPS
+end
+
+module Qpid::Proton
+  # Returns +s+ converted to a {URI::AMQP} or {URI::AMQPS} object
+  #
+  # Shortcut strings are allowed: an "amqp://" prefix is added if +s+ does
+  # not already look like an 'amqp:', 'amqps:' URI.
+  #
+  # @note this does not give the same result as a standard URI parser in all cases.
+  #  For standard conversion to a URI use: {#URI}(s)
+  #
+  # @param s [String,URI] String to convert to a URI, or a URI object.
+  #  A URI object with no scheme will be converted to {URI::AMQP}
+  # @return [URI::AMQP] A valid {URI::AMQP} or {URI::AMQPS} object
+  # @raise [BadURIError] s is a URI object with a non-AMQP scheme
+  # @raise [InvalidURIError] s cannot be parsed as a URI or shortcut
+  # @raise [::ArgumentError] s is not a string or URI
+  #
+  def self.uri(s)
+    case s
+      when URI::AMQP then s     # Pass-thru
+    when URI::Generic
+      s.scheme ||= 'amqp'
+      u = URI.parse(s.to_s)      # Re-parse as amqp
+      raise URI::BadURIError, "Not an AMQP URI: '#{u}'" unless u.is_a? URI::AMQP
+      u
+    else
+      s = String.try_convert s
+      raise ::ArgumentError, "bad argument (expected URI object or URI string)" unless s
+      case s
+      when %r{^amqps?:} then URI.parse(s)      # Looks like an AMQP URI
+      when %r{^//} then URI.parse("amqp:#{s}") # Looks like a scheme-less URI
+      else URI.parse("amqp://#{s}")            # Treat as a bare host:port/path string
+      end
+    end
+  end
+end