uxid 0.2.3 → 1.0.0

data/lib/uxid/encoder.rb

@@ -1,180 +1,111 @@
-module UXID
-  class Encoder
-    def self.encode model
-      new(model).encode
-    end
-
-    def initialize model
-      @model = model
-    end
+# frozen_string_literal: true
 
-    def encode
-      @model.time_encoded = encode_time
-      @model.entropy_encoded = public_send "encode_entropy_#{@model.rand_size}"
+require "digest"
+require "securerandom"
 
-      @model.encoded
+module UXID
+  # Builds a time body and its id from resolved options. Internal: the public
+  # entry point is UXID.generate, which documents every option.
+  module Encoder
+    LOWER = "0123456789abcdefghjkmnpqrstvwxyz"
+    UPPER = LOWER.upcase.freeze
+
+    COMPACT_BITS = 40
+    COMPACT_MASK = (2**COMPACT_BITS) - 1
+    MARKER = 31
+
+    module_function
+
+    # @param request [Options::Resolved, Options::Deterministic]
+    # @return [String] the id
+    def generate(request)
+      body = request.is_a?(Options::Deterministic) ? deterministic_body(request) : body(request)
+      prefix = request.prefix
+      prefix.nil? || prefix.empty? ? body : "#{prefix}#{request.delimiter}#{body}"
     end
 
-    def encode_entropy_0; ""; end
-
-    def encode_entropy_1
-      b0, _b1 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)]
+    # The marker, then the first count x 5 bits of the SHA-256 of
+    # prefix || 0x00 || from || 0x00 || count, as count characters. The
+    # prefix and count are in the hash so that the same string under another
+    # prefix or at another size gives an unrelated body; case is not.
+    def deterministic_body(request)
+      alphabet = request.upper ? UPPER : LOWER
+      alphabet[MARKER] + encode_groups(hash_bits(request), request.count, alphabet)
     end
 
-    def encode_entropy_2
-      b0, b1 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)]
+    # The digest's first count x 5 bits, as an Integer.
+    def hash_bits(request)
+      input = [hashed_bytes(request.prefix.to_s), hashed_bytes(request.from), request.count]
+      digest = Digest::SHA256.digest(input.pack("a*xa*xC"))
+      digest.unpack1("H*").to_i(16) >> ((digest.bytesize * 8) - (request.count * 5))
     end
 
-    def encode_entropy_3
-      b0, b1, b2 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1)]
+    def body(request)
+      alphabet = request.upper ? UPPER : LOWER
+      bytes = request.rand.nil? ? draw(request.byte_source, request.width) : fixed(request.rand, request.width)
+      encode_time(request.millis, request.compact_time, alphabet) + encode_rand(bytes, alphabet)
     end
 
-    def encode_entropy_4
-      b0, b1, b2, b3 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)]
-    end
+    def draw(byte_source, width)
+      bytes = byte_source.nil? ? SecureRandom.random_bytes(width) : byte_source.call(width)
+      return bytes.b if bytes.is_a?(String) && bytes.bytesize == width
 
-    def encode_entropy_5
-      b0, b1, b2, b3, b4 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)  | ((b4&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b4&31]
+      raise ArgumentError, "byte_source: must return a String of #{width} bytes, got: #{bytes.inspect}"
     end
 
-    def encode_entropy_6
-      b0, b1, b2, b3, b4, b5 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)  | ((b4&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b4&31] +
-      UXID::CROCKFORD_ENCODING[(b5&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b5&7)<<2)]
-    end
+    def fixed(rand, width)
+      return rand.b if rand.bytesize == width
 
-    def encode_entropy_7
-      b0, b1, b2, b3, b4, b5, b6 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)  | ((b4&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b4&31] +
-      UXID::CROCKFORD_ENCODING[(b5&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b5&7)<<2)  | ((b6&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b6&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b6&1)<<4)]
+      raise Error.new(:rand_width_mismatch,
+                      "rand: must be exactly #{width} bytes for this call (the random field's width), " \
+                      "got: #{rand.bytesize}")
     end
 
-    def encode_entropy_8
-      b0, b1, b2, b3, b4, b5, b6, b7 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)  | ((b4&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b4&31] +
-      UXID::CROCKFORD_ENCODING[(b5&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b5&7)<<2)  | ((b6&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b6&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b6&1)<<4)  | ((b7&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b7&15)<<1)]
+    # The bytes hashed for a string. Valid text in an encoding other than
+    # UTF-8 is transcoded to UTF-8 first, so the same text gives the same
+    # bytes whatever its encoding. A binary (ASCII-8BIT) string, a string
+    # that is not valid in its own encoding, and one Ruby cannot transcode
+    # are hashed as their own bytes, as the wire format's "the input
+    # string's bytes" reads.
+    def hashed_bytes(string)
+      # A UTF-8 string, invalid or not, is returned unchanged; binary bytes
+      # above 0x7f, invalid bytes in another encoding and an encoding with
+      # no converter raise, and the string's own bytes are hashed.
+      string.encode(Encoding::UTF_8).b
+    rescue EncodingError
+      string.b
     end
 
-    def encode_entropy_9
-      b0, b1, b2, b3, b4, b5, b6, b7, b8 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)  | ((b4&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b4&31] +
-      UXID::CROCKFORD_ENCODING[(b5&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b5&7)<<2)  | ((b6&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b6&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b6&1)<<4)  | ((b7&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b7&15)<<1) | ((b8&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b8&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b8&3)<<3)]
+    # Standard time: 48 bits in 10 characters, the first holding 3 bits.
+    # Compact time: the low 40 bits in 8 characters.
+    def encode_time(millis, compact_time, alphabet)
+      return encode_groups(millis, 10, alphabet) unless compact_time
+
+      compact = millis & COMPACT_MASK
+      if compact >> (COMPACT_BITS - 5) == MARKER
+        raise Error.new(:compact_time_out_of_range,
+                        "compact_time: cannot encode #{millis}: its first character would be the " \
+                        "deterministic marker; use standard time")
+      end
+      encode_groups(compact, 8, alphabet)
     end
 
-    def encode_entropy_10
-      b0, b1, b2, b3, b4, b5, b6, b7, b8, b9 = @model.entropy_bytes
-
-      UXID::CROCKFORD_ENCODING[(b0&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b0&7)<<2)  | ((b1&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b1&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b1&1)<<4)  | ((b2&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b2&15)<<1) | ((b3&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b3&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b3&3)<<3)  | ((b4&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b4&31] +
-      UXID::CROCKFORD_ENCODING[(b5&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b5&7)<<2)  | ((b6&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b6&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b6&1)<<4)  | ((b7&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b7&15)<<1) | ((b8&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b8&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b8&3)<<3)  | ((b9&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b9&31]
+    # The random field, most significant bit first in 5-bit groups; the short
+    # group is the last one and is written as its raw value, never padded.
+    def encode_rand(bytes, alphabet)
+      bits = bytes.bytesize * 8
+      value = bytes.empty? ? 0 : bytes.unpack1("H*").to_i(16)
+      short = bits % 5
+      encoded = encode_groups(value >> short, bits / 5, alphabet)
+      short.zero? ? encoded : encoded << alphabet[value & ((1 << short) - 1)]
     end
 
-    def encode_time
-      # Get the 5 bytes of the 48bit time
-      b0, b1, b2, b3, b4, b5 = @model.time_bytes
-
-      # Split these 5 bytes up into 10 characters using the encoding
-      # and join them together as a string
-      UXID::CROCKFORD_ENCODING[(b0&224)>>5] +
-      UXID::CROCKFORD_ENCODING[b0&31] +
-      UXID::CROCKFORD_ENCODING[(b1&248)>>3] +
-      UXID::CROCKFORD_ENCODING[((b1&7)<<2)  | ((b2&192)>>6)] +
-      UXID::CROCKFORD_ENCODING[(b2&62)>>1] +
-      UXID::CROCKFORD_ENCODING[((b2&1)<<4)  | ((b3&240)>>4)] +
-      UXID::CROCKFORD_ENCODING[((b3&15)<<1) | ((b4&128)>>7)] +
-      UXID::CROCKFORD_ENCODING[(b4&124)>>2] +
-      UXID::CROCKFORD_ENCODING[((b4&3)<<3)  | ((b5&224)>>5)] +
-      UXID::CROCKFORD_ENCODING[b5&31]
+    def encode_groups(value, count, alphabet)
+      (count - 1).downto(0).each_with_object(String.new(capacity: count, encoding: Encoding::UTF_8)) do |index, out|
+        out << alphabet[(value >> (5 * index)) & 31]
+      end
     end
   end
+
+  private_constant :Encoder
 end

data/lib/uxid/error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module UXID
+  # A generation request the wire format refuses: options that contradict each
+  # other or the format. {#code} names the refusal with the name the wire-format
+  # spec and its conformance corpus give it; the message is for people and may
+  # change.
+  #
+  # It is an ArgumentError, so a caller that rescues ArgumentError also catches
+  # the options UXID.generate refuses for other reasons (an unknown size, a
+  # time out of range), which carry no code.
+  #
+  # @example
+  #   begin
+  #     UXID.generate(prefix: "usr", rand_size: 11)
+  #   rescue UXID::Error => e
+  #     e.code # => :rand_size_too_large
+  #   end
+  class Error < ArgumentError
+    # The refusal's name, one of :compact_time_out_of_range,
+    # :rand_width_mismatch, :rand_size_too_large, :rand_with_from,
+    # :from_with_monotonic and :rand_with_monotonic (the last two from
+    # UXID::Monotonic).
+    #
+    # @return [Symbol]
+    attr_reader :code
+
+    # @param code [Symbol] the refusal's name
+    # @param message [String] a description for people
+    def initialize(code, message)
+      @code = code
+      super(message)
+    end
+  end
+end

data/lib/uxid/monotonic.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module UXID
+  # A monotonic generator: ids from one generator, for one prefix and random
+  # width, increase strictly, also within one millisecond and when the clock
+  # moves back. It follows the "Monotonic generation" rule of uxid-ex's
+  # wire-format spec. A monotonic id is an ordinary time-based id of its size;
+  # nothing in it says how it was made, and UXID.decode reads it as any other.
+  #
+  # The generator keeps, for each prefix and random width it has generated
+  # for, the last time T and the last random value R (the random field read
+  # as one big-endian unsigned integer of w bytes). For a call at the current
+  # time:
+  #
+  # 1. with no state for its prefix and width, or a time later than T, the
+  #    random field is a fresh random value (a seed) and the id carries the
+  #    current time;
+  # 2. with a time equal to or earlier than T, the id carries T and R + step,
+  #    the step drawn uniformly from 1 to 2**(4w);
+  # 3. when R + step is 2**(8w) or more, the id carries T + 1 and a fresh
+  #    seed instead.
+  #
+  # The step is not a plus-one counter: it spreads consecutive ids over a
+  # window of 2**(4w) values, which stops trivial enumeration but is not
+  # unpredictability. Low-entropy sizes stay low-entropy.
+  #
+  # The state belongs to the instance: two generators never share it, and
+  # nothing is kept at class level or globally. A Mutex inside the instance
+  # guards it, so one generator may be shared across threads and its ids
+  # still increase strictly for each prefix and width. Ids from different
+  # generators (one per thread, say) carry no such order between them.
+  #
+  # @example
+  #   generator = UXID::Monotonic.new(prefix: "usr", size: :s)
+  #   generator.generate(time: 1_700_000_000_000)  # => "usr_01hf7yat00...."
+  #   generator.generate(time: 1_700_000_000_000)  # => a larger "usr_01hf7yat00...."
+  #   generator.generate(prefix: "cus")            # => "cus_01..." (its own state)
+  class Monotonic
+    # The options of UXID.generate a monotonic generator takes. time is given
+    # per call; from and rand are refused.
+    STREAM_OPTIONS = %i[prefix size rand_size compact_time case delimiter byte_source].freeze
+    private_constant :STREAM_OPTIONS
+
+    # The sizes whose standard time leaves no random field: compact time is
+    # their default here, so there is a field to step.
+    XS_NAMES = %w[xs xsmall].freeze
+    private_constant :XS_NAMES
+
+    State = Data.define(:millis, :value)
+    private_constant :State
+
+    # Makes a generator. Every option is one of UXID.generate's, with its
+    # meaning and its default there, and is the default of every call to
+    # {#generate}, which may give any of them again.
+    #
+    # One default differs: size :xs (or :xsmall) uses compact time unless
+    # :compact_time is given, because a standard xs has no random field to
+    # step. {#generate} refuses an xs with compact_time: false, and any other
+    # request whose random width is 0.
+    #
+    # @param prefix [String, nil] (nil) the prefix; nil and "" are both no
+    #   prefix and share their state
+    # @param size [Symbol, String] (:xl) the size, as UXID.generate takes it
+    # @param draws [#seed, #step, nil] (nil) where the random values come
+    #   from: any object whose seed(width) returns an Integer from 0 to
+    #   2**(8 * width) - 1, the fresh value of a width-byte field, and whose
+    #   step(width) returns an Integer from 1 to 2**(4 * width), drawn
+    #   uniformly. For replaying recorded draws, such as the conformance
+    #   corpus's, never as a source of randomness. A value outside its range
+    #   raises ArgumentError and the state is left as it was. nil draws from
+    #   the byte source: a seed is width bytes read big-endian, a step is the
+    #   low 4 * width bits of ceil(4 * width / 8) bytes plus 1, so neither is
+    #   biased. When draws is given the byte source is not called
+    # @param options [Hash] the other options of UXID.generate except :time:
+    #   :rand_size, :compact_time, :case, :delimiter and :byte_source
+    # @raise [UXID::Error] :from_with_monotonic for a :from, and
+    #   :rand_with_monotonic for a :rand, that is not nil: a monotonic
+    #   generator makes neither a deterministic id nor one with a fixed random
+    #   field
+    # @raise [ArgumentError] for an unknown option, an option UXID.generate
+    #   refuses, or a draws that does not respond to seed and step
+    def initialize(prefix: nil, size: :xl, draws: nil, **options)
+      refuse_body_sources(options)
+      unless draws.nil? || (draws.respond_to?(:seed) && draws.respond_to?(:step))
+        raise ArgumentError, "draws: must respond to seed(width) and step(width), or be nil, got: #{draws.inspect}"
+      end
+
+      @options = { prefix: prefix, size: size }.merge(options)
+      check_keys(@options)
+      Options.resolve(apply_xs_default(@options).merge(time: 0))
+      @draws = draws
+      @states = {}
+      @mutex = Mutex.new
+    end
+
+    # Generates the next id: its time and random field follow the monotonic
+    # rule above for the call's prefix and random width. Safe to call from
+    # several threads at once on one generator.
+    #
+    # @param time [Integer, Time, nil] (nil) the current time, as UXID.generate
+    #   takes it; nil reads the system clock. The id carries an earlier or
+    #   later time when the rule says so
+    # @param options [Hash] any option {#initialize} takes except :draws, in
+    #   place of the generator's own for this call
+    # @return [String] the id
+    # @raise [UXID::Error] :from_with_monotonic and :rand_with_monotonic as
+    #   for {#initialize}; :compact_time_out_of_range as for UXID.generate,
+    #   for the time the id would carry
+    # @raise [ArgumentError] for an option UXID.generate refuses, a request
+    #   with no random field, a draw outside its range, or a step that would
+    #   carry the time past 2**48 - 1. A call that raises leaves the state as
+    #   it was
+    #
+    # @example
+    #   generator = UXID::Monotonic.new(prefix: "usr")
+    #   generator.generate                            # the system clock
+    #   generator.generate(time: 1_700_000_000_000)   # a fixed time
+    #   generator.generate(prefix: "cus", size: :m)   # another prefix and size
+    def generate(time: nil, **options)
+      refuse_body_sources(options)
+      check_keys(options)
+      request = Options.resolve(apply_xs_default(@options.merge(options)).merge(time: time))
+      width = request.width
+      raise ArgumentError, "a monotonic id needs a random field, but this request's random width is 0" if width.zero?
+
+      @mutex.synchronize { next_id(request, width) }
+    end
+
+    private
+
+    def refuse_body_sources(options)
+      unless options[:from].nil?
+        raise Error.new(:from_with_monotonic,
+                        "from: cannot be used with monotonic generation: a deterministic id has no time or " \
+                        "random field to order")
+      end
+      return if options[:rand].nil?
+
+      raise Error.new(:rand_with_monotonic,
+                      "rand: cannot be used with monotonic generation: the generator fills the random field")
+    end
+
+    def check_keys(options)
+      unknown = options.keys - STREAM_OPTIONS - %i[from rand]
+      return if unknown.empty?
+
+      raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
+    end
+
+    # Compact time for xs unless the caller set compact_time; nil from and
+    # rand are dropped, as UXID.generate drops them.
+    def apply_xs_default(options)
+      options = options.except(:from, :rand)
+      return options if options.key?(:compact_time) || !XS_NAMES.include?(options[:size].to_s)
+
+      options.merge(compact_time: true)
+    end
+
+    # Runs under the mutex. The state is written only once the id is built,
+    # so a call that raises leaves it as it was.
+    def next_id(request, width)
+      key = [request.prefix.to_s, width]
+      state = advance(@states[key], request.millis, width, request.byte_source)
+      unless state.millis <= Options::TIME_MAX
+        raise ArgumentError, "time: a step past #{Options::TIME_MAX} ms would carry the id beyond the largest time"
+      end
+
+      id = Encoder.generate(request.with(millis: state.millis, rand: bytes(state.value, width)))
+      @states[key] = state
+      id
+    end
+
+    def advance(last, millis, width, byte_source)
+      return State.new(millis: millis, value: seed(width, byte_source)) if last.nil? || millis > last.millis
+
+      value = last.value + step(width, byte_source)
+      return State.new(millis: last.millis, value: value) if value < (1 << (8 * width))
+
+      State.new(millis: last.millis + 1, value: seed(width, byte_source))
+    end
+
+    def seed(width, byte_source)
+      value = @draws.nil? ? integer(Encoder.draw(byte_source, width)) : @draws.seed(width)
+      checked(value, 0, (1 << (8 * width)) - 1, "seed")
+    end
+
+    def step(width, byte_source)
+      bits = 4 * width
+      value =
+        if @draws.nil?
+          (integer(Encoder.draw(byte_source, (bits + 7) / 8)) & ((1 << bits) - 1)) + 1
+        else
+          @draws.step(width)
+        end
+      checked(value, 1, 1 << bits, "step")
+    end
+
+    # The value as width bytes, big-endian.
+    def bytes(value, width)
+      [value.to_s(16).rjust(width * 2, "0")].pack("H*")
+    end
+
+    def integer(bytes)
+      bytes.unpack1("H*").to_i(16)
+    end
+
+    def checked(value, low, high, name)
+      return value if value.is_a?(Integer) && value.between?(low, high)
+
+      raise ArgumentError, "draws: #{name} must be an Integer from #{low} to #{high}, got: #{value.inspect}"
+    end
+  end
+end

data/lib/uxid/options.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module UXID
+  # Checks UXID.generate's options and resolves them to what the encoder
+  # needs. Internal: UXID.generate documents every option.
+  module Options
+    DEFAULTS = {
+      prefix: nil, size: :xl, rand_size: nil, compact_time: false, case: :lower,
+      delimiter: "_", time: nil, rand: nil, byte_source: nil, from: nil
+    }.freeze
+
+    SIZES = {
+      xs: :xs, xsmall: :xs, s: :s, small: :s, m: :m, medium: :m,
+      l: :l, large: :l, xl: :xl, xlarge: :xl
+    }.freeze
+
+    # Random field bytes per size, standard time then compact time.
+    RAND_BYTES = {
+      xs: [0, 1], s: [2, 3], m: [5, 6], l: [7, 8], xl: [10, 10]
+    }.freeze
+
+    # Hash characters per size in a deterministic body, which is the marker
+    # and then these characters.
+    HASH_CHARS = { xs: 9, s: 13, m: 17, l: 21, xl: 25 }.freeze
+
+    MAX_RAND_BYTES = 10
+    TIME_MAX = (2**48) - 1
+
+    # What the encoder reads: the checked options, the time in milliseconds
+    # and the random field's width in bytes.
+    Resolved = Data.define(:prefix, :delimiter, :upper, :compact_time, :millis, :width, :rand, :byte_source)
+
+    # What the encoder reads for a deterministic body: the checked options
+    # and the number of hash characters.
+    Deterministic = Data.define(:prefix, :delimiter, :upper, :from, :count)
+
+    module_function
+
+    # @return [Resolved, Deterministic]
+    def resolve(options)
+      check_keys(options)
+      options = DEFAULTS.merge(options)
+      check_types(options)
+      options[:from].nil? ? time_based(options) : deterministic(options)
+    end
+
+    def time_based(options)
+      Resolved.new(
+        prefix: options[:prefix], delimiter: options[:delimiter], upper: upper?(options[:case]),
+        compact_time: options[:compact_time], millis: millis_for(options[:time]), width: width(options),
+        rand: options[:rand], byte_source: options[:byte_source]
+      )
+    end
+
+    # A deterministic body has no time field and no random field, so the
+    # options that shape those (time, compact_time, rand_size, byte_source)
+    # are not read; a fixed random field contradicts it and is refused.
+    def deterministic(options)
+      unless options[:rand].nil?
+        raise Error.new(:rand_with_from,
+                        "rand: and from: cannot be given together: a deterministic body has no random field")
+      end
+
+      Deterministic.new(
+        prefix: options[:prefix], delimiter: options[:delimiter], upper: upper?(options[:case]),
+        from: options[:from], count: HASH_CHARS.fetch(size_for(options[:size]))
+      )
+    end
+
+    def width(options)
+      width_for(size_for(options[:size]), options[:compact_time], options[:rand_size])
+    end
+
+    def check_keys(options)
+      unknown = options.keys - DEFAULTS.keys
+      return if unknown.empty?
+
+      raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
+    end
+
+    def check_types(options)
+      check(options, :prefix, "a String or nil") { |value| value.nil? || value.is_a?(String) }
+      check(options, :delimiter, "a non-empty String") { |value| value.is_a?(String) && !value.empty? }
+      check(options, :compact_time, "true or false") { |value| [true, false].include?(value) }
+      check_body_sources(options)
+    end
+
+    # The options a body's bytes come from: a fixed random field, the string
+    # a deterministic body hashes, and the byte source.
+    def check_body_sources(options)
+      check(options, :rand, "a String of bytes or nil") { |value| value.nil? || value.is_a?(String) }
+      check(options, :from, "a String or nil") { |value| value.nil? || value.is_a?(String) }
+      check(options, :byte_source, "an object responding to call(count), or nil") do |value|
+        value.nil? || value.respond_to?(:call)
+      end
+    end
+
+    def check(options, key, expected)
+      return if yield(options[key])
+
+      raise ArgumentError, "#{key}: must be #{expected}, got: #{options[key].inspect}"
+    end
+
+    def upper?(letter_case)
+      case letter_case.to_s
+      when "lower" then false
+      when "upper" then true
+      else raise ArgumentError, "case: must be :lower or :upper, got: #{letter_case.inspect}"
+      end
+    end
+
+    def size_for(size)
+      SIZES.fetch(size.to_s.to_sym) do
+        raise ArgumentError, "size: must be one of #{SIZES.keys.join(", ")}, got: #{size.inspect}"
+      end
+    end
+
+    def millis_for(time)
+      millis =
+        case time
+        when nil then Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+        when Time then (time.to_r * 1000).floor
+        when Integer then time
+        else raise ArgumentError, "time: must be an Integer of milliseconds or a Time, got: #{time.inspect}"
+        end
+      return millis if millis.between?(0, TIME_MAX)
+
+      raise ArgumentError, "time: must be from 0 to 2**48 - 1 milliseconds, got: #{millis}"
+    end
+
+    def width_for(size, compact_time, rand_size)
+      return RAND_BYTES.fetch(size)[compact_time ? 1 : 0] if rand_size.nil?
+
+      unless rand_size.is_a?(Integer) && rand_size >= 0
+        raise ArgumentError, "rand_size: must be a non-negative Integer, got: #{rand_size.inspect}"
+      end
+      return rand_size if rand_size <= MAX_RAND_BYTES
+
+      raise Error.new(:rand_size_too_large, "rand_size: must be at most #{MAX_RAND_BYTES} bytes, got: #{rand_size}")
+    end
+  end
+
+  private_constant :Options
+end

data/lib/uxid/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module UXID
-  VERSION = "0.2.3"
+  # The gem's version.
+  VERSION = "1.0.0"
 end