encoded_id 1.0.0.rc2 → 1.0.0.rc4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7e11278f039a19d4fa201541b907a3f52e5b73c440ba0870c6e8a4fd068bb99
-  data.tar.gz: 70d726b45f982670895c1ddccbbf7e9f42b4a6ab3e6eca8439ac5e58ce399fe0
+  metadata.gz: '0844f07baeecd48a70bf0b2564dfb9f02998b002279b44bf75bd0172ccc265be'
+  data.tar.gz: 0bcd81de8a4ea7e034097a92dff9ba82478d92f87f7820dda872a9f35b5294d3
 SHA512:
-  metadata.gz: fcfad8b207316c8041ddd6cd8687a17b9e04c5bcdca8b73084aae2e4a241c5b2c10247fe24f513e66d939ab97289bb1206458f0fab70cc6a04415224ec62083b
-  data.tar.gz: c3d4148b9ddddac5eb2dc47b58c2beb6e88e0e3be9c207328e36c825adbce05826c3eaeb6b4d2023160da65286c177e3a3085f222ba7ba7eb529dab995939cb3
+  metadata.gz: 4dcf3c99891f8a3a195d188656d1c45c9471760dfbc715fe994fac4c4145a086d9573b663c5a4a79894c71c4e3a15bf68ff0d30b20e44b8fe661c68f1707c065
+  data.tar.gz: 8edb3675d565ff7be88441fcdb2a55783415f170fcd8d9102c6bb0fff8cc6fa0d22f1af19e72dd5558dedb37ba2af23c29fd6171d12da2032a0e2ce187bedeca

data/CHANGELOG.md

@@ -1,15 +1,36 @@
 ## [Unreleased]
 
-## [1.0.0] - 2023-08-06
+## [2.0.0.alpha1] - unreleased
+
+### Breaking changes
+
+- `ReversibleId` now no longer downcases the encodedid input string by default on decode, ie the `decode` option `downcase` is now `false`. In a future release the `downcase` option will be removed.
+
+## [1.0.0.rc4] - unreleased
+
+- Add an optional `max_inputs_per_id` argument to `ReversibleId`, thanks to [@avcwisesa](https://github.com/avcwisesa)
+
+## [1.0.0.rc3] - 2023-10-23
+
+- Add an optional `max_length` argument to `ReversibleId`, thanks to [@jugglebird](https://github.com/jugglebird)
+- Alphabet validations to prevent whitespace and null chars
+- Add `Alphabet#to_a`, `Alphabet#to_s`, `Alphabet#size` and a custom `Alphabet#inspect`
+- Fixes to input validations
+- hashids are case-sensitive, as are `Alphabet`s, however `ReversibleId` was always `downcase`ing the encodedid input string on decode. A new option has been added to `decode` and `decode_hex`, `downcase`, which defaults to `true`. Thus, the default behaviour is unchanged, but you can opt out to allow mixed case encodedid decode. *Note:* In V2 this will default to `false`.
+
+## [1.0.0.rc2] - 2023-08-07
+
+- `Alphabet` now has `#include?` and `#unique_charaters` methods
+
+## [1.0.0.rc1] - 2023-08-06
 
 - Improved RBS definitions
 - Improved test coverage
-- `Alphabet` now has `#include?` and `#unique_charaters` methods
 
 ## [0.4.0] - 2022-12-04
 
-- Support custom split character which must not be in the alphabet
-- Ability to provide a custom character equivalences mapping
+- Support custom 'split' character which must not be in the alphabet
+- Ability to provide a custom character equivalence mapping
 
 ## [0.3.0] - 2022-10-12
 

data/Gemfile

@@ -7,8 +7,18 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "minitest", "~> 5.0"
+gem "minitest"
 
 gem "standard", "~> 1.30"
 
-gem "steep", "~> 1.5"
+gem "rbs"
+
+gem "steep"
+
+gem "simplecov"
+
+gem "benchmark-ips"
+
+gem "benchmark-memory"
+
+gem "fuzzbert"

data/README.md

@@ -33,16 +33,27 @@ coder.decode("z2j7-Odmw") # (note the capital 'o' instead of zero)
 
 ## Features
 
-* encoded IDs are reversible (uses with https://hashids.org))
-* supports multiple IDs encoded in one encoded string (eg `7aq6-0zqw` decodes to `[78, 45]`)
-* supports encoding of hex strings (eg UUIDs), including multiple IDs encoded in one string **(experimental)**
-* supports custom alphabets for the encoded string (at least 16 characters needed)
+* 🔄 encoded IDs are reversible (uses with https://hashids.org))
+* 👥 supports multiple IDs encoded in one encoded string (eg `7aq6-0zqw` decodes to `[78, 45]`)
+* 🔡 supports custom alphabets for the encoded string (at least 16 characters needed)
   - by default uses a variation of the Crockford reduced character set (https://www.crockford.com/base32.html)
-  - easily confused characters (eg `i` and `j`, `0` and `O`, `1` and `I` etc) are mapped to counterpart characters, to help
+  - 👓 easily confused characters (eg `i` and `j`, `0` and `O`, `1` and `I` etc) are mapped to counterpart characters, to help
       avoid common readability mistakes when reading/sharing
-  - build in profanity limitation
-* encoded string can be split into groups of letters to improve human-readability
+  - 🤬 build in profanity limitation
+* 🤓 encoded string can be split into groups of letters to improve human-readability
   - eg `nft9hr834htu` as `nft9-hr83-4htu`
+* 🥽 supports limits on length to prevent resource exhaustion on encoding and decoding
+* configured with sensible defaults
+
+I aim for 100% test coverage and have fuzz tested quite extensively. But please report any issues!
+
+### Experimental
+
+* support for encoding of hex strings (eg UUIDs), including multiple IDs encoded in one string
+
+### Coming soon
+
+Performance improvements and benchmarking!
 
 ### Rails support `encoded_id-rails`
 
@@ -117,9 +128,27 @@ The encoded ID is configurable. The following can be changed:
 
 The actual length of the encoded string can be longer if the inputs cannot be represented in the minimum length.
 
+### `max_length`
+
+`max_length`: the maximum length of the encoded string. The default is 128 characters.
+
+The maximum length represents both the longest encoded string that will be generated and also a limit on
+the maximum input length that will be decoded. If the encoded string exceeds `max_length` then a
+`EncodedIdLengthError` will be raised. If the input exceeds `max_length` then a `InvalidInputError` will
+be raised. If `max_length` is set to `nil`, then no validation, even using the default will be performed.
+
+### `max_inputs_per_id`
+
+`max_inputs_per_id`: the maximum amount of IDs to be encoded together. The default is 32.
+
+This maximum amount is used to limit:
+- the length of array input passed to `encode`
+- the length of integer array encoded in hex string(s) passed to `encode_hex` function.
+`InvalidInputError` wil be raised when array longer than `max_inputs_per_id` is provided.
+
 ### `alphabet`
 
-`alphabet`: the alphabet used in the encoded string. By default it uses a variation of the Crockford reduced character set (https://www.crockford.com/base32.html).
+`alphabet`: the alphabet used in the encoded string. By default, it uses a variation of the Crockford reduced character set (https://www.crockford.com/base32.html).
 
 `alphabet` must be an instance of `EncodedId::Alphabet`.
 
@@ -137,7 +166,8 @@ alphabet = EncodedId::Alphabet.new("0123456789abcdef")
 
 `characters`: the characters of the alphabet. Can be a string or array of strings.
 
-Note that the `characters` of the alphabet must be at least 16 _unique_ characters long.
+Note that the `characters` of the alphabet must be at least 16 _unique_ characters long and must not contain any
+whitespace characters.
 
 
 ```ruby
@@ -268,16 +298,17 @@ coder.decode_hex("5jjy-c8d9-hxp2-qsve-rgh9-rxnt-7nb5-tve7-bf84-vr")
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also 
-run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. 
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version 
-number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git 
-commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running tests
+
+Run `bundle exec rake test` to run the tests.
 
 ### Type check
 
-First install dependencies:
+First install RBS dependencies:
 
 ```bash
 rbs collection install
@@ -289,7 +320,6 @@ Then run:
 steep check
 ```
 
-
 ## See also
 
 - https://hashids.org

data/lib/encoded_id/alphabet.rb

@@ -20,8 +20,9 @@ module EncodedId
     def initialize(characters, equivalences = nil)
       raise_invalid_alphabet! unless valid_input_characters?(characters)
       @unique_characters = unique_character_alphabet(characters)
-      raise_character_set_too_small! unless sufficient_characters?(@unique_characters.size)
-      raise_invalid_equivalences! unless valid_equivalences?(equivalences, @unique_characters)
+      raise_invalid_alphabet! unless valid_characters?
+      raise_character_set_too_small! unless sufficient_characters?
+      raise_invalid_equivalences! unless valid_equivalences?(equivalences)
 
       @characters = unique_characters.join
       @equivalences = equivalences
@@ -33,29 +34,52 @@ module EncodedId
       unique_characters.include?(character)
     end
 
+    def to_a
+      unique_characters.dup
+    end
+
+    def to_s
+      @characters.dup
+    end
+
+    def inspect
+      "#<#{self.class.name} chars: #{unique_characters.inspect}>"
+    end
+
+    def size
+      unique_characters.size
+    end
+    alias_method :length, :size
+
     private
 
     def valid_input_characters?(characters)
-      (characters.is_a?(Array) || characters.is_a?(String)) && characters.size > 0
+      return false unless characters.is_a?(Array) || characters.is_a?(String)
+      characters.size > 0
     end
 
     def unique_character_alphabet(characters)
       (characters.is_a?(Array) ? characters : characters.chars).uniq
     end
 
-    def sufficient_characters?(size)
-      size >= MIN_UNIQUE_CHARACTERS
+    def valid_characters?
+      unique_characters.size > 0 && unique_characters.grep(/\s|\0/).size == 0
+    end
+
+    def sufficient_characters?
+      unique_characters.size >= MIN_UNIQUE_CHARACTERS
     end
 
-    def valid_equivalences?(equivalences, unique_characters)
+    def valid_equivalences?(equivalences)
       return true if equivalences.nil?
       return false unless equivalences.is_a?(Hash)
+      return false if equivalences.any? { |key, value| key.size != 1 || value.size != 1 }
 
       (unique_characters & equivalences.keys).empty? && (equivalences.values - unique_characters).empty?
     end
 
     def raise_invalid_alphabet!
-      raise InvalidAlphabetError, "Alphabet must be a string or array."
+      raise InvalidAlphabetError, "Alphabet must be a string or array and not contain whitespace."
     end
 
     def raise_character_set_too_small!
@@ -63,7 +87,7 @@ module EncodedId
     end
 
     def raise_invalid_equivalences!
-      raise InvalidConfigurationError, "Character equivalences must be a hash or nil."
+      raise InvalidConfigurationError, "Character equivalences must be a hash or nil and contain mappings to valid alphabet characters."
     end
   end
 end

data/lib/encoded_id/reversible_id.rb

@@ -8,20 +8,25 @@ require "hashids"
 # Note hashIds already has a built in profanity limitation algorithm
 module EncodedId
   class ReversibleId
-    def initialize(salt:, length: 8, split_at: 4, split_with: "-", alphabet: Alphabet.modified_crockford, hex_digit_encoding_group_size: 4)
+    def initialize(salt:, length: 8, split_at: 4, split_with: "-", alphabet: Alphabet.modified_crockford, hex_digit_encoding_group_size: 4, max_length: 128, max_inputs_per_id: 32)
       @alphabet = validate_alphabet(alphabet)
       @salt = validate_salt(salt)
       @length = validate_length(length)
       @split_at = validate_split_at(split_at)
       @split_with = validate_split_with(split_with, alphabet)
       @hex_represention_encoder = HexRepresentation.new(hex_digit_encoding_group_size)
+      @max_length = validate_max_length(max_length)
+      @max_inputs_per_id = validate_max_input(max_inputs_per_id)
     end
 
     # Encode the input values into a hash
     def encode(values)
       inputs = prepare_input(values)
       encoded_id = encoded_id_generator.encode(inputs)
-      encoded_id = humanize_length(encoded_id) unless split_at.nil?
+      encoded_id = humanize_length(encoded_id) unless split_with.nil? || split_at.nil?
+
+      raise EncodedIdLengthError if max_length_exceeded?(encoded_id)
+
       encoded_id
     end
 
@@ -31,15 +36,17 @@ module EncodedId
     end
 
     # Decode the hash to original array
-    def decode(str)
-      encoded_id_generator.decode(convert_to_hash(str))
+    def decode(str, downcase: true)
+      raise InvalidInputError if max_length_exceeded?(str)
+
+      encoded_id_generator.decode(convert_to_hash(str, downcase))
     rescue ::Hashids::InputError => e
       raise EncodedIdFormatError, e.message
     end
 
     # Decode hex strings from a hash
-    def decode_hex(str)
-      integers = encoded_id_generator.decode(convert_to_hash(str))
+    def decode_hex(str, downcase: true)
+      integers = encoded_id_generator.decode(convert_to_hash(str, downcase))
       hex_represention_encoder.integers_as_hex(integers)
     end
 
@@ -50,43 +57,56 @@ module EncodedId
       :alphabet,
       :split_at,
       :split_with,
-      :hex_represention_encoder
+      :hex_represention_encoder,
+      :max_length
 
     def validate_alphabet(alphabet)
-      raise InvalidAlphabetError, "alphabet must be an instance of Alphabet" unless alphabet.is_a?(Alphabet)
-      alphabet
+      return alphabet if alphabet.is_a?(Alphabet)
+      raise InvalidAlphabetError, "alphabet must be an instance of Alphabet"
     end
 
     def validate_salt(salt)
-      raise InvalidConfigurationError, "Salt must be a string and longer than 3 characters" unless salt.is_a?(String) && salt.size > 3
-      salt
+      return salt if salt.is_a?(String) && salt.size > 3
+      raise InvalidConfigurationError, "Salt must be a string and longer than 3 characters"
     end
 
     # Target length of the encoded string (the minimum but not maximum length)
     def validate_length(length)
-      raise InvalidConfigurationError, "Length must be an integer greater than 0" unless length.is_a?(Integer) && length > 0
-      length
+      return length if valid_integer_option?(length)
+      raise InvalidConfigurationError, "Length must be an integer greater than 0"
+    end
+
+    def validate_max_length(max_length)
+      return max_length if valid_integer_option?(max_length) || max_length.nil?
+      raise InvalidConfigurationError, "Max length must be an integer greater than 0"
+    end
+
+    def validate_max_input(max_inputs_per_id)
+      return max_inputs_per_id if valid_integer_option?(max_inputs_per_id)
+      raise InvalidConfigurationError, "Max inputs per ID must be an integer greater than 0"
     end
 
     # Split the encoded string into groups of this size
     def validate_split_at(split_at)
-      unless (split_at.is_a?(Integer) && split_at > 0) || split_at.nil?
-        raise InvalidConfigurationError, "Split at must be an integer greater than 0 or nil"
-      end
-      split_at
+      return split_at if valid_integer_option?(split_at) || split_at.nil?
+      raise InvalidConfigurationError, "Split at must be an integer greater than 0 or nil"
     end
 
     def validate_split_with(split_with, alphabet)
-      unless split_with.is_a?(String) && !alphabet.characters.include?(split_with)
-        raise InvalidConfigurationError, "Split with must be a string and not part of the alphabet"
-      end
-      split_with
+      return split_with if split_with.nil? || (split_with.is_a?(String) && !alphabet.characters.include?(split_with))
+      raise InvalidConfigurationError, "Split with must be a string and not part of the alphabet or nil"
+    end
+
+    def valid_integer_option?(value)
+      value.is_a?(Integer) && value > 0
     end
 
     def prepare_input(value)
       inputs = value.is_a?(Array) ? value.map(&:to_i) : [value.to_i]
       raise ::EncodedId::InvalidInputError, "Integer IDs to be encoded can only be positive" if inputs.any?(&:negative?)
 
+      raise ::EncodedId::InvalidInputError, "%d integer IDs provided, maximum amount of IDs is %d" % [inputs.length, @max_inputs_per_id] if inputs.length > @max_inputs_per_id
+
       inputs
     end
 
@@ -102,16 +122,25 @@ module EncodedId
       hash.gsub(split_regex, "\\0#{split_with}")
     end
 
-    def convert_to_hash(str)
-      clean = str.delete(split_with).downcase
-      alphabet.equivalences.nil? ? clean : map_equivalent_characters(clean)
+    def convert_to_hash(str, downcase)
+      clean = str.gsub(split_with, "")
+      clean = clean.downcase if downcase
+      map_equivalent_characters(clean)
     end
 
     def map_equivalent_characters(str)
+      return str unless alphabet.equivalences
+
       alphabet.equivalences.reduce(str) do |cleaned, ceq|
         from, to = ceq
         cleaned.tr(from, to)
       end
     end
+
+    def max_length_exceeded?(str)
+      return false if max_length.nil?
+
+      str.length > max_length
+    end
   end
 end

data/lib/encoded_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EncodedId
-  VERSION = "1.0.0.rc2"
+  VERSION = "1.0.0.rc4"
 end

data/lib/encoded_id.rb

@@ -12,5 +12,7 @@ module EncodedId
 
   class EncodedIdFormatError < ArgumentError; end
 
+  class EncodedIdLengthError < ArgumentError; end
+
   class InvalidInputError < ArgumentError; end
 end

data/sig/encoded_id.rbs

@@ -3,17 +3,18 @@ module EncodedId
 
   InvalidConfigurationError: ::StandardError
   EncodedIdFormatError: ::ArgumentError
+  EncodedIdLengthError: ::ArgumentError
   InvalidAlphabetError: ::ArgumentError
   InvalidInputError: ::ArgumentError
 
   class Alphabet
     MIN_UNIQUE_CHARACTERS: ::Integer
 
-    def initialize: (String, ?::Hash[::String, ::String]) -> void
+    def initialize: (String | ::Array[::String] characters, ::Hash[::String, ::String] ?equivalences) -> void
 
     attr_reader unique_characters: ::Array[::String]
     attr_reader characters: String
-    attr_reader equivalences: ::Hash[::String, ::String]
+    attr_reader equivalences: ::Hash[::String, ::String] | nil
 
     def include?: (::String character) -> bool
 
@@ -23,11 +24,13 @@ module EncodedId
 
     def valid_input_characters?: ((::Array[::String] | ::String) characters) -> bool
 
-    def sufficient_characters?: (::Integer size) -> bool
+    def valid_characters?: -> bool
+
+    def sufficient_characters?: -> bool
 
     def unique_character_alphabet: ((::Array[::String] | ::String) characters) -> ::Array[::String]
 
-    def valid_equivalences?: (::Hash[::String, ::String] equivalences, ::Array[::String] unique_characters) -> bool
+    def valid_equivalences?: (::Hash[::String, ::String] ?equivalences) -> bool
 
     def raise_character_set_too_small!: -> untyped
 
@@ -56,7 +59,7 @@ module EncodedId
   end
 
   class ReversibleId
-    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?split_with: ::String, ?alphabet: Alphabet, ?hex_digit_encoding_group_size: ::Integer) -> void
+    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?split_with: ::String, ?alphabet: Alphabet, ?hex_digit_encoding_group_size: ::Integer, ?max_length: ::Integer, ?max_inputs_per_id: ::Integer) -> void
 
     # Encode the input values into a hash
     def encode: (encodeableValue values) -> ::String
@@ -79,6 +82,7 @@ module EncodedId
     attr_reader salt: ::String
 
     attr_reader length: ::Integer
+    attr_reader max_length: ::Integer | nil
 
     attr_reader alphabet: Alphabet
 
@@ -90,9 +94,12 @@ module EncodedId
     def validate_alphabet: (Alphabet) -> Alphabet
     def validate_salt: (::String) -> ::String
     def validate_length: (::Integer) -> ::Integer
+    def validate_max_length: (::Integer | nil) -> (::Integer | nil)
+    def validate_max_input: (::Integer) -> ::Integer
     def validate_split_at: (::Integer | nil) -> (::Integer | nil)
     def validate_split_with: (::String, Alphabet) -> ::String
     def validate_hex_digit_encoding_group_size: (::Integer) -> ::Integer
+    def valid_integer_option?: (::Integer | nil) -> bool
 
     def prepare_input: (untyped value) -> ::Array[::Integer]
 
@@ -102,8 +109,9 @@ module EncodedId
 
     def humanize_length: (::String hash) -> ::String
 
-    def convert_to_hash: (::String str) -> ::String
+    def convert_to_hash: (::String str, bool) -> ::String
 
     def map_equivalent_characters: (::String str) -> ::String
+    def max_length_exceeded?: (::String str) -> bool
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc2
+  version: 1.0.0.rc4
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-07 00:00:00.000000000 Z
+date: 2024-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashids
@@ -67,11 +67,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: EncodedId is a gem for creating reversible obfuscated IDs from numerical