domainic-type 0.1.0.alpha.3.0.2 → 0.1.0.alpha.3.1.0

data/lib/domainic/type/types/network/hostname_type.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/string_behavior/matching_behavior'
+require 'domainic/type/behavior/sizable_behavior'
+require 'domainic/type/behavior/uri_behavior'
+
+module Domainic
+  module Type
+    # A type for validating hostnames according to RFC 1034 and RFC 1123 standards
+    #
+    # This type provides comprehensive hostname validation, ensuring that values conform to
+    # DNS standards for hostnames. It supports constraints on the domain structure, such as
+    # top-level domain validation and hostname pattern matching.
+    #
+    # Key features:
+    # - RFC-compliant hostname validation
+    # - Maximum length enforcement (253 characters)
+    # - ASCII character set requirement
+    # - Validation of allowed or disallowed hostnames and TLDs
+    #
+    # @example Basic usage
+    #   type = HostNameType.new
+    #   type.validate("example.com") # => true
+    #   type.validate("invalid_host") # => false
+    #
+    # @example With domain constraints
+    #   type = HostNameType.new
+    #     .having_top_level_domain("com", "org")
+    #
+    # @example With hostname inclusion/exclusion
+    #   type = HostNameType.new
+    #     .having_hostname("example.com")
+    #     .not_having_hostname("forbidden.com")
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class HostnameType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::StringBehavior::MatchingBehavior
+      include Behavior::SizableBehavior
+      include Behavior::URIBehavior
+
+      RFC_HOSTNAME_REGEXP = /\A
+        [a-zA-Z0-9]                                   # Start with an alphanumeric character
+        (?:                                           # Begin optional group for the rest of the segment
+          [a-zA-Z0-9-]{0,61}                          # Allow up to 61 characters (letters, digits, hyphens)
+          [a-zA-Z0-9]                                 # End segment with an alphanumeric character
+        )?                                            # The group is optional
+        (?:                                           # Begin optional group for additional domain segments
+          \.                                          # Segment must start with a dot
+          [a-zA-Z0-9]                                 # Alphanumeric character at the start of the new segment
+          (?:                                         # Optional group for segment body
+            [a-zA-Z0-9-]{0,61}                        # Allow up to 61 characters (letters, digits, hyphens)
+            [a-zA-Z0-9]                               # End segment with an alphanumeric character
+          )?                                          # End optional segment body
+        )*                                            # Allow zero or more additional segments
+      \z/x #: Regexp
+
+      # Core hostname constraints based on RFC standards
+      intrinsically_constrain :self, :type, String, description: :not_described
+      intrinsically_constrain :self, :match_pattern, RFC_HOSTNAME_REGEXP, description: :not_described
+      intrinsically_constrain :length, :range, { maximum: 253 }, description: :not_described, concerning: :size
+      intrinsically_constrain :self, :character_set, :ascii, description: :not_described
+
+      # Constrain hostname to allowed hostnames
+      #
+      # Creates a constraint ensuring the hostname matches one of the specified hostnames.
+      # This is useful for restricting to specific domains.
+      #
+      # @example
+      #   type.having_hostname("example.com", "company.com")
+      #   type.validate("example.com") # => true
+      #   type.validate("other.com")   # => false
+      #
+      # @param hostnames [Array<String>] List of allowed hostnames
+      # @return [self] self for method chaining
+      # @rbs (*String hostnames) -> self
+      def matching(*hostnames)
+        pattern = /\A(?:#{hostnames.map { |h| Regexp.escape(h) }.join('|')})\z/i
+        constrain :self, :match_pattern, pattern, concerning: :inclusion
+      end
+      alias allowing matching
+
+      # Constrain hostname to exclude specific hostnames
+      #
+      # Ensures the hostname does not match any of the specified hostnames. Useful for blacklisting.
+      #
+      # @example
+      #   type.not_having_hostname("forbidden.com")
+      #   type.validate("allowed.com") # => true
+      #   type.validate("forbidden.com") # => false
+      #
+      # @param hostnames [Array<String>] List of forbidden hostnames
+      # @return [self] self for method chaining
+      # @rbs (*String hostnames) -> self
+      def not_matching(*hostnames)
+        pattern = /\A(?:#{hostnames.map { |h| Regexp.escape(h) }.join('|')})\z/i
+        hostname_pattern = @constraints.prepare :self, :match_pattern, pattern
+        constrain :self, :not, hostname_pattern, concerning: :hostname_exclusion
+      end
+      alias forbidding not_matching
+    end
+  end
+end

data/lib/domainic/type/types/network/uri_type.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/string_behavior/matching_behavior'
+require 'domainic/type/behavior/sizable_behavior'
+require 'domainic/type/behavior/uri_behavior'
+require 'domainic/type/types/network/hostname_type'
+require 'uri'
+
+module Domainic
+  module Type
+    # A type for validating URIs according to RFC 3986 standards
+    #
+    # This type provides comprehensive URI validation, ensuring that values conform to
+    # standard URI syntax. It supports constraints on components like the scheme, hostname,
+    # path, and query string.
+    #
+    # Key features:
+    # - RFC-compliant URI validation
+    # - Scheme, hostname, path, and query validation
+    # - Maximum length enforcement
+    # - ASCII character set requirement
+    #
+    # @example Basic usage
+    #   type = UriType.new
+    #   type.validate("https://example.com/path?query=1") # => true
+    #   type.validate("not-a-uri") # => false
+    #
+    # @example With scheme constraints
+    #   type = UriType.new
+    #     .having_scheme("http", "https")
+    #
+    # @example With hostname and path constraints
+    #   type = UriType.new
+    #     .having_hostname("example.com")
+    #     .matching_path(/^\/[a-z]+$/)
+    #
+    # @example With maximum length
+    #   type = UriType.new
+    #     .having_maximum_size(2000)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class URIType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::StringBehavior::MatchingBehavior
+      include Behavior::SizableBehavior
+      include Behavior::URIBehavior
+
+      URI_REGEXP = /\A#{URI::DEFAULT_PARSER.make_regexp}\z/ #: Regexp
+
+      # Core URI constraints based on RFC standards
+      intrinsically_constrain :self, :type, String, description: :not_described
+      intrinsically_constrain :self, :match_pattern, URI_REGEXP, description: :not_described
+      intrinsically_constrain :self, :character_set, :ascii, description: :not_described
+
+      # Constrain URI hostname to allowed values
+      #
+      # Uses `HostnameType` to validate the hostname part of the URI.
+      #
+      # @example
+      #   type.having_hostname("example.com")
+      #   type.validate("https://example.com")  # => true
+      #   type.validate("https://other.com")    # => false
+      #
+      # @param hostnames [Array<String>] List of allowed hostnames
+      # @return [self] self for method chaining
+      # @rbs (*String hostnames) -> self
+      def having_hostname(*hostnames)
+        hostname_type = HostnameType.new(matching: hostnames)
+        constrain :self, :type, hostname_type,
+                  coerce_with: lambda { |value|
+                    begin
+                      URI.parse(value).host
+                    rescue StandardError
+                      nil
+                    end
+                  }, concerning: :hostname_inclusion
+      end
+      alias allowing_hostname having_hostname
+      alias host having_hostname
+      alias hostname having_hostname
+      alias with_hostname having_hostname
+
+      # Constrain URI path to match any of the specified patterns
+      #
+      # Ensures that the path part of the URI matches at least one of the given patterns.
+      #
+      # @example
+      #   type.having_path(/^\/[a-z]+$/, /^\/api\/v\d+/)
+      #   type.validate("https://example.com/path") # => true
+      #   type.validate("https://example.com/api/v1") # => true
+      #   type.validate("https://example.com/123")  # => false
+      #
+      # @param patterns [Array<Regexp>] Patterns the path must match
+      # @return [self] self for method chaining
+      # @rbs (*String | Regexp patterns) -> self
+      def having_path(*patterns)
+        patterns = patterns.map { |p| p.is_a?(String) ? Regexp.new(p) : p }
+        combined_pattern = Regexp.union(patterns)
+        constrain :self, :match_pattern, combined_pattern,
+                  coerce_with: lambda { |value|
+                    begin
+                      URI.parse(value).path
+                    rescue StandardError
+                      nil
+                    end
+                  }, concerning: :path_inclusion
+      end
+      alias allowing_path having_path
+      alias with_path having_path
+
+      # Constrain URI scheme to specific values
+      #
+      # Ensures that the scheme part of the URI matches one of the specified schemes.
+      #
+      # @example
+      #   type.having_scheme("http", "https")
+      #   type.validate("https://example.com") # => true
+      #   type.validate("ftp://example.com")   # => false
+      #
+      # @param schemes [Array<String>] List of allowed schemes
+      # @return [self] self for method chaining
+      # @rbs (*String schemes) -> self
+      def having_scheme(*schemes)
+        included_schemes = schemes.map { |scheme| @constraints.prepare :self, :inclusion, scheme.downcase }
+        constrain :self, :or, included_schemes,
+                  coerce_with: lambda { |value|
+                    begin
+                      URI.parse(value).scheme&.downcase
+                    rescue URI::InvalidURIError
+                      nil
+                    end
+                  }, concerning: :scheme_inclusion
+      end
+      alias allowing_scheme having_scheme
+      alias scheme having_scheme
+
+      # Constrain URI hostname to exclude specific values
+      #
+      # Uses `HostnameType` to blacklist hostnames.
+      #
+      # @example
+      #   type.not_having_hostname("forbidden.com")
+      #   type.validate("https://allowed.com")   # => true
+      #   type.validate("https://forbidden.com") # => false
+      #
+      # @param hostnames [Array<String>] List of forbidden hostnames
+      # @return [self] self for method chaining
+      # @rbs (*String hostnames) -> self
+      def not_having_hostname(*hostnames)
+        hostname_type = HostnameType.new(not_matching: hostnames)
+        constrain :self, :type, hostname_type,
+                  coerce_with: lambda { |value|
+                    begin
+                      URI.parse(value).host
+                    rescue StandardError
+                      nil
+                    end
+                  }, concerning: :hostname_exclusion
+      end
+      alias forbidding_hostname not_having_hostname
+      alias not_host not_having_hostname
+      alias not_hostname not_having_hostname
+
+      # Constrain URI path to exclude any of the specified patterns
+      #
+      # Ensures that the path part of the URI does not match any of the given patterns.
+      #
+      # @example
+      #   type.not_having_path(/^\/admin/, /^\/private/)
+      #   type.validate("https://example.com/user") # => true
+      #   type.validate("https://example.com/admin") # => false
+      #   type.validate("https://example.com/private") # => false
+      #
+      # @param patterns [Array<Regexp>] Patterns the path must not match
+      # @return [self] self for method chaining
+      # @rbs (*String | Regexp patterns) -> self
+      def not_having_path(*patterns)
+        patterns = patterns.map { |p| p.is_a?(String) ? Regexp.new(p) : p }
+        combined_pattern = Regexp.union(patterns)
+        path_pattern = @constraints.prepare :self, :match_pattern, combined_pattern,
+                                            coerce_with: lambda { |value|
+                                              begin
+                                                URI.parse(value).path
+                                              rescue StandardError
+                                                nil
+                                              end
+                                            }
+        constrain :self, :not, path_pattern, concerning: :path_exclusion
+      end
+      alias forbidding_path not_having_path
+      alias not_allowing_path not_having_path
+
+      # Constrain URI scheme to exclude specific values
+      #
+      # Ensures that the scheme part of the URI does not match the specified schemes.
+      #
+      # @example
+      #   type.not_having_scheme("ftp")
+      #   type.validate("https://example.com") # => true
+      #   type.validate("ftp://example.com")   # => false
+      #
+      # @param schemes [Array<String>] List of forbidden schemes
+      # @return [self] self for method chaining
+      # @rbs (*String schemes) -> self
+      def not_having_scheme(*schemes)
+        included_schemes = schemes.map { |scheme| @constraints.prepare :self, :inclusion, scheme.downcase }
+        constrain :self, :nor, included_schemes,
+                  coerce_with: lambda { |value|
+                    begin
+                      URI.parse(value).scheme&.downcase
+                    rescue URI::InvalidURIError
+                      nil
+                    end
+                  }, concerning: :scheme_inclusion
+      end
+      alias forbidding_scheme not_having_scheme
+      alias not_allowing_scheme not_having_scheme
+    end
+  end
+end

data/sig/domainic/type/behavior/string_behavior/matching_behavior.rbs

@@ -0,0 +1,84 @@
+module Domainic
+  module Type
+    module Behavior
+      module StringBehavior
+        # A module providing string matching constraint methods
+        #
+        # This module extends types with methods for constraining string values based on
+        # equality, pattern matching, and substring inclusion/exclusion. It provides a
+        # fluent interface for building complex string matching constraints.
+        #
+        # @example Basic equality constraints
+        #   type = StringType.new
+        #     .being_equal_to("expected")
+        #     .not_being_equal_to("forbidden")
+        #
+        # @example Pattern matching constraints
+        #   type = StringType.new
+        #     .matching(/^\w+$/, /[0-9]/)
+        #     .not_matching(/admin/i)
+        #
+        # @example Substring constraints
+        #   type = StringType.new
+        #     .containing("allowed", "required")
+        #     .excluding("forbidden", "blocked")
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.1.0
+        module MatchingBehavior
+          # Constrain string to equal a specific value
+          #
+          # @param literal [String, Symbol] the value to match against
+          # @return [Behavior] self for method chaining
+          def being_equal_to: (String | Symbol literal) -> Behavior
+
+          alias eql being_equal_to
+
+          alias equal_to being_equal_to
+
+          alias equaling being_equal_to
+
+          # Constrain string to contain specific substrings
+          #
+          # @param literals [Array<String, Symbol>] the required substrings
+          # @return [Behavior] self for method chaining
+          def containing: (*String | Symbol literals) -> Behavior
+
+          alias including containing
+
+          # Constrain string to exclude specific substrings
+          #
+          # @param literals [Array<String, Symbol>] the forbidden substrings
+          # @return [Behavior] self for method chaining
+          def excluding: (*String | Symbol literals) -> Behavior
+
+          alias omitting excluding
+
+          # Constrain string to match specific patterns
+          #
+          # @param patterns [Array<String, Regexp>] the required patterns
+          # @return [Behavior] self for method chaining
+          def matching: (*String | Regexp patterns) -> Behavior
+
+          # Constrain string to not equal a specific value
+          #
+          # @param literal [String, Symbol] the forbidden value
+          # @return [Behavior] self for method chaining
+          def not_being_equal_to: (String | Symbol literal) -> Behavior
+
+          alias not_eql not_being_equal_to
+
+          alias not_equal_to not_being_equal_to
+
+          alias not_equaling not_being_equal_to
+
+          # Constrain string to not match specific patterns
+          #
+          # @param patterns [Array<String, Regexp>] the forbidden patterns
+          # @return [Behavior] self for method chaining
+          def not_matching: (*String | Regexp patterns) -> Behavior
+        end
+      end
+    end
+  end
+end

data/sig/domainic/type/behavior/string_behavior.rbs

@@ -50,6 +50,8 @@ module Domainic
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       module StringBehavior
+        include MatchingBehavior
+
         include SizableBehavior
 
         # Validate string contains only alphanumeric characters.
@@ -90,23 +92,6 @@ module Domainic
 
         alias empty being_empty
 
-        # Validate string equals a specific value.
-        #
-        # @example
-        #   type.being_equal_to("hello")
-        #   type.validate("hello")  # => true
-        #   type.validate("world")  # => false
-        #
-        # @param literal [String, Symbol] the value to compare against
-        # @return [Behavior] self for method chaining
-        def being_equal_to: (String | Symbol literal) -> Behavior
-
-        alias eql being_equal_to
-
-        alias equal_to being_equal_to
-
-        alias equaling being_equal_to
-
         # Validate string is lowercase.
         #
         # @example
@@ -235,43 +220,6 @@ module Domainic
 
         alias uppercase being_uppercase
 
-        # Validate string contains all specified substrings.
-        #
-        # @example
-        #   type.containing("hello", "world")
-        #   type.validate("hello world")  # => true
-        #   type.validate("hello")        # => false
-        #
-        # @param literals [Array<String, Symbol>] the substrings to look for
-        # @return [Behavior] self for method chaining
-        def containing: (*String | Symbol literals) -> Behavior
-
-        alias including containing
-
-        # Validate string does not contain any specified substrings.
-        #
-        # @example
-        #   type.excluding("foo", "bar")
-        #   type.validate("hello world")  # => true
-        #   type.validate("foo bar")      # => false
-        #
-        # @param literals [Array<String, Symbol>] the substrings to exclude
-        # @return [Behavior] self for method chaining
-        def excluding: (*String | Symbol literals) -> Behavior
-
-        alias omitting excluding
-
-        # Validate string matches all specified patterns.
-        #
-        # @example
-        #   type.matching(/^\w+$/, /\d/)
-        #   type.validate("hello123")  # => true
-        #   type.validate("hello")     # => false
-        #
-        # @param patterns [Array<String, Regexp>] the patterns to match against
-        # @return [Behavior] self for method chaining
-        def matching: (*String | Regexp patterns) -> Behavior
-
         # Validate string is not empty.
         #
         # @example
@@ -281,34 +229,6 @@ module Domainic
         #
         # @return [Behavior] self for method chaining
         def not_being_empty: () -> Behavior
-
-        # Validate string does not equal a specific value.
-        #
-        # @example
-        #   type.not_being_equal_to("admin")
-        #   type.validate("user")   # => true
-        #   type.validate("admin")  # => false
-        #
-        # @param literal [String, Symbol] the value to compare against
-        # @return [Behavior] self for method chaining
-        def not_being_equal_to: (String | Symbol literal) -> Behavior
-
-        alias not_eql not_being_equal_to
-
-        alias not_equal_to not_being_equal_to
-
-        alias not_equaling not_being_equal_to
-
-        # Validate string does not match any specified patterns.
-        #
-        # @example
-        #   type.not_matching(/\d/, /[A-Z]/)
-        #   type.validate("hello")     # => true
-        #   type.validate("Hello123")  # => false
-        #
-        # @param patterns [Array<String, Regexp>] the patterns to avoid matching
-        # @return [Behavior] self for method chaining
-        def not_matching: (*String | Regexp patterns) -> Behavior
       end
     end
   end

data/sig/domainic/type/behavior/uri_behavior.rbs

@@ -0,0 +1,95 @@
+module Domainic
+  module Type
+    module Behavior
+      # A module providing URI-based validation behaviors for types.
+      #
+      # This module extends the base Type::Behavior with methods designed for validating URI-related constraints.
+      # It focuses on ensuring URIs conform to specific rules, such as restricting or excluding particular
+      # top-level domains (TLDs). These features are useful for scenarios like domain-specific validations
+      # or blocking specific domain extensions.
+      #
+      # Key features:
+      # - Top-level domain inclusion constraints
+      # - Top-level domain exclusion constraints
+      # - Flexible and customizable pattern matching
+      # - Consistent interface for defining URI-related constraints
+      #
+      # @example Basic usage
+      #   class MyType
+      #     include Domainic::Type::Behavior::URIBehavior
+      #
+      #     def initialize
+      #       super
+      #       having_top_level_domain("com", "org")      # Allow only .com and .org
+      #       not_having_top_level_domain("test", "dev") # Exclude .test and .dev
+      #     end
+      #   end
+      #
+      # @example Method aliases
+      #   type.having_top_level_domain("com")      # Allow only .com
+      #   type.tld("com")                          # Same as above
+      #   type.with_tld("com")                     # Same as above
+      #
+      #   type.not_having_top_level_domain("test") # Exclude .test
+      #   type.not_tld("test")                     # Same as above
+      #   type.not_top_level_domain("test")        # Same as above
+      #
+      # This module provides a consistent interface for working with URIs, ensuring flexibility and
+      # extensibility for domain and TLD validation tasks.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module URIBehavior
+        # Constrain URIBehavior to allowed top-level domains
+        #
+        # Creates a constraint ensuring the URIBehavior uses one of the specified top-level
+        # domains (TLDs). This allows restricting emails to specific TLDs like .com or .org.
+        #
+        # @example
+        #   type.having_top_level_domain("com", "org")
+        #   type.validate("example.com")  # => true
+        #   type.validate("example.net")  # => false
+        #
+        # @param top_level_domains [Array<String>] List of allowed TLDs
+        # @return [self] self for method chaining
+        def having_top_level_domain: (*String top_level_domains) -> Behavior
+
+        alias allowing_tld having_top_level_domain
+
+        alias allowing_top_level_domain having_top_level_domain
+
+        alias having_tld having_top_level_domain
+
+        alias tld having_top_level_domain
+
+        alias with_tld having_top_level_domain
+
+        alias with_top_level_domain having_top_level_domain
+
+        # Constrain URIBehavior to exclude specific top-level domains
+        #
+        # Creates a constraint ensuring the email does not use any of the specified
+        # top-level domains (TLDs). Useful for blocking certain TLDs.
+        #
+        # @example
+        #   type.not_having_top_level_domain("test")
+        #   type.validate("example.com")   # => true
+        #   type.validate("example.test")  # => false
+        #
+        # @param top_level_domains [Array<String>] List of forbidden TLDs
+        # @return [self] self for method chaining
+        def not_having_top_level_domain: (*String top_level_domains) -> Behavior
+
+        alias forbidding_tld not_having_top_level_domain
+
+        alias forbidding_top_level_domain not_having_top_level_domain
+
+        alias not_having_tld not_having_top_level_domain
+
+        alias not_tld not_having_top_level_domain
+
+        alias not_top_level_domain not_having_top_level_domain
+      end
+    end
+  end
+end

data/sig/domainic/type/behavior.rbs

@@ -87,6 +87,8 @@ module Domainic
         #
         # @see Constraint::Set#add
         #
+        # @deprecated Use {#intrinsically_constrain} instead
+        #
         # @return [void]
         def intrinsic: (Type::accessor accessor, String | Symbol constraint_type, ?untyped expectation, **untyped options) -> void
 
@@ -95,6 +97,13 @@ module Domainic
         # @return [Constraint::Set] The constraint set
         def intrinsic_constraints: () -> Constraint::Set
 
+        # Add an intrinsic constraint to this type.
+        #
+        # @see Constraint::Set#add
+        #
+        # @return [void]
+        def intrinsically_constrain: (Type::accessor accessor, String | Symbol constraint_type, ?untyped expectation, **untyped options) -> void
+
         # Delegate unknown methods to a new instance.
         #
         # @return [Object] The result of calling the method on a new instance