snowflaked 0.2.0-x86_64-darwin → 0.3.0-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 944c1a6b4119bd0a93ac54833b6eab9431fbff59f3602075c05f04dde4eed40e
-  data.tar.gz: 7c888994a394606e54e8bcfa6e1afa52b2325fa65c9621e8121526db6b8a84bd
+  metadata.gz: c4b472c55a93ad9d23408576c10f5efe71fab97e18d4687115aa0b589a11c207
+  data.tar.gz: b9845f8ad1c9d2fd6641b5af6b224d844065c6c653dc1e77bfbc2eadafe994c6
 SHA512:
-  metadata.gz: cf7ced846e10af83611a03dbc024de8b283d63504bb933e9e9f8e5790ebd46412cfbdabd6cebe99bb637ff6455a9f576c710e4cc0e10761c545ba8045b826698
-  data.tar.gz: faecae93cf76baa9f4429cc05a1241ec2e9687a78736c5367bde745042ed01d8ee4d25c8e3b42f83f209cba0c6f8809999504e9fccfb958758ae35e91ddc8649
+  metadata.gz: 549aef8a88663ba9838becf340936c7b43f1711f5e4bbf66d3b4c314f995cbd9aa942978c0423fcae0ed780239cf9e769f656ebda97b1d2f5fa48077d82a5aa5
+  data.tar.gz: 9a1fd304cafdc6913a513a38770fbc31b9a0146b62b7dcb4b8c1f24d249098bc1a090aad2026e1f5d2ac2203d94ae82c2bea3960e21d45a8ef8b1c1a991f5a89

data/README.md

@@ -83,14 +83,16 @@ end
 ```ruby
 Snowflaked.configure do |config|
   config.machine_id = 42
-  config.epoch = Time.utc(1989, 1, 3) # When not configured, the epoch is set to the Unix epoch (January 1, 1970)
+  config.epoch = Time.utc(1989, 1, 3) # Defaults to DEFAULT_EPOCH (2024-01-01) if not configured
 end
 ```
 
+Configuration is locked after `Snowflaked.configure` or the first generated/parsed ID. Set it during application boot, before request threads start.
+
 ### Machine ID
 
 > [!TIP]
-> For multi-process servers like Puma, it is recommended to **not** configure `machine_id` explicitly. The gem automatically calculates a unique machine ID using `(hostname.hash ^ pid) % 1024`, which ensures each forked worker process gets a different ID and avoids duplicate Snowflake IDs.
+> For multi-process servers like Puma, it is recommended to **not** configure `machine_id` explicitly. The gem automatically calculates a process-local machine ID using `(hostname.hash ^ pid) % 1024`, so forked workers do not reuse the parent's cached machine ID.
 
 If you must set `machine_id` explicitly, use environment variables that differ per worker process.
 
@@ -102,14 +104,12 @@ If `machine_id` is not explicitly configured, it resolves in this order:
 2. `MACHINE_ID` environment variable
 3. Auto-detected using the following formula: `(hostname.hash ^ pid) % 1024`
 
-For Kubernetes deployments, you can set the machine ID using an environment variable:
+For Kubernetes deployments, set the machine ID to a numeric value between `0` and `1023`:
 
 ```yaml
 env:
   - name: SNOWFLAKED_MACHINE_ID
-    valueFrom:
-      fieldRef:
-        fieldPath: metadata.name
+    value: "42"
 ```
 
 Or use a StatefulSet ordinal for guaranteed unique values:
@@ -151,9 +151,8 @@ tl;dr: Snowflake IDs have a negligible performance impact compared to database-b
 
 ## Requirements
 
-- Ruby >= 3.2
-- rustc >= 1.81.0
-- cargo >= 1.81.0
+- Ruby >= 3.3
+- rustc / cargo >= 1.81.0 (development uses the toolchain pinned in `mise.toml`)
 - Mise
 
 ## Development

data/lib/snowflaked/model_extensions.rb

@@ -20,10 +20,14 @@ module Snowflaked
       def _snowflake_columns_from_comments
         return @_snowflake_columns_from_comments if defined?(@_snowflake_columns_from_comments)
 
-        @_snowflake_columns_from_comments = table_exists? ? columns.filter_map { |col| col.name.to_sym if col.comment == Snowflaked::SchemaDefinitions::COMMENT } : []
+        return [] unless table_exists?
+
+        @_snowflake_columns_from_comments = columns.filter_map { |col| col.name.to_sym if col.comment == Snowflaked::SchemaDefinitions::COMMENT }
       end
 
       def _snowflake_attributes_with_columns
+        return _snowflake_attributes unless table_exists?
+
         @_snowflake_attributes_with_columns ||= (_snowflake_attributes | _snowflake_columns_from_comments)
       end
     end

data/lib/snowflaked/railtie.rb

@@ -42,10 +42,9 @@ module Snowflaked
     end
 
     initializer "snowflaked.model_extensions", after: "active_record.initialize_database" do
-      ActiveSupport.on_load(:active_record) do
-        require "snowflaked/model_extensions"
-        ActiveRecord::Base.include(Snowflaked::ModelExtensions)
-      end
+      require "snowflaked/model_extensions"
+
+      ActiveSupport.on_load(:active_record) { include Snowflaked::ModelExtensions }
     end
   end
 end

data/lib/snowflaked/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Snowflaked
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/snowflaked.rb

@@ -16,40 +16,81 @@ require_relative "snowflaked/railtie" if defined?(Rails::Railtie)
 
 module Snowflaked
   MAX_MACHINE_ID = 1023
+  DEFAULT_EPOCH = Time.utc(2024, 1, 1).freeze
 
   class Error < StandardError; end
   class ConfigurationError < Error; end
 
   class Configuration
-    attr_accessor :machine_id, :epoch
+    attr_reader :machine_id, :epoch
 
     def initialize
       @machine_id = nil
-      @epoch      = nil
+      @epoch      = DEFAULT_EPOCH
+      @sealed     = false
+    end
+
+    def machine_id=(value)
+      raise_if_sealed!(:machine_id)
+
+      @machine_id           = value.nil? ? nil : checked_machine_id(value)
+      @machine_id_value     = nil
+      @machine_id_value_pid = nil
+    end
+
+    def epoch=(value)
+      raise_if_sealed!(:epoch)
+
+      @epoch    = value
+      @epoch_ms = nil
+    end
+
+    def seal!
+      @sealed = true
     end
 
     def machine_id_value
-      (@machine_id || default_machine_id) % (MAX_MACHINE_ID + 1)
+      if @machine_id_value_pid != Process.pid
+        @machine_id_value     = resolve_machine_id
+        @machine_id_value_pid = Process.pid
+      end
+
+      @machine_id_value
     end
 
     def epoch_ms
       return nil unless @epoch
 
-      (@epoch.to_f * 1000).to_i
+      @epoch_ms ||= (@epoch.to_r * 1000).to_i
     end
 
     private
 
-    def default_machine_id
-      env_machine_id || hostname_pid_hash
+    # Resolution order: explicit config, then env vars, then an auto fallback.
+    # Explicit and env values are range-checked; the fallback is always valid.
+    def resolve_machine_id
+      return @machine_id unless @machine_id.nil?
+
+      env = ENV["SNOWFLAKED_MACHINE_ID"] || ENV.fetch("MACHINE_ID", nil)
+      return checked_machine_id(env) if env
+
+      # Unique-enough per process without coordination: varies by host and by
+      # pid, so forked workers each get a different id. % keeps it in range.
+      (Socket.gethostname.hash ^ Process.pid) % (MAX_MACHINE_ID + 1)
     end
 
-    def env_machine_id
-      (ENV["SNOWFLAKED_MACHINE_ID"] || ENV.fetch("MACHINE_ID", nil))&.to_i
+    # Coerce to Integer and ensure it fits in 0..MAX_MACHINE_ID, else raise.
+    def checked_machine_id(value)
+      id = Integer(value, exception: false)
+      return id if id&.between?(0, MAX_MACHINE_ID)
+
+      raise ConfigurationError, "machine_id must be an integer between 0 and #{MAX_MACHINE_ID}, got #{value.inspect}"
     end
 
-    def hostname_pid_hash
-      (Socket.gethostname.hash ^ Process.pid) % (MAX_MACHINE_ID + 1)
+    def raise_if_sealed!(attribute)
+      return unless @sealed
+
+      raise ConfigurationError, "#{attribute} cannot be changed after Snowflaked has been configured"
     end
   end
 
@@ -66,8 +107,8 @@ module Snowflaked
     end
 
     def id
-      config = configuration
-      Native.generate(config.machine_id_value, config.epoch_ms)
+      ensure_initialized!
+      Native.generate
     end
 
     def parse(id)
@@ -78,10 +119,15 @@ module Snowflaked
     def timestamp(id)
       ensure_initialized!
       seconds, milliseconds = Native.timestamp_ms(id).divmod(1000)
-      Time.at(seconds, milliseconds * 1000, :usec)
+
+      if defined?(Time.zone) && Time.zone
+        Time.zone.at(seconds, milliseconds * 1000, :usec)
+      else
+        Time.at(seconds, milliseconds * 1000, :usec).utc
+      end
     end
 
-    def machine_id(id)
+    def machine_id(id) # rubocop:disable Rails/Delegate
       Native.machine_id(id)
     end
 
@@ -90,16 +136,20 @@ module Snowflaked
       Native.timestamp_ms(id)
     end
 
-    def sequence(id)
+    def sequence(id) # rubocop:disable Rails/Delegate
       Native.sequence(id)
     end
 
     private
 
     def ensure_initialized!
-      return if Native.initialized?
+      return if @native_initialized_pid == Process.pid
+
+      config = configuration
+      config.seal!
 
-      Native.init_generator(configuration.machine_id_value, configuration.epoch_ms)
+      Native.init_generator(config.machine_id_value, config.epoch_ms)
+      @native_initialized_pid = Process.pid
     end
   end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: snowflaked
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: x86_64-darwin
 authors:
 - Luiz Eduardo Kowalski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-02-27 00:00:00.000000000 Z
-dependencies: []
+date: 2026-07-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
 description: A Ruby gem for generating Twitter Snowflake IDs using a high-performance
   Rust backend. Thread-safe with configurable machine ID and custom epoch support.
 email: 
@@ -20,7 +34,6 @@ files:
 - LICENSE.txt
 - README.md
 - lib/snowflaked.rb
-- lib/snowflaked/3.2/snowflaked.bundle
 - lib/snowflaked/3.3/snowflaked.bundle
 - lib/snowflaked/3.4/snowflaked.bundle
 - lib/snowflaked/4.0/snowflaked.bundle
@@ -47,7 +60,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
   - - "<"
     - !ruby/object:Gem::Version
       version: 4.1.dev