= ValidatesHostname

* Source: https://github.com/KimNorgaard/validates_hostname
* Bugs:   https://github.com/KimNorgaard/validates_hostname/issues

== Description

Extension to ActiveRecord::Base for validating hostnames and domain names.


== Features

* Adds validation for hostnames to ActiveModel

* Supports I18n for the error messages

== Installation

As plugin (from master)

  rails plugin install git://github.com/KimNorgaard/validates_hostname.git

As gem

  # in Gemfile
  gem 'validates_hostname', '~> 1.0'
  
  # Run bundler
  $ bundle install


== Validations performed

* maximum length of hostname is 255 characters

* maximum length of each hostname label is 63 characters

* characters allowed in hostname labels are a-z, A-Z, 0-9 and hyphen

* labels do not begin or end with a hyphen

* labels do not consist of numeric values only


== Options

* option to allow for underscores in hostname labels

* option to require that the last label is a valid TLD (ie. require that the name is a FQDN)

* option to allow numeric values in the first label of the hostname (exception: the hostname cannot consist of a single numeric label)

* option to specify a list of valid TLDs

* options to allow for wildcard hostname in first label (for use with DNS)

See also http://www.zytrax.com/books/dns/apa/names.html


== How to use

Simple usage

  class Record < ActiveRecord::Base
    validates :name, :hostname => true
  end

With options

  class Record < ActiveRecord::Base
    validates :name, :hostname => { OPTIONS }
  end


== Options and their defaults:

* :allow_underscore => false

* :require_valid_tld => false

* :valid_tlds => Array of allowed TLDs (can only be used with :require_fqdn => true)

* :allow_numeric_hostname => false


== Examples

Without options

  class Record < ActiveRecord::Base
    validates :host, :hostname => true
  end

  >> @record = Record.new :name => 'horse'
  >> @record.save
  => true

  >> @record2 = Record.new :name => '_horse'
  >> @record2.save
  => false

With :allow_underscore

  class Record < ActiveRecord::Base
    validates :name, :hostname => { :allow_underscore => true }
  end

  >> @record3 = Record.new :name => '_horse'
  >> @record3.save
  => true

With :require_valid_tld

  class Record < ActiveRecord::Base
    validates :name, :hostname => { :require_valid_tld => true }
  end

  >> @record4 = Record.new :name => 'horse'
  >> @record4.save
  => false

  >> @record5 = Record.new :name => 'horse.com'
  >> @record5.save
  => true

With :valid_tlds

  class Record < ActiveRecord::Base
    validates :name, :hostname => { :require_valid_tld, :valid_tlds => %w(com org net) }
  end

  >> @record6 = Record.new :name => 'horse.info'
  >> @record6.save
  => false

With :allow_numeric_hostname

  class Record < ActiveRecord::Base
    validates :name, :hostname => { :allow_numeric_hostname => false }
  end

  >> @record7 = Record.new :name => '123.info'
  >> @record7.save
  => false

With :allow_wildcard_hostname

  class Record < ActiveRecord::Base
    validates :name, :hostname => { :allow_wildcard_hostname => true }
  end

  >> @record8 = Record.new :name => '*.123.info'
  >> @record8.save
  => true


== Extra validators

A few extra validators are included.

=== domainname

* sets require_valid_tld       => true

* sets allow_numeric_hostname  => true

* returns error if there is only one label and this label is numeric

=== fqdn

* sets require_valid_tld       => true

=== wildcard

* sets allow_wildcard_hostname => true


== Error messages

Using the I18n system to define new defaults:

  en:
    errors:
      messages:
        invalid_label_length: "label must be between 1 and 63 characters long"
        label_begins_or_ends_with_hyphen: "label begins or ends with a hyphen"
        hostname_label_is_numeric: "unqualified hostname part cannot consist of numeric values only"
        single_numeric_hostname_label: "hostnames cannot consist of a single numeric label"
        label_contains_invalid_characters: "label contains invalid characters (valid characters: [%{valid_chars}])"
        invalid_hostname_length: "hostname must be between 1 and 255 characters long"
        tld_is_invalid: "tld of hostname is invalid"

The %{valid_chars} signifies the range of valid characters allowed in labels.

It is highly recommended you use the I18n system for error messages.


== Maintainers

*  {Kim Nørgaard}[<jasen@jasen.dk>]


== License

Copyright (c) 2009-2011 Kim Norgaard, released under the MIT license