uxid 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 329b2b3ae00dc22cfc6a32ce123ad4f22a1211cc2d1851d1797211b838b59983
-  data.tar.gz: 586e48ce10bd900cf51a1fafc363640443d2f22e6ac845ddcaac85ae810467bc
+  metadata.gz: 9ddc9c523df0274739dd977feb61799c5bccba6c0319ac9caa89a97b16d23178
+  data.tar.gz: 5f3e9b5660bf0406fe6be9882ddbf0adffa3851c4ef64304cf091df89d860893
 SHA512:
-  metadata.gz: a5516fd55ea9f94f64c4a7535b4d1bb751ba729021aad89e28a47fd23b7adb42183d2267374a28badacb0aab704fd591eb22a7d7f4ae0d3a589eb0ee04b2c384
-  data.tar.gz: a19e5b88e3e0d2b88931bfb146d2323595e848dbf4d6675726afc476c4a1a1a3810870bd1e34e7f92bbbf1b8014419bf97a7bebd5c3392f4a7f624043f56a555
+  metadata.gz: 985179a75fa0cdf3bfb8f11b7dc4307c2096fd32f19ef8b1b670c3bfc3acbf7fa429b7a47a2f42f3557733a9d6f908dea47895319ce76cdd267fc16bd6a1f248
+  data.tar.gz: 36bc846998cf71c55e698b3bad2c7df452d3257116c447eb4ad001308ec09964c23fae324aea7d9f3dfd3cf0e434d7549a10517d673432b3a88720cf7fbbbbb9

data/CHANGELOG.md

@@ -3,6 +3,36 @@
 * (Nothing yet)
 
 
+### 1.0.0 / 2026-10-19
+
+A rewrite of the gem under its existing name, and a breaking release: the
+0.2.x API is gone. The gem now implements the wire format of the Elixir
+reference implementation, [uxid-ex](https://github.com/riddler/uxid-ex), and
+passes every case of that implementation's conformance corpus at the tag
+`v2.10.0`, vendored under `conformance/` (`conformance/SOURCE.json` records the
+tag, its commit and the corpus hash). An ID written by 0.2 with a symbol size
+has the layout of the same size in 1.0 apart from its case: 0.2 wrote upper
+case and 1.0 writes lowercase by default (`case: :upper` keeps upper case), and
+`UXID.decode` reads either case. To stay on 0.2, pin `gem "uxid", "~> 0.2"`;
+the README's "Upgrading from 0.2" lists what changes for a caller.
+
+**Added**
+
+* `UXID.generate(from: "...")` builds a deterministic id: the marker `z` (`Z` in an upper-case id) and then the first bits of the SHA-256 of the prefix, the `from` string and the size, as uxid-ex's wire format defines it, so the same arguments always give the same id and it sorts after every time-based id with its prefix and case. `from` (and the prefix) are hashed as their bytes: valid text in an encoding other than UTF-8 is transcoded to UTF-8 first, and a binary String, one not valid in its own encoding, or one Ruby cannot transcode is hashed as its own bytes, so a raw-byte key such as a 16-byte UUID works. `rand:` with `from:` raises `UXID::Error` with code `:rand_with_from`; the time and random-field options do not apply to a deterministic id and are not read.
+* `UXID.decode(id, delimiter: "_", now: nil)` reads an id back as uxid-ex's wire format defines it and never raises on malformed input. A well-formed id gives a frozen `UXID::Decoded` with `prefix` (nil when there is no delimiter), `size` (`:xs` to `:xl`), `compact?`, `deterministic?` and `time` (milliseconds, nil for a deterministic id); the random field is not read back. Anything else gives a frozen `UXID::Invalid` whose `reason` is `:empty`, `:invalid_length` or `:invalid_character`, the first rule the body fails in that order, with lengths counted in bytes; a value that is not a String is `:invalid_character`. Both answer `valid?`. Body lengths 10 and 18 are read as standard xs and standard m, so a compact xs or compact m id decodes to its size but not its time. A compact time takes its high bits from `now:` (default the system clock), less 2**40 ms when that puts it more than a day ahead.
+* `UXID.valid?(id, prefix: nil, delimiter: "_")` is whether the id decodes and, when `prefix:` is given, has exactly that prefix; `UXID.deterministic?(id, delimiter: "_")` is whether it decodes to a deterministic body. Neither raises on the id.
+* `UXID::Monotonic.new(prefix: nil, size: :xl, draws: nil, **options)` is a monotonic generator, and its `#generate(time: nil, **options)` gives ids that increase strictly for each prefix and random width, within one millisecond and when the clock moves back, by the monotonic rule of uxid-ex's wire format: a later time takes a fresh random value, an equal or earlier one keeps the last time and adds a step drawn uniformly from 1 to 2**(4w), and a step that overflows the field moves to the next millisecond with a fresh value. The options are `UXID.generate`'s; those given to `new` are the defaults of every call. Size `:xs` uses compact time unless `compact_time:` is given, and a request with no random field is refused. The state belongs to the instance, guarded by a Mutex inside it, so one generator may be shared across threads; nothing is kept at class level or globally. Random values come from the byte source (default `SecureRandom`), or from `draws:`, an object answering `seed(width)` and `step(width)`, for replaying recorded draws. `from:` raises `UXID::Error` with code `:from_with_monotonic`, and `rand:` with `:rand_with_monotonic`.
+
+**Changed**
+
+* Breaking: `UXID.generate` now builds the id uxid-ex's wire format defines, from the keyword options prefix, size, rand_size, compact_time, case, delimiter and time; 0.2.x ids are not reproduced, so callers re-read the option list in the method's doc. Random bytes come from an injectable `byte_source` (default `SecureRandom.random_bytes`), and `rand:` fixes the random field for test vectors only. A refused request raises `UXID::Error`, an `ArgumentError` whose `#code` names the refusal.
+* Breaking: Ruby 3.2 or later is required, where 0.2 asked for 2.3; stay on 0.2 on an older Ruby.
+
+**Removed**
+
+* Breaking: `UXID.new`, `UXID::Model` and the 0.2 encoder class and constants are removed, and `UXID.generate` no longer takes a Hash; call `UXID.generate` with keyword options, or pin `~> 0.2`.
+
+
 ### 0.2.3 / 2020-11-29
 
 * Updates project URL

data/README.md

@@ -1,75 +1,173 @@
 # UXID
 
-![MIT License][badge_license_url]
-![Gem Version][badge_version_url]
+[![MIT License][badge_license_url]](LICENSE)
+[![CI][badge_ci_url]](https://github.com/riddler/uxid-rb/actions/workflows/ci.yml)
+[![Gem Version][badge_version_url]](https://rubygems.org/gems/uxid)
+
+User eXperience focused IDentifiers for Ruby: prefixed, K-sortable,
+Stripe-style IDs a person can read, copy and route back to their resource. An
+ID looks like `usr_01m5ahke2t2v9sczzafsbf0y2e`: the prefix names the resource,
+and the body carries a timestamp and randomness in lowercase Crockford Base32.
+The IDs are wire-compatible with the Elixir reference implementation,
+[uxid-ex](https://github.com/riddler/uxid-ex), and the gem is checked against
+that implementation's conformance corpus.
+
+## Why UXID
+
+An auto-increment key leaks how many rows a table holds and invites
+enumeration; a random UUID fixes both but is long, unordered and anonymous, so
+in a log line, a URL or a support thread nobody can tell what it points at, and
+a double-click selects only part of it. A UXID names its resource in its
+prefix, selects whole on a double-click, reads aloud without ambiguity, sorts
+by creation time so it indexes well, and is generated in the application with
+no coordination between nodes. Its size is tunable for low-cardinality
+resources, a monotonic generator keeps a burst within one millisecond unique
+and ordered, and a deterministic mode maps the same input to the same ID.
+
+## Install
+
+Add `uxid` to your Gemfile:
 
+```ruby
+gem "uxid", "~> 1.0"
+```
 
-**U**ser e**X**perience focused **ID**entifiers (UXIDs) are identifiers which:
+And then execute:
 
-* Describe the resource (aid in debugging and investigation)
-* Work well with copy and paste (double clicking selects the entire ID)
-* Can be shortened for low cardinality resources
-* Are secure against enumeration attacks
-* Can be generated by application code (not tied to the datastore)
-* Are K-sortable (lexicographically sortable by time - works well with datastore indexing)
-* Do not require any coordination (human or automated) at startup, or generation
-* Are very unlikely to collide (more likely with less randomness)
-* Are easily and accurately transmitted to another human using a telephone
+    $ bundle install
 
-Many of the concepts of Stripe IDs have been used in this library.
+Or install it yourself as:
 
-## Usage
+    $ gem install uxid
 
-#### Generating UXIDs
+## Basic usage
 
 ```ruby
-# No options generates a basic ULID
-UXID.generate # "01EMDGJF0DQXQJ8FM78XE97Y3H"
-
-# A prefix can be provided
-UXID.generate prefix: "cus" # "cus_01EMDGJF0DQXQJ8FM78XE97Y3H"
-
-# The amount of entropy can be decreased for smaller cardinality resources
-# T-Shirt sizes can be used (:xs, :s, :m, :l, :xl) or (:xsmall, :small, :medium, :large, :xlarge)
-UXID.generate prefix: "cus", size: :small # "cus_01EQRH884AQYY1"
+require "uxid"
+
+# No options generates a plain ID: a time field and a random field
+UXID.generate                                       # "01m5ahke2tebfrqcks88r0d5ta"
+
+# A prefix names the resource
+UXID.generate(prefix: "usr")                        # "usr_01m5ahke2t2v9sczzafsbf0y2e"
+
+# Shrink the random part for low-cardinality resources
+# Sizes: :xs :s :m :l :xl (or :xsmall :small :medium :large :xlarge)
+UXID.generate(prefix: "cus", size: :small)          # "cus_01m5ahke2t2e40"
+
+# Deterministic: the same input gives the same ID, with the prefix as namespace
+UXID.generate(prefix: "usr", from: "alice@example.com")
+# => "usr_zcvt7epac0t1ebcsjfyf7cwz25"
+
+# Read an ID back, or check it
+UXID.decode("usr_01hf7yat00")
+# => #<data UXID::Decoded prefix="usr", size=:xs, compact=false, deterministic=false, time=1700000000000>
+UXID.valid?("usr_01hf7yat00", prefix: "usr")        # => true
+UXID.valid?("usr_01hf7yat00", prefix: "cus")        # => false
+UXID.deterministic?("usr_zcvt7epac0t1ebcsjfyf7cwz25") # => true
+
+# Monotonic: IDs from one generator increase strictly, also within one
+# millisecond. You hold the generator; the gem keeps no global state.
+generator = UXID::Monotonic.new(prefix: "usr", size: :s)
+generator.generate                                  # "usr_01m5ahke2te6h0"
+generator.generate                                  # a larger one
 ```
 
+`UXID.decode` never raises on malformed input: it answers a `UXID::Invalid`
+whose `reason` is `:empty`, `:invalid_length` or `:invalid_character`. A request
+the wire format refuses, such as `rand_size: 11`, raises `UXID::Error`, an
+`ArgumentError` whose `code` names the refusal.
 
-## Installation
+## Upgrading from 0.2
 
-Add this line to your application's Gemfile:
+Version 1.0.0 is a different format and API under the same gem name. It is a
+breaking release, not an upgrade path for 0.2 code. To stay on 0.2, pin it:
 
 ```ruby
-gem "uxid"
+gem "uxid", "~> 0.2"
 ```
 
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install uxid
-
+To move to 1.0:
+
+- **The API is replaced.** `UXID.generate` takes keyword options (`prefix`,
+  `size`, `rand_size`, `compact_time`, `case`, `delimiter`, `time`, `rand`,
+  `byte_source`, `from`) and no longer takes a Hash. `UXID.new`, `UXID::Model`
+  and the 0.2 encoder class and constants are gone. `UXID.decode`,
+  `UXID.valid?`, `UXID.deterministic?` and `UXID::Monotonic` are new.
+- **Sizes are symbols or their names.** An Integer `size` is refused with an
+  `ArgumentError`; use `rand_size` for a specific number of random bytes, from
+  0 to 10. A String `size` such as `"small"` was read by 0.2 as the largest
+  size, with a warning; in 1.0 it means what the name says, so such a call
+  gives a shorter ID and no error.
+- **IDs are written in lowercase by default.** 0.2 wrote upper case. Pass
+  `case: :upper` to keep writing it. `UXID.decode` reads either case.
+- **Errors are `UXID::Error`.** It is an `ArgumentError`, where 0.2's was a
+  `StandardError`, and its `code` names the refusal.
+- **Ruby 3.2 or later** is required, where 0.2 asked for 2.3.
+- **Stored IDs.** An ID written by 0.2 with a symbol size has the layout of the
+  same size in 1.0, apart from its case, and `UXID.decode` reads it. Compare IDs
+  in one case, or normalize them, if you mix the two.
+
+## Compatibility
+
+Ruby 3.2 or later (`required_ruby_version` in the gemspec). CI runs the test
+suite on every Ruby minor from 3.2 up to the version `mise.toml` pins, and the
+full quality gate on that pinned version. There are no runtime dependencies;
+random bytes come from `SecureRandom` unless you give a `byte_source`. One
+`UXID::Monotonic` instance may be shared across threads: its state is guarded
+by a Mutex inside the instance, and nothing is kept at class level or globally.
+IDs from different generators carry no order between them.
+
+## Documentation
+
+- Look up
+  - Every public method and class carries a YARD doc comment in `lib/`:
+    `UXID.generate`, `UXID.decode`, `UXID.valid?`, `UXID.deterministic?`,
+    `UXID::Monotonic`, `UXID::Decoded`, `UXID::Invalid` and `UXID::Error`.
+  - [UXID wire format][guide_wire_format_url]: the normative layout of an ID -
+    alphabet, bit packing, sizes, prefix grammar, deterministic and monotonic
+    bodies, and decoding - which this gem implements.
+  - [The changelog](CHANGELOG.md): what changed in each version.
+  - [The conformance corpus](conformance/README.md): the cases every
+    implementation of the wire format passes, vendored here from uxid-ex.
+- Understand
+  - [Why a UXID has a prefix, a time and randomness][guide_why_url]: what each
+    part of an ID is for, and what you trade when you tune it.
+  - [Why monotonic mode exists and what it costs][guide_monotonic_url]:
+    same-millisecond uniqueness and ordering, and the security tradeoff.
+  - [_Designing APIs for humans: object IDs_][stripe_ids_url]: the Stripe ID
+    design many of UXID's choices follow.
 
 ## 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 `mise install` for the Ruby `mise.toml` pins
+and `mise exec -- bundle install` for the development tools. Then
+`mise exec -- bundle exec rake test` runs the tests, and
+`mise exec -- bundle exec rake` runs the full gate: RuboCop, the corpus
+integrity check and the tests under a coverage minimum.
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+A release is published by CI, never from a checkout: pushing a tag `vX.Y.Z`
+that names `UXID::VERSION` runs `.github/workflows/release.yml`, which builds
+and pushes the gem to [rubygems.org](https://rubygems.org). `rake release`
+refuses to run anywhere else.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/riddler/uxid.
-
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/riddler/uxid-rb.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
 <!-- LINKS -->
-[mit_license_url]: http://opensource.org/licenses/MIT
+[guide_wire_format_url]: https://hexdocs.pm/uxid/wire-format.html
+[guide_why_url]: https://hexdocs.pm/uxid/why-prefix-time-randomness.html
+[guide_monotonic_url]: https://hexdocs.pm/uxid/monotonic.html
+[stripe_ids_url]: https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a
 
 <!-- BADGES -->
 [badge_license_url]: https://img.shields.io/badge/license-MIT-brightgreen.svg?cacheSeconds=3600?style=flat-square
+[badge_ci_url]: https://github.com/riddler/uxid-rb/actions/workflows/ci.yml/badge.svg
 [badge_version_url]: https://badge.fury.io/rb/uxid.svg

data/lib/uxid/decoded.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module UXID
+  # What UXID.decode reads from a well-formed id: its prefix, its size and
+  # time form, whether it is deterministic, and its time. The random field is
+  # not read back. A frozen value: two decodings of the same id are equal.
+  #
+  # @!attribute [r] prefix
+  #   @return [String, nil] everything before the last delimiter, nil when the
+  #     id has no delimiter; an id that starts with the delimiter (not one a
+  #     producer emits) has the empty string, which reads as no prefix
+  # @!attribute [r] size
+  #   @return [Symbol] the size the body length gives: :xs, :s, :m, :l or :xl
+  # @!attribute [r] compact
+  #   @return [Boolean] whether the body length is a compact one; see
+  #     {#compact?}
+  # @!attribute [r] deterministic
+  #   @return [Boolean] whether the body starts with the marker z or Z; see
+  #     {#deterministic?}
+  # @!attribute [r] time
+  #   @return [Integer, nil] the time in milliseconds since the Unix epoch, nil
+  #     for a deterministic body. A compact time's high bits come from the
+  #     decoder's clock (UXID.decode's :now)
+  Decoded = Data.define(:prefix, :size, :compact, :deterministic, :time) do
+    # @return [true] a decoded id is always valid; {Invalid#valid?} is false,
+    #   so a caller can branch on the result without a type check
+    def valid?
+      true
+    end
+
+    # @return [Boolean] whether the body length is a compact one
+    def compact?
+      compact
+    end
+
+    # @return [Boolean] whether the body is deterministic (no time)
+    def deterministic?
+      deterministic
+    end
+  end
+
+  # What UXID.decode answers for a string it refuses: the reason, named as
+  # the wire-format spec and its conformance corpus name it. A frozen value.
+  #
+  # @!attribute [r] reason
+  #   @return [Symbol] :empty, :invalid_length or :invalid_character
+  Invalid = Data.define(:reason) do
+    # @return [false] a refused id is never valid; {Decoded#valid?} is true
+    def valid?
+      false
+    end
+  end
+end

data/lib/uxid/decoder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module UXID
+  # Reads an id back to a Decoded, or refuses it with an Invalid. Internal:
+  # the public entry point is UXID.decode, which documents the reading.
+  module Decoder
+    # Body length in bytes to the size and whether the time is compact. The
+    # lengths 10 and 18 are also those of compact xs and compact m; the wire
+    # format reads both as standard.
+    LENGTHS = {
+      10 => [:xs, false], 13 => [:s, true], 14 => [:s, false], 18 => [:m, false],
+      21 => [:l, true], 22 => [:l, false], 24 => [:xl, true], 26 => [:xl, false]
+    }.freeze
+
+    # Each byte of the alphabet, in either case, to its 5-bit value.
+    VALUES = (Encoder::LOWER.bytes.each_with_index.to_a + Encoder::UPPER.bytes.each_with_index.to_a).to_h.freeze
+
+    MARKERS = ["z".ord, "Z".ord].freeze
+    COMPACT_WINDOW = 2**40
+    ONE_DAY = 86_400_000
+
+    module_function
+
+    # @param id [Object] the id; anything other than a String is refused
+    # @param delimiter [String] the non-empty string between prefix and body
+    # @param now [Integer, Time, nil] the decoder's clock for a compact time
+    # @return [Decoded, Invalid]
+    def decode(id, delimiter, now)
+      check_options(delimiter, now)
+      return Invalid.new(reason: :invalid_character) unless id.is_a?(String)
+
+      prefix, body = split(id, delimiter)
+      reason = refusal(body)
+      reason ? Invalid.new(reason: reason) : decoded(prefix, body, now)
+    end
+
+    def check_options(delimiter, now)
+      unless delimiter.is_a?(String) && !delimiter.empty?
+        raise ArgumentError, "delimiter: must be a non-empty String, got: #{delimiter.inspect}"
+      end
+      return if now.nil? || now.is_a?(Integer) || now.is_a?(Time)
+
+      raise ArgumentError, "now: must be an Integer of milliseconds, a Time or nil, got: #{now.inspect}"
+    end
+
+    # The body is everything after the last delimiter and the prefix
+    # everything before it; with no delimiter the whole id is the body. The
+    # split is on bytes, so an id that is not valid in its encoding splits
+    # without raising; the prefix keeps the id's encoding.
+    def split(id, delimiter)
+      bytes = id.b
+      at = bytes.rindex(delimiter.b)
+      return [nil, bytes] if at.nil?
+
+      prefix = bytes.byteslice(0, at).force_encoding(id.encoding).freeze
+      [prefix, bytes.byteslice(at + delimiter.bytesize, bytes.bytesize)]
+    end
+
+    # The first rule the body fails, in the spec's order, or nil when it is
+    # well formed. Lengths are in bytes.
+    def refusal(body)
+      return :empty if body.empty?
+      return :invalid_length unless LENGTHS.key?(body.bytesize)
+
+      :invalid_character unless body.each_byte.all? { |byte| VALUES.key?(byte) }
+    end
+
+    def decoded(prefix, body, now)
+      size, compact = LENGTHS.fetch(body.bytesize)
+      deterministic = MARKERS.include?(body.getbyte(0))
+      time =
+        if deterministic then nil
+        elsif compact then compact_time(value(body, 8), now)
+        else standard_time(body)
+        end
+      Decoded.new(prefix: prefix, size: size, compact: compact, deterministic: deterministic, time: time)
+    end
+
+    # The first 10 characters, the first holding the time's top 3 bits; the
+    # first character's higher bits are not read.
+    def standard_time(body)
+      ((VALUES.fetch(body.getbyte(0)) & 7) << 45) | value(body.byteslice(1, 9), 9)
+    end
+
+    # The low 40 bits from the id and the rest from the clock; a result more
+    # than a day ahead of the clock is from the window before.
+    def compact_time(low, now)
+      clock = millis(now)
+      time = ((clock >> 40) << 40) | low
+      time - clock > ONE_DAY ? time - COMPACT_WINDOW : time
+    end
+
+    def value(body, count)
+      body.each_byte.first(count).reduce(0) { |acc, byte| (acc << 5) | VALUES.fetch(byte) }
+    end
+
+    def millis(now)
+      case now
+      when nil then Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      when Time then (now.to_r * 1000).floor
+      else now
+      end
+    end
+  end
+
+  private_constant :Decoder
+end