Class: RubyJID

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/ruby_jid.rb,
lib/ruby_jid/version.rb

Overview

Jabber ID or JID

See [RFC 3920 Section 3 - Addressing](xmpp.org/rfcs/rfc3920.html#addressing)

An entity is anything that can be considered a network endpoint (i.e., an ID on the network) and that can communicate using XMPP. All such entities are uniquely addressable in a form that is consistent with RFC 2396 [URI]. For historical reasons, the address of an XMPP entity is called a Jabber Identifier or JID. A valid JID contains a set of ordered elements formed of a domain identifier, node identifier, and resource identifier.

The syntax for a JID is defined below using the Augmented Backus-Naur Form as defined in [ABNF]. (The IPv4address and IPv6address rules are defined in Appendix B of [IPv6]; the allowable character sequences that conform to the node rule are defined by the Nodeprep profile of [STRINGPREP] as documented in Appendix A of this memo; the allowable character sequences that conform to the resource rule are defined by the Resourceprep profile of [STRINGPREP] as documented in Appendix B of this memo; and the sub-domain rule makes reference to the concept of an internationalized domain label as described in [IDNA].)

jid             = [ node "@" ] domain [ "/" resource ]
domain          = fqdn / address-literal
fqdn            = (sub-domain 1*("." sub-domain))
sub-domain      = (internationalized domain label)
address-literal = IPv4address / IPv6address

All JIDs are based on the foregoing structure. The most common use of this structure is to identify an instant messaging user, the server to which the user connects, and the user’s connected resource (e.g., a specific client) in the form of <user@host/resource>. However, node types other than clients are possible; for example, a specific chat room offered by a multi-user chat service could be addressed as <room@service> (where “room” is the name of the chat room and “service” is the hostname of the multi-user chat service) and a specific occupant of such a room could be addressed as <room@service/nick> (where “nick” is the occupant’s room nickname). Many other JID types are possible (e.g., <domain/resource> could be a server-side script or service).

Each allowable portion of a JID (node identifier, domain identifier, and resource identifier) MUST NOT be more than 1023 bytes in length, resulting in a maximum total size (including the ‘@’ and ‘/’ separators) of 3071 bytes.

Constant Summary collapse

PATTERN = 
/\A(?:([^@]*)@)??([^@\/]*)(?:\/(.*?))?\Z/.freeze
NODE_PREP =

tools.ietf.org/html/rfc6122#appendix-A

/[[:cntrl:] "&'\/:<>@]/.freeze
NAME_PREP =

tools.ietf.org/html/rfc3454#appendix-C

/[[:cntrl:] ]/.freeze
RESOURCE_PREP =

tools.ietf.org/html/rfc6122#appendix-B

/[[:cntrl:]]/.freeze
VERSION = 
"1.0.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(jid) ⇒ RubyJID #initialize(jid) ⇒ RubyJID #initialize(node, domain = nil, resource = nil) ⇒ RubyJID

Create a new JID object

Overloads:

  • #initialize(jid) ⇒ RubyJID

    Passes the jid object right back out

    Parameters:

  • #initialize(jid) ⇒ RubyJID

    Creates a new JID parsed out of the provided jid (“node@domain/resource”)

    Parameters:

    • jid (String) —

      a jid in the standard format

  • #initialize(node, domain = nil, resource = nil) ⇒ RubyJID

    Creates a new JID

    Parameters:

    • node (String) —

      the node of the JID

    • domian (String, nil) —

      the domain of the JID

    • resource (String, nil) (defaults to: nil) —

      the resource of the JID

Raises:

  • (ArgumentError) —

    if the parts of the JID are too large (1023 bytes)



95
96
97
98
99
100
101
102
103
104
 
# File 'lib/ruby_jid.rb', line 95

def initialize(node, domain = nil, resource = nil)
  @node, @domain, @resource = node, domain, resource

  if @domain.nil? && @resource.nil?
    @node, @domain, @resource = @node.to_s.scan(PATTERN).first
  end
  @domain.downcase! if @domain

  validate
end

Instance Attribute Details

#domain ⇒ Object (readonly)

Returns the value of attribute domain.



62
63
64
 
# File 'lib/ruby_jid.rb', line 62

def domain
  @domain
end

#node ⇒ Object (readonly)

Returns the value of attribute node.



62
63
64
 
# File 'lib/ruby_jid.rb', line 62

def node
  @node
end

#resource ⇒ Object

Returns the value of attribute resource.



62
63
64
 
# File 'lib/ruby_jid.rb', line 62

def resource
  @resource
end

Class Method Details

.new(node, domain = nil, resource = nil) ⇒ Object 



66
67
68
 
# File 'lib/ruby_jid.rb', line 66

def self.new(node, domain = nil, resource = nil)
  node.is_a?(RubyJID) ? node : super
end

.valid?(node, domain = nil, resource = nil) ⇒ Boolean

Validate a JID

Returns:

  • (Boolean) —

    true if a valid JID, otherwise false



73
74
75
76
77
 
# File 'lib/ruby_jid.rb', line 73

def self.valid?(node, domain = nil, resource = nil)
  !!new(node, domain, resource)
rescue ArgumentError
  false
end

Instance Method Details

#<=>(jid) ⇒ Object 



134
135
136
 
# File 'lib/ruby_jid.rb', line 134

def <=>(jid)
  to_s.downcase <=> jid.to_s.downcase
end

#bare ⇒ RubyJID

Strip the resource part from this JID and return it as a new JID object. The new JID contains only the optional node part and the required domain part from the original. This JID remains unchanged.

Returns:

  • (RubyJID) —

    a new JID without a resource



112
113
114
 
# File 'lib/ruby_jid.rb', line 112

def bare
  RubyJID.new @node, @domain
end

#bare? ⇒ Boolean

Return true if this is a bare JID without a resource part.

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/ruby_jid.rb', line 117

def bare?
  @resource.nil?
end

#domain? ⇒ Boolean

Return true if this is a domain-only JID without a node or resource part.

Returns:

  • (Boolean) 


122
123
124
 
# File 'lib/ruby_jid.rb', line 122

def domain?
  !empty? && to_s == @domain
end

#empty? ⇒ Boolean

Return true if this JID is equal to the empty string ”. That is, it’s missing the node, domain, and resource parts that form a valid JID. It makes for easier error handling to be able to create JID objects from strings and then check if they’re empty rather than nil.

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/ruby_jid.rb', line 130

def empty?
  to_s == ''
end

#eql?(jid) ⇒ Boolean

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/ruby_jid.rb', line 138

def eql?(jid)
  jid.is_a?(RubyJID) && self == jid
end

#hash ⇒ Object 



142
143
144
 
# File 'lib/ruby_jid.rb', line 142

def hash
  to_s.hash
end

#to_s ⇒ String

Turn the JID into a string

  • “”

  • “domain”

  • “node@domain”

  • “domain/resource”

  • “node@domain/resource”

Returns:

  • (String) —

    the JID as a string



155
156
157
158
159
160
 
# File 'lib/ruby_jid.rb', line 155

def to_s
  s = @domain
  s = "#{@node}@#{s}" if @node
  s = "#{s}/#{@resource}" if @resource
  s
end