snowflaked 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f68c35e56f2b711babd4f66a36c759964a5d62cfd43e3076032491ef08af8f0a
+  data.tar.gz: ac779781bedeb1379d52e10ba6d86f72dad333b7d9ea424d99b711fa27bf302f
+SHA512:
+  metadata.gz: 4d7cd9826ae0ec4bbf15fb591d29c831e06678f82739b5b4e351540c5e69e4f45b7f1f179f131436e01200bd72320119536681e5a5abdeddd872a48771d95e7f
+  data.tar.gz: f47b9bbfab1f8a4e259d4cafcb1669fba31a6a16a758a2e53e6178d6cfef16ac6afa2325a0c05af4ed1ebaa9ff251373f9649684bd9163ef2bd0f7e709711051

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luiz Eduardo Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# Snowflaked
+
+A high-performance, thread-safe Snowflake ID generator for Ruby, powered by Rust.
+
+Snowflake IDs are 64-bit unique identifiers that encode a timestamp, machine ID, and sequence number. They're time-sortable (IDs created later are always larger), making them ideal for distributed systems where you need unique IDs without coordination between machines. Unlike UUIDs, Snowflake IDs are smaller, sortable, and index-friendly for databases.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "snowflaked"
+```
+
+## Quick Start
+
+```ruby
+id = Snowflaked.id
+# => 7193489234823847936
+```
+
+## Rails Integration
+
+All models automatically generate a Snowflake ID for the `:id` attribute:
+
+```ruby
+class User < ApplicationRecord
+end
+
+User.create!
+# => #<User id: 7193489234823847936>
+```
+
+You can also define additional Snowflake columns in migrations:
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :users do |t|
+      t.snowflake :external_id
+    end
+  end
+end
+```
+
+If you want to generate Snowflake IDs for additional columns, you can do so by using the `snowflake_id` method, without having to migrate the table:
+
+```ruby
+class User < ApplicationRecord
+  snowflake_id :external_id
+end
+```
+
+It is also possible to disable automatic `:id` generation by passing `id: false` to the `snowflake_id` method:
+
+```ruby
+class Post < ApplicationRecord
+  snowflake_id id: false
+end
+```
+
+Or generate Snowflake IDs for other columns but not `:id`:
+
+```ruby
+class Post < ApplicationRecord
+  snowflake_id :external_id, id: false
+end
+```
+
+## Configuration
+
+```ruby
+Snowflaked.configure do |config|
+  config.machine_id = 42
+  config.epoch = Time.utc(2020, 1, 1)
+end
+```
+
+### Machine ID Resolution
+
+If `machine_id` is not explicitly configured, it resolves in this order:
+
+1. `SNOWFLAKED_MACHINE_ID` environment variable
+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:
+
+```yaml
+env:
+  - name: SNOWFLAKED_MACHINE_ID
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.name
+```
+
+Or use a StatefulSet ordinal for guaranteed unique values:
+
+```yaml
+env:
+  - name: SNOWFLAKED_MACHINE_ID
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.annotations['apps.kubernetes.io/pod-index']
+```
+
+## API Reference
+
+```ruby
+id = Snowflaked.id
+
+Snowflaked.parse(id)
+# => {timestamp_ms: 1735123456789, machine_id: 42, sequence: 0}
+
+Snowflaked.timestamp(id)
+# => 2024-12-25 12:34:56 +0000
+
+Snowflaked.timestamp_ms(id)
+# => 1735123456789
+
+Snowflaked.sequence(id)
+# => 0
+
+Snowflaked.machine_id(id)
+# => 42
+```
+
+## Requirements
+
+- Ruby >= 3.2
+- rustc >= 1.81.0
+- cargo >= 1.81.0
+- Mise
+
+## Development
+
+```bash
+mise install
+bundle install
+bundle exec rake
+```
+
+## License
+
+MIT

data/lib/snowflaked/adapter_extension.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Snowflaked
+  module AdapterExtension
+    SNOWFLAKE_TYPE = { name: "bigint" }.freeze
+
+    def native_database_types
+      super.merge(snowflake: SNOWFLAKE_TYPE)
+    end
+
+    module ClassMethods
+      def native_database_types
+        super.merge(snowflake: SNOWFLAKE_TYPE)
+      end
+    end
+
+    def self.prepended(base)
+      base.singleton_class.prepend(ClassMethods)
+    end
+  end
+end

data/lib/snowflaked/model_extensions.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Snowflaked
+  module ModelExtensions
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_snowflake_attributes, instance_writer: false, default: [:id] # rubocop:disable ThreadSafety/ClassAndModuleAttributes -- false positive
+      before_validation :_generate_snowflake_ids, on: :create
+    end
+
+    class_methods do
+      def snowflake_id(*attributes, id: true)
+        attrs = attributes.map(&:to_sym)
+        attrs |= [:id] if id
+        self._snowflake_attributes = attrs
+      end
+
+      def _snowflake_columns_from_comments
+        return [] unless table_exists?
+
+        columns.select { |c| c.comment == Snowflaked::SchemaDefinitions::COMMENT }.map { |c| c.name.to_sym }
+      end
+    end
+
+    private
+
+    def _generate_snowflake_ids
+      attributes_to_generate = self.class._snowflake_attributes | self.class._snowflake_columns_from_comments
+
+      attributes_to_generate.each do |attribute|
+        next if self[attribute].present?
+
+        self[attribute] = Snowflaked.id
+      end
+    end
+  end
+end

data/lib/snowflaked/railtie.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Snowflaked
+  class Railtie < Rails::Railtie
+    initializer "snowflaked.register_type", after: "active_record.initialize_database" do
+      ActiveSupport.on_load(:active_record) do
+        require "snowflaked/type/snowflake"
+        ActiveRecord::Type.register(:snowflake, Snowflaked::Type::Snowflake)
+      end
+    end
+
+    initializer "snowflaked.extend_adapters", after: "active_record.initialize_database" do
+      ActiveSupport.on_load(:active_record) do
+        require "snowflaked/adapter_extension"
+
+        adapters = %w[
+          PostgreSQLAdapter
+          Mysql2Adapter
+          TrilogyAdapter
+          SQLite3Adapter
+        ]
+
+        adapters.each do |adapter_name|
+          next unless ActiveRecord::ConnectionAdapters.const_defined?(adapter_name)
+
+          ActiveRecord::ConnectionAdapters.const_get(adapter_name).prepend(
+            Snowflaked::AdapterExtension
+          )
+        end
+      end
+    end
+
+    initializer "snowflaked.schema_definitions", after: "active_record.initialize_database" do
+      ActiveSupport.on_load(:active_record) do
+        require "snowflaked/schema_definitions"
+
+        ActiveRecord::ConnectionAdapters::TableDefinition.include(Snowflaked::SchemaDefinitions::TableDefinition)
+        ActiveRecord::ConnectionAdapters::Table.include(Snowflaked::SchemaDefinitions::Table)
+      end
+    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
+    end
+  end
+end

data/lib/snowflaked/schema_definitions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Snowflaked
+  module SchemaDefinitions
+    COMMENT = "snowflaked"
+
+    module TableDefinition
+      def snowflake(name, **options)
+        options[:comment] = Snowflaked::SchemaDefinitions::COMMENT
+        column(name, :snowflake, **options)
+      end
+    end
+
+    module Table
+      def snowflake(name, **options)
+        options[:comment] = Snowflaked::SchemaDefinitions::COMMENT
+        column(name, :snowflake, **options)
+      end
+    end
+  end
+end

data/lib/snowflaked/type/snowflake.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Snowflaked
+  module Type
+    class Snowflake < ActiveRecord::Type::BigInteger
+      def type
+        :snowflake
+      end
+    end
+  end
+end

data/lib/snowflaked/version.rb

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

data/lib/snowflaked.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "snowflaked/version"
+require_relative "snowflaked/snowflaked"
+require "socket"
+
+require_relative "snowflaked/railtie" if defined?(Rails::Railtie)
+
+module Snowflaked
+  MAX_MACHINE_ID = 1023
+
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class Configuration
+    attr_accessor :machine_id, :epoch
+
+    def initialize
+      @machine_id = nil
+      @epoch      = nil
+    end
+
+    def machine_id_value
+      id = @machine_id || default_machine_id
+      id % (MAX_MACHINE_ID + 1)
+    end
+
+    def epoch_ms
+      return nil unless @epoch
+
+      (@epoch.to_f * 1000).to_i
+    end
+
+    private
+
+    def default_machine_id
+      env_machine_id || hostname_pid_hash
+    end
+
+    def env_machine_id
+      id = ENV["SNOWFLAKED_MACHINE_ID"] || ENV.fetch("MACHINE_ID", nil)
+      id&.to_i
+    end
+
+    def hostname_pid_hash
+      (Socket.gethostname.hash ^ Process.pid) % (MAX_MACHINE_ID + 1)
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new # rubocop:disable ThreadSafety/ClassInstanceVariable -- not changed after initialization
+    end
+
+    def configure
+      yield(configuration) if block_given?
+
+      ensure_initialized!
+      configuration
+    end
+
+    def id
+      ensure_initialized!
+      Native.generate
+    end
+
+    def parse(id)
+      ensure_initialized!
+      Native.parse(id)
+    end
+
+    def timestamp(id)
+      time_ms = Native.timestamp_ms(id)
+      Time.at(time_ms / 1000, (time_ms % 1000) * 1000, :usec)
+    end
+
+    def machine_id(id)
+      ensure_initialized!
+      Native.machine_id(id)
+    end
+
+    def timestamp_ms(id)
+      Native.timestamp_ms(id)
+    end
+
+    def sequence(id)
+      Native.sequence(id)
+    end
+
+    private
+
+    def ensure_initialized!
+      return if Native.initialized?
+
+      config = configuration
+      Native.init_generator(config.machine_id_value, config.epoch_ms)
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: snowflaked
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- Luiz Eduardo Kowalski
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-01-08 00:00:00.000000000 Z
+dependencies: []
+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: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/snowflaked.rb
+- lib/snowflaked/3.2/snowflaked.so
+- lib/snowflaked/3.3/snowflaked.so
+- lib/snowflaked/3.4/snowflaked.so
+- lib/snowflaked/4.0/snowflaked.so
+- lib/snowflaked/adapter_extension.rb
+- lib/snowflaked/model_extensions.rb
+- lib/snowflaked/railtie.rb
+- lib/snowflaked/schema_definitions.rb
+- lib/snowflaked/type/snowflake.rb
+- lib/snowflaked/version.rb
+homepage: https://github.com/luizkowalski/snowflaked
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/luizkowalski/snowflaked
+  source_code_uri: https://github.com/luizkowalski/snowflaked
+  changelog_uri: https://github.com/luizkowalski/snowflaked/blob/main/CHANGES.md
+  bug_tracker_uri: https://github.com/luizkowalski/snowflaked/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Fast Snowflake ID generator with Rust backend
+test_files: []