diameter 0.1.0.pre4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e787a00dc9e59758d16cceaa42c530a14e474721
-  data.tar.gz: 0b99ff5787724bbbda608a90e0f8d249601ca63f
+  metadata.gz: 121a1f974bb560f963d47972a12d9e8ab1702b58
+  data.tar.gz: e0b7395beece98bf489951db82e5760c57827488
 SHA512:
-  metadata.gz: 1d284fd28e4511c7bf8565f987298d9be213b53f3108c39188abeaa91dc5943dbbcd6e2b00fcb1084bfac6d201725343c650a6ad908bfaaef1a9764982412de4
-  data.tar.gz: 4eed27cfbc0a60588d1c696437a3be93dd5a811ba609d4c5b48a8ae085f621076a5ccf6f973ff75cf1611d37b8994d53c233d1858fec6d680d13b7f25e77b32d
+  metadata.gz: de100f0fbb64fcf7f65caf44a0f4ba42915d69e05a5c6d574df3aa1eb398df123eb7788caf8487dcb5637d1f9ae8e42a8683149e9179584f39f7c3dade7db2a5
+  data.tar.gz: bcca6e6ece1548202843fbe343729ca652048ad98efb2a8e38834af85d75744d3a09ed18f9d3dc029bdce46cbc1c95614f9a41de49dbb78f01e639361fa60d3b

data/lib/diameter/avp.rb

@@ -51,12 +51,14 @@ module Diameter
 
     include AVPParser
 
+    # @api private
+    #
+    # Prefer {AVP.create} where possible.
     def initialize(code, options = {})
       @code = code
       @vendor_id = options[:vendor_id] || 0
       @content = options[:content] || ''
-      @mandatory = options[:mandatory]
-      @mandatory = true if @mandatory.nil?
+      @mandatory = options.fetch(:mandatory, true)
     end
 
     # Creates an AVP by name, and assigns it a value.
@@ -66,6 +68,10 @@ module Diameter
     #   that AVP - e.g. a Fixnum for an AVP defined as Unsigned32, a
     #   String for an AVP defined as OctetString, or an IPAddr for an AVP
     #   defined as IPAddress.
+    # @option opts [true, false] mandatory
+    #   Whether understanding this AVP is mandatory within this
+    #   application.
+    #
     # @return [AVP] The AVP that was created.
     def self.create(name, val, options = {})
       code, type, vendor = AVPNames.get(name)
@@ -103,22 +109,7 @@ module Diameter
         to_wire_novendor
       end
     end
-    
-    def to_wire_novendor
-      length_8, length_16 = UInt24.to_u8_and_u16(@content.length + 8)
-      avp_flags = @mandatory ? '01000000' : '00000000'
-      header = [@code, avp_flags, length_8, length_16].pack('NB8Cn')
-      header + padded_content
-    end
-
-    def to_wire_vendor
-      length_8, length_16 = UInt24.to_u8_and_u16(@content.length + 12)
-      avp_flags = @mandatory ? '11000000' : '10000000'
-      header = [@code, avp_flags, length_8, length_16, @vendor_id].pack('NB8CnN')
-      header + padded_content
-    end
 
-    
     # Guessing the type of an AVP and displaying it sensibly is complex,
     # so this is a complex method (but one that has a unity of purpose,
     # so can't easily be broken down). Disable several Rubocop
@@ -216,6 +207,8 @@ module Diameter
       grouped_value.select { |a| a.code == code }
     end
 
+    alias_method :[], :inner_avp
+    
     # Even though it is just "the raw bytes in the content",
     # octet_string is only one way of interpreting the AVP content and
     # shouldn't be treated differently to the others, so disable the
@@ -371,6 +364,20 @@ module Diameter
       end
     end
 
+    def to_wire_novendor
+      length_8, length_16 = UInt24.to_u8_and_u16(@content.length + 8)
+      avp_flags = @mandatory ? '01000000' : '00000000'
+      header = [@code, avp_flags, length_8, length_16].pack('NB8Cn')
+      header + padded_content
+    end
+
+    def to_wire_vendor
+      length_8, length_16 = UInt24.to_u8_and_u16(@content.length + 12)
+      avp_flags = @mandatory ? '11000000' : '10000000'
+      header = [@code, avp_flags, length_8, length_16, @vendor_id].pack('NB8CnN')
+      header + padded_content
+    end
+
     protected
 
     def padded_content

data/lib/diameter/message.rb

@@ -1,6 +1,7 @@
 require 'diameter/avp_parser'
 require 'diameter/u24'
 
+# The Diameter module
 module Diameter
   # A Diameter message.
   #
@@ -17,16 +18,14 @@ module Diameter
   #   The end-to-end identifier of this message.
   # @!attribute [r] request
   #   Whether this message is a request.
+  # @!attribute [r] answer
+  #   Whether this message is an answer.
   class Message
-    attr_reader :version, :command_code, :app_id, :hbh, :ete, :request
+    attr_reader :version, :command_code, :app_id, :hbh, :ete, :request, :answer
     include Internals
-    
-    # @!attribute [r] answer
-    #   Whether this message is an answer.
-    def answer
-      !@request
-    end
 
+    # Creates a new Diameter message.
+    #
     # @option opts [Fixnum] command_code
     #   The Diameter Command-Code of this messsage.
     # @option opts [Fixnum] app_id
@@ -52,6 +51,7 @@ module Diameter
       @ete = options[:ete] || Message.next_ete
 
       @request = options.fetch(:request, true)
+      @answer = !@request
       @proxyable = options.fetch(:proxyable, false)
       @retransmitted = false
       @error = false
@@ -90,8 +90,10 @@ module Diameter
     # Returns the first AVP with the given name. Only covers "top-level"
     # AVPs - it won't look inside Grouped AVPs.
     #
+    # Also available as [], e.g. message['Result-Code']
+    #
     # @param name [String] The AVP name, either one predefined in
-    #   {AVPNames::AVAILABLE_AVPS} or user-defined with {AVP.define}
+    #   {Constants::AVAILABLE_AVPS} or user-defined with {AVP.define}
     #
     # @return [AVP] if there is an AVP with that name
     # @return [nil] if there is not an AVP with that name
@@ -104,7 +106,7 @@ module Diameter
     # AVPs - it won't look inside Grouped AVPs.
     #
     # @param name [String] The AVP name, either one predefined in
-    #   {AVPNames::AVAILABLE_AVPS} or user-defined with {AVP.define}
+    #   {Constants::AVAILABLE_AVPS} or user-defined with {AVP.define}
     #
     # @return [Array<AVP>]
     def all_avps_by_name(name)
@@ -115,7 +117,10 @@ module Diameter
     alias_method :avp, :avp_by_name
     alias_method :[], :avp_by_name
     alias_method :avps, :all_avps_by_name
-    
+
+    # @private
+    # Prefer AVP.define and the by-name versions to this
+    #
     # Returns the first AVP with the given code and vendor. Only covers "top-level"
     # AVPs - it won't look inside Grouped AVPs.
     #
@@ -133,6 +138,9 @@ module Diameter
       end
     end
 
+    # @private
+    # Prefer AVP.define and the by-name versions to this
+    #
     # Returns all AVPs with the given code and vendor. Only covers "top-level"
     # AVPs - it won't look inside Grouped AVPs.
     #
@@ -154,25 +162,24 @@ module Diameter
 
     # Does this message contain a (top-level) AVP with this name?
     # @param name [String] The AVP name, either one predefined in
-    #   {AVPNames::AVAILABLE_AVPS} or user-defined with {AVP.define}
+    #   {Constants::AVAILABLE_AVPS} or user-defined with {AVP.define}
     #
     # @return [true, false]  
     def has_avp?(name)
       !!avp(name)
     end
 
-    # @api private
+    # @private
     #
-    # Adds an AVP to this message. Not recommended for normal use -
-    # all AVPs should be given to the constructor. Used to allow the
-    # stack to add appropriate Origin-Host/Origin-Realm AVPs to outbound
-    # messages.
-    # @param name [String] The AVP name, either one predefined in
-    #   {AVPNames::AVAILABLE_AVPS} or user-defined with {AVP.define}
-    # @param value [Object] The AVP value, with type dependent on the
-    #   AVP itself.
-    def add_avp(name, value)
-      @avps << AVP.create(name, value)
+    # Not recommended for normal use - all AVPs should be given to the
+    # constructor. Used to allow the stack to add appropriate
+    # Origin-Host/Origin-Realm AVPs to outbound messages.
+    #
+    # @param host [String] The Diameter Identity for the stack.
+    # @param realm [String] The Diameter realm for the stack.
+    def add_origin_host_and_realm(host, realm)
+      @avps << AVP.create("Origin-Host", host) unless has_avp? 'Origin-Host'
+      @avps << AVP.create("Origin-Realm", realm) unless has_avp? 'Origin-Realm'
     end
     
     # @!endgroup
@@ -207,6 +214,7 @@ module Diameter
       avps = Internals::AVPParser.parse_avps_int(bytes[20..-1])
       Message.new(version: version, command_code: command_code, app_id: app_id, hbh: hbh, ete: ete, request: request, proxyable: proxyable, retransmitted: false, error: false, avps: avps)
     end
+    
     # @!endgroup
 
     # Generates an answer to this request, filling in a Result-Code or

data/lib/diameter/stack.rb

@@ -9,10 +9,21 @@ require 'concurrent'
 module Diameter
   class Stack
     include Internals
-    def initialize(host, realm, opts={})
+
+    # @!group Setup methods
+
+    # Stack constructor.
+    #
+    # @note The stack does not advertise any applications to peers by
+    #  default - {#add_handler} must be called early on.
+    #
+    # @param host [String] The Diameter Identity of this stack (for
+    #  the Origin-Host AVP).
+    # @param realm [String] The Diameter realm of this stack (for
+    #  the Origin-Realm AVP).
+    def initialize(host, realm)
       @local_host = host
       @local_realm = realm
-      @local_port = opts[:port] || 3868
 
       @auth_apps = []
       @acct_apps = []
@@ -34,15 +45,43 @@ module Diameter
       Diameter.logger.log(Logger::INFO, 'Stack initialized')
     end
 
-    # @!group Setup methods
+    # Complete the stack initialization and begin reading from the TCP connections.
     def start
       @tcp_helper.start_main_loop
     end
 
-    def listen_for_tcp
-      @tcp_helper.setup_new_listen_connection("0.0.0.0", @local_port)
+    # Begins listening for inbound Diameter connections (making this a
+    # Diameter server instead of just a client).
+    #
+    # @param port [Fixnum] The TCP port to listen on (default 3868)
+    def listen_for_tcp(port=3868)
+      @tcp_helper.setup_new_listen_connection("0.0.0.0", port)
     end
 
+    # Adds a handler for a specific Diameter application.
+    #
+    # @note If you expect to only send requests for this application,
+    #  not receive them, the block can be a no-op (e.g. `{ nil }`)
+    #
+    # @param app_id [Fixnum] The Diameter application ID.
+    # @option opts [true, false] auth
+    #   Whether we should advertise support for this application in
+    #   the Auth-Application-ID AVP. Note that at least one of auth or
+    #   acct must be specified.
+    # @option opts [true, false] acct
+    #   Whether we should advertise support for this application in
+    #   the Acct-Application-ID AVP. Note that at least one of auth or
+    #   acct must be specified.
+    # @option opts [Fixnum] vendor
+    #  If we should advertise support for this application in a
+    #  Vendor-Specific-Application-Id AVP, this specifies the
+    #  associated Vendor-Id.
+    #
+    # @yield [req, cxn] Passes a Diameter message (and its originating
+    #  connection) for application-specific handling.
+    # @yieldparam [Message] req The parsed Diameter message from the peer.
+    # @yieldparam [Socket] cxn The TCP connection to the peer, to be
+    #  passed to {Stack#send_answer}.
     def add_handler(app_id, opts={}, &blk)
       vendor = opts.fetch(:vendor, 0)
       auth = opts.fetch(:auth, false)
@@ -58,6 +97,8 @@ module Diameter
 
     # @!endgroup
 
+    # This shuts the stack down, closing all TCP connections and
+    # terminating any background threads still waiting for an answer.
     def shutdown
       @tcp_helper.shutdown
       @pending_ete.each do |ete, q|
@@ -68,6 +109,12 @@ module Diameter
       @threadpool.wait_for_termination(5)
     end
 
+    # Closes the given connection, blanking out any internal data
+    # structures associated with it.
+    #
+    # Likely to be moved to the Peer object in a future release/
+    #
+    # @param connection [Socket] The connection to close.
     def close(connection)
       @tcp_helper.close(connection)
     end
@@ -78,12 +125,11 @@ module Diameter
     # network location indicated by peer_uri.
     #
     # @param peer_uri [URI] The aaa:// URI identifying the peer. Should
-    #   contain a hostname/IP; may contain a port (default 3868) and a
-    #   transport param indicating TCP or SCTP (default TCP).
+    #   contain a hostname/IP; may contain a port (default 3868).
     # @param peer_host [String] The DiameterIdentity of this peer, which
     #   will uniquely identify it in the peer table.
     # @param realm [String] The Diameter realm of this peer.
-    def connect_to_peer(peer_uri, peer_host, _realm)
+    def connect_to_peer(peer_uri, peer_host, realm)
       uri = URI(peer_uri)
       cxn = @tcp_helper.setup_new_connection(uri.host, uri.port)
       avps = [AVP.create('Origin-Host', @local_host),
@@ -102,10 +148,16 @@ module Diameter
       # Will move to :UP when the CEA is received
     end
 
+    # Sends a Diameter request. This is routed to an appropriate peer
+    # based on the Destination-Host AVP.
+    #
+    # This adds this stack's Origin-Host and Origin-Realm AVPs, if
+    # those AVPs don't already exist.
+    #
+    # @param req [Message] The request to send.
     def send_request(req)
       fail "Must pass a request" unless req.request
-      req.add_avp('Origin-Host', @local_host) unless req.has_avp? 'Origin-Host'
-      req.add_avp('Origin-Realm', @local_realm) unless req.has_avp? 'Origin-Realm'
+      req.add_origin_host_and_realm(@local_host, @local_realm) 
       peer_name = req.avp_by_name('Destination-Host').octet_string
       state = peer_state(peer_name)
       if state == :UP
@@ -125,13 +177,28 @@ module Diameter
       end
     end
 
+    # Sends a Diameter answer. This is sent over the same connection
+    # the request was received on (which needs to be passed into to
+    # this method).
+    #
+    # This adds this stack's Origin-Host and Origin-Realm AVPs, if
+    # those AVPs don't already exist.
+    #
+    # @param ans [Message] The Diameter answer
+    # @param original_cxn [Socket] The connection which the request
+    #   came in on. This will have been passed to the block registered
+    #   with {Stack#add_handler}.
     def send_answer(ans, original_cxn)
       fail "Must pass an answer" unless ans.answer
-      ans.add_avp('Origin-Host', @local_host) unless ans.has_avp? 'Origin-Host'
-      ans.add_avp('Origin-Realm', @local_realm) unless ans.has_avp? 'Origin-Realm'
+      ans.add_origin_host_and_realm(@local_host, @local_realm) 
       @tcp_helper.send(ans.to_wire, original_cxn)
     end
 
+    # Retrieves the current state of a peer, defaulting to :CLOSED if
+    # the peer does not exist.
+    #
+    # @param id [String] The Diameter identity of the peer.
+    # @return [Keyword] The state of the peer (:UP, :WAITING or :CLOSED).
     def peer_state(id)
       if !@peer_table.key? id
         :CLOSED
@@ -143,6 +210,9 @@ module Diameter
     # @!endgroup
     
     # @private
+    # Handles a Diameter request straight from a network connection.
+    # Intended to be called by TCPStackHelper after it retrieves a
+    # message, not directly by users.
     def handle_message(msg_bytes, cxn)
       # Common processing - ensure that this message has come in on this
       # peer's expected connection, and update the last time we saw

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: diameter
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre4
+  version: 0.1.0
 platform: ruby
 authors:
 - Rob Day
@@ -126,9 +126,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.3
@@ -136,3 +136,4 @@ signing_key:
 specification_version: 4
 summary: Pure-Ruby Diameter stack
 test_files: []
+has_rdoc: