email_address 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 225554c1b1abf4ead2900a7209b55ec7babeaefe
-  data.tar.gz: 4de853f82e80be5e9e6ce843a16fd2dc3f4a3255
+  metadata.gz: da957eceefc70a7dc4a21a1d1f44296e36783021
+  data.tar.gz: fffc1230d4c3080ab56229e34604838543b659e6
 SHA512:
-  metadata.gz: 11b73a88096b1553dac4aa7979a1a7385c568ae8d5c2dca268c88bf1fd2827aa77bb76e3a412a6cc85d1f5d9983f470a1a6b1840df73d428fbfdae76277bfe9a
-  data.tar.gz: 97b3f3497d00346404b94dbfde915bbbcf1dae41bcbc6d7fc98a4e0dc0072245b57597ca4939295e6db47fc2700ed935add5f8019519389950288f2501ad7bc6
+  metadata.gz: e638d9efbba9834cd1857150db91821d82e6bbbbf95ee694bc30287d5c9f69893d87928ee49b044207e9503accf4eefc354295b29e3d5ec44ad6ee5ab2918653
+  data.tar.gz: 90749c6bdbc84c2586208eefb04f8eb208812124d3253170d46471b64df4e23c5ff24bc6967c426285e8cd838f71bcd1fb3b910a7a82690ab3a91da5665e9e40

data/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in email_address.gemspec
 gemspec
+gem 'minitest'

data/README.md

@@ -1,25 +1,31 @@
-# EmailAddress
-
-The EmailAddress library is an _opinionated_ email address handler and
-validator. 
-
-So you have an email address input by a user. Do you want to validate
-it, check it for uniqueness, or mine statistics on all your addresses?
-Then the email_address gem is for you!
-
-Opininated? Yes. By default, this does not support RFC822 specification
-because it allows addresses that should never exist for real people.
-By limiting email addresses to a subset of standardly used ones, you can
-remove false positives in validation, and help the email community
-evolve into a friendlier place. I like standards as much as the next
-person, but enough is enough!
-
-Why my opinion? I've been working with email and such since the late
-1990's. I would like to see modern practices applied to email addresses.
-These rules really do apply to most (without real statistics, I'll claim
-99.9+%) usage in the 21st Century. They may not be for everyone, you may
-need strict adherence to these standards for historical reasons, but I
-bet you'll wish you could support this one instead!
+# Email Address
+
+The EmailAddress gem is an _opinionated_ email address handler and
+validator. It does not use RFC standards because they make things worse.
+Email addresses should conform to a few practices that are not
+RFC-Compliant.
+
+Specifically, local parts (left side of the @):
+
+* Should not be case sensitive.
+* Should not contain spaces or anything that would cause quoting.
+* Should not allow Unicode. Addressable items like this need to be
+entered from any keyboard, such as the US ASCII character set. (Domain
+names too, but that can be handled with Punycode.)
+* Should not have comments. Neither should domains.
+* Should not allow unusual symbols (not usually in names and standard
+punctuation).
+* Should not be verified by SMTP connections if possible.
+* Should have spaces stripped automatically if enabled
+* Should be of a reasonable length to identify the recipient.
+* Should be human readable and writable.
+* Should continue allowing for tagging.
+* Should provide mechanism for handling bounce backs and VERP.
+* Should be easily normalized and corrected.
+* Should be canonicalized to identify duplicates if necessary.
+* Should be able to be stored as a digest for privacy proctections.
+
+If you're on board, let's go!
 
 ## Installation
 
@@ -40,23 +46,84 @@ Or install it yourself as:
 Inspect your email address string by creating an instance of
 EmailAddress:
 
-    email = EmailAddress.new("user@example.com")
+    email = EmailAddress.new("USER+tag@EXAMPLE.com")
+    email.normalize     #=> "user+tag@example.com"
+    email.canonical     #=> "user@example.com"
+
+Email Service Provider (ESP) specific edits can be created to provide
+validations and canonical manipulations. A few are given out of the box.
+Providers can be defined bu email domain match rules, or by match rules
+for the MX host names using domains or CIDR addresses.
+
+    email = EmailAddress.new("First.Last+Tag@Gmail.Com")
+    email.provider      #=> :gmail
+    email.canonical     #=> "firstlast@gmail.com"
+
+Storing the canonical address with the request address (don't remove
+tags given by users), you can lookup email addresses without the
+original formatting, case, and tag information.
+
+You can inspect the MX (Mail Exchanger) records
+
+    email.host.exchanger.mxers.first
+      #=> {:host=>"alt3.gmail-smtp-in.l.google.com", :ip=>"173.194.70.27", :priority=>30}
 
 You can see if it validates as an opinionated address:
 
-    email.valid?
+    email.valid?      # Resonably valid?
+    email.valid_host? # Host name is defined in DNS
+    email.strict?     # Strictly valid?
+
+Email addresses should be able to be "archived" or stored in a digest
+format. This allows you to safely keep a record of the address and still
+protect the account's privacy after it has been closed. Given an address
+for inquiry, it can still look up a closed account.
+
+    email.md5     #=> "dea073fb289e438a6d69c5384113454c"
+    email.archive #=> "554d32017ab3a7fcf51c88ffce078689003bc521@gmail.com"
+
+
+## Email Address Parts
+
+The Local and Domain Parsing routines divvy the email address into these
+parts from `(comment)mailbox+tag@subdomain.domain.tld`
+
+* Local - Everything to the left of the "@"
+* Mailbox - The controlling mailbox name
+* Tag - Anything after the mailbox and tag separator character (usually "+")
+* Comment - To be removed from the normalized form
+* Host Name - Everything to the right of the "@"
+* Subdomains - of the host name, if any.
+* Domain Name - host name without subdomains, with TLD
+* TLD - the rightmost word or set of 2-character domains ("co.uk")
+* Registration Name - host name without subdomain or TLD
+
+## Domain Matching
+
+You can also employ domain matching rules
+
+    email.host.matches?('gmail.com', '.us', '.msn.com', 'yahoo')
+
+This tests the address can be matched in the given list of domain rules:
+
+* Full host name. (subdomain.example.com)
+* TLD and domain wildcards  (.us, .msg.com)
+* Registration names matching without the TLD. 'yahoo' matches:
+    * "www.yahoo.com" (with Subdomains)
+    * "yahoo.ca"     (any TLD)
+    * "yahoo.co.jp"  (2-char TLD with 2-char Second-level)
+    * But _may_ also match non-Yahoo domain names (yahoo.xxx)
 
-This runs the following checks you can do yourself:
+## Customizing
 
-    email.valid_format?
-    email.valid_domain?
-    email.valid_user?
-    email.disposable_email?
-    email.spam_trap?
+You can change configuration options and add new providers such as:
 
-Of course, the last couple tests can't be published, so you can provide
-a callback to check them yourself if you need.
+    EmailAddress::Config.setup do
+      provider :github, domains:%w(github.com github.io)
+      option   :check_dns, false
+    end
 
+See `lib/email_address/config.rb` for more options.
 
 ## Contributing
 

data/email_address.gemspec

@@ -21,5 +21,6 @@ validator.}
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "simpleidn"
+  spec.add_dependency "simpleidn"
+  spec.add_dependency "netaddr"
 end

data/lib/email_address.rb

@@ -1,145 +1,17 @@
-#require "email_address/version"
-#require "email_address/config"
-#require "email_address/host"
-#require "email_address/address"
-require 'simpleidn'
-
-class EmailAddress
-  attr_reader :address, :local, :account, :tag, :comment,
-    :domain, :subdomains, :domain_name, :base_domain, :top_level_domain
-
-  def initialize(email)
-    self.address = email
-  end
-
-  ##############################################################################
-  # Basic email address: local@domain
-  # Only supporting FQDN's (Fully Qualified Domain Names)?
-  # Length: Up to 254 characters
-  ##############################################################################
-  def address=(email)
-    @address = email.strip
-    (local_name, domain_name) = @address.split('@')
-    self.domain = domain_name
-    self.local  = local_name
-    @address
-  end
-
-  def to_s
-    [local, domain].join('@')
-  end
-
-  ##############################################################################
-  # Domain Parsing
-  # Parts: subdomains.basedomain.top-level-domain
-  # IPv6/IPv6: [128.0.0.1], [IPv6:2001:db8:1ff::a0b:dbd0]
-  # Comments: (comment)example.com, example.com(comment)
-  # Internationalized: Unicode to Punycode
-  # Length: up to 255 characters
-  ##############################################################################
-  def domain=(host_name)
-    host_name ||= ''
-    @domain = host_name.strip.downcase
-    parse_domain
-    @domain
-  end
-
-  def parse_domain
-    @subdomains = @base_domain = @domain_name = @top_level_domain = ''
-    # Patterns: *.com, *.xx.cc, *.cc
-    if @domain =~ /\A(.+)\.(\w{3,10})\z/ || @domain =~ /\A(.+)\.(\w{1,3}\.\w\w)\z/ || @domain =~ /\A(.+)\.(\w\w)\z/
-      @top_level_domain = $2;
-      sld = $1 # Second level domain
-      if sld =~ /\A(.+)\.(.+)\z/ # is subdomain? sub.example [.tld]
-        @subdomains  = $1
-        @base_domain = $2
-      else
-        @subdomains  = ""
-        @base_domain = sld
-      end
-      @domain_name  = @base_domain + '.' + @top_level_domain
-    end
-  end
-
-  def dns_hostname
-    @dns_hostname ||= SimpleIDN.to_ascii(domain)
-  end
-
-  ##############################################################################
-  # Parsing id provider-dependent, but RFC allows:
-  # A-Z a-z 0-9 . ! # $ % ' * + - / = ? ^ _ { | } ~
-  # Quoted: space ( ) , : ; < > @ [ ]
-  # Quoted-Backslash-Escaped: \ "
-  # Quote local part or dot-separated sub-parts x."y".z
-  # (comment)mailbox | mailbox(comment)
-  # 8-bit/UTF-8: allowed but mail-system defined
-  # RFC 5321 also warns that "a host that expects to receive mail SHOULD avoid defining mailboxes where the Local-part requires (or uses) the Quoted-string form".
-  # Postmaster: must always be case-insensitive
-  # Case: sensitive, but usually treated as equivalent
-  # Local Parts: comment, account tag
-  # Length: upt o 64 cgaracters
-  ##############################################################################
-  def local=(local)
-    local ||= ''
-    @local = local.strip.downcase
-    @account = parse_comment(@local)
-    (@account, @tag) = @account.split(tag_separator)
-    @tag ||= ''
-
-    @local
-  end
-
-  def parse_comment(local)
-    if local =~ /\A\((.+?)\)(.+)\z/
-      (@comment, local) = [$1, $2]
-    elsif @local =~ /\A(.+)\((.+?)\)\z/
-      (@comment, local) = [$1, $2]
-    else
-      @comment = '';
-    end
-    local
-  end
-
-  ##############################################################################
-  # Provider-Specific Settings
-  ##############################################################################
-
-  def provider
-   # @provider ||= EmailProviders::Default.new
-   'unknown'
-  end
-
-  def tag_separator
-   '+'
-  end
-
-  def case_sensitive_local
-   false
-  end
-
-  # Returns the unique address as simplified account@hostname
-  def unique_address
-    "#{account}@#{dns_hostname}".downcase
-  end
-
-  # Letters, numbers, period (no start) 6-30chars
-  def user_pattern
-   /\A[a-z0-9][\.a-z0-9]{0,29}\z/i
-  end
-
-  ##############################################################################
-  # Validations -- Eventually a provider-sepecific check
-  ##############################################################################
-  def valid?
-    return false unless @local =~ user_pattern
-    return false unless provider # .valid_domain
-    true
-  end
-
-  def valid_format?
-    return false unless @local.match(user_pattern)
-    return false unless @host.valid_format?
-    true
+require "email_address/address"
+require "email_address/config"
+require "email_address/domain_matcher"
+require "email_address/domain_parser"
+require "email_address/exchanger"
+require "email_address/host"
+require "email_address/local"
+require "email_address/validator"
+require "email_address/version"
+
+module EmailAddress
+
+  def self.new(address)
+    EmailAddress::Address.new(address)
   end
 
 end

data/lib/email_address/address.rb

@@ -1,4 +1,74 @@
+require 'digest/sha1'
+require 'digest/md5'
+
 module EmailAddress
   class Address
+
+    def initialize(address)
+      @address = address
+      parse
+    end
+
+    def parse
+      (_, local, host) = @address.match(/\A(.+)@(.+)/).to_a
+      @host = EmailAddress::Host.new(host)
+      @local = EmailAddress::Local.new(local, @host.provider)
+    end
+
+    def host
+      @host
+    end
+
+    def local
+      @local
+    end
+
+    def mailbox
+      @local.mailbox
+    end
+
+    def host_name
+      @host.host_name
+    end
+
+    def tag
+      @local.tag
+    end
+
+    def comment
+      @local.comment
+    end
+
+    def provider
+      @host.provider
+    end
+
+    def to_s
+      normalize
+    end
+
+    def normalize
+      [@local.normalize, @host.normalize].join('@')
+    end
+
+    def canonical
+      [@local.canonical, @host.canonical].join('@')
+    end
+
+    def md5
+      Digest::MD5.hexdigest(canonical)
+    end
+
+    def sha1
+      Digest::SHA1.hexdigest(canonical)
+    end
+
+    def archive
+      [sha1, @host.canonical].join('@')
+    end
+
+    def valid?(options={})
+      EmailAddress::Validator.validate(self, options)
+    end
   end
 end

data/lib/email_address/config.rb

@@ -1,4 +1,79 @@
 module EmailAddress
   class Config
+    @options = {
+       downcase_mailboxes: true,
+       check_dns:          true,
+    }
+
+    @providers = {
+       default: {
+         domains:           [],
+         exchangers:        [],
+         tag_separator:     '+',
+         case_sensitive:    false,
+         address_size:      3..254,
+         local_size:        1..64,
+         domain_size:       1..253,
+         mailbox_size:      1..64,
+         mailbox_unicode:   false,
+         canonical_mailbox: ->(m) {m},
+         valid_mailbox:     nil,  # :legible, :rfc, ->(m) {true}
+       },
+       aol: {
+         registration_names: %w(aol compuserve netscape aim cs)
+       },
+       google: {
+         domains:           %w(gmail.com googlemail.com),
+         exchangers:        %w(google.com),
+         local_size:        5..64,
+         canonical_mailbox: ->(m) {m.gsub('.','')},
+         #valid_mailbox:    ->(local) { local.mailbox =~ /\A[a-z0-9][\.a-z0-9]{5,29}\z/i},
+       },
+       msn: {
+         valid_mailbox:    ->(m) { m =~ /\A[a-z0-9][\.\-a-z0-9]{5,29}\z/i},
+       },
+       yahoo: {
+         domains:          %w(yahoo ymail rocketmail),
+         exchangers:       %w(yahoodns yahoo-inc),
+       },
+    }
+
+    def self.providers
+      @providers
+    end
+
+    def self.options
+      @options
+    end
+
+    def self.provider(name)
+      @providers[:default].merge(@providers.fetch(name) { Hash.new })
+    end
+
+    class Setup
+      attr_reader :providers
+
+      def initialize
+        @providers = {}
+      end
+
+      def do_block(&block)
+        instance_eval(&block)
+      end
+
+      def provider(name, defn={})
+        EmailAddress::Config.providers[name] = defn
+      end
+
+      def option(name, value)
+        EmailAddress::Config.options[name.to_sym] = value
+      end
+    end
+
+    def self.setup(&block)
+      @setup ||= Setup.new
+      @setup.do_block(&block) if block_given?
+      @setup
+    end
   end
 end