fast_cuid2 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 674b326baeddf83d78dd24637f903fbcf6a823c46cb0e2d951409d0b5b539b94
+  data.tar.gz: f26f14bec785defaa804cb62e6602e78946f7c331dab1e167d7234165f5d4f93
+SHA512:
+  metadata.gz: a416b5eac1fcff9cac876689482c641f9df932d49c5424294b55b94d7e462dd83cd4f43f858370dd9c3768668927e2889cdae6b889945d22528b03b1369db6be
+  data.tar.gz: 5b3efb13674b84b39aefa5cad16ba47d040d90a0817fd25118cd29e88076064b8c6efd90d8d58ac63a1751a9c446e9b8739039534ce5b05116c86e429e8570a2

data/README.md

@@ -0,0 +1,118 @@
+# FastCuid2 🚀
+
+A high-performance CUID2 (Collision-resistant Unique ID) generator for Ruby, implemented in C for maximum speed while maintaining cryptographic security.
+
+## What is CUID2? 🤔
+
+CUID2 is the next generation of collision-resistant ids, designed to be:
+- 🔒 Secure: Uses cryptographically secure random numbers
+- 📏 Shorter: 24 characters vs CUID1's 25
+- 🔗 URL-safe: Uses a restricted character set
+- ⏰ Time-sortable: Includes a timestamp component
+- 🎯 Unique: Has a negligible chance of collision
+
+## Installation 💿
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fast_cuid2'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install fast_cuid2
+```
+
+## Usage 🛠️
+
+### Basic Usage 💡
+
+```ruby
+require 'fast_cuid2'
+
+# Generate a new CUID2
+id = FastCuid2.generate
+puts id  # => "k2zt4qxvz5..."
+
+# Use as a before_create callback in your models
+class User < ApplicationRecord
+  before_create :set_cuid2
+
+  private
+    def set_cuid2
+      self.id = FastCuid2.generate
+    end
+end
+```
+
+### Database Migrations 🗄️
+
+Example migration for creating a new table with CUID2:
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[7.0]
+  def change
+    create_table :users, id: false do |t|
+      t.string :id, primary_key: true, null: false, limit: 24
+      t.timestamps
+    end
+  end
+end
+```
+
+Adding a CUID2 column to an existing table:
+
+```ruby
+class AddReferenceToPosts < ActiveRecord::Migration[7.0]
+  def change
+    add_column :posts, :reference_id, :string, limit: 24
+    add_index :posts, :reference_id, unique: true
+  end
+end
+```
+
+## CUID2 Format 📋
+
+Each CUID2 is a 24-character string that:
+- 📝 Always starts with a letter
+- ⌨️ Uses only lowercase letters and numbers (excluding i, l, o, u)
+- 🕒 Includes a time component for rough sorting
+- 🔐 Has cryptographically secure random data
+
+## Performance ⚡
+
+FastCuid2 is implemented in C for maximum performance. It uses:
+- 🔒 OpenSSL's CSPRNG for secure random numbers
+- ⚙️ Optimized bit operations
+- 💾 Minimal memory allocations
+- 🔄 Thread-safe implementation
+
+## Development 👩‍💻
+
+After checking out the repo, run:
+
+```bash
+$ bundle install
+$ rake compile  # Builds the C extension
+$ rake spec    # Runs the tests
+```
+
+## Contributing 🤝
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sebyx07/fast_cuid2. This project is intended to be a safe, welcoming space for collaboration.
+
+## License 📜
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct 🤝
+
+Everyone interacting in the FastCuid2 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sebyx07/fast_cuid2/blob/master/CODE_OF_CONDUCT.md).

data/ext/fast_cuid2/extconf.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+
+# Add optimization flags
+$CFLAGS << ' -O3 -Wall -Wextra'
+
+# Check for required headers
+have_header('ruby.h')
+have_library('crypto')
+have_header('openssl/rand.h')
+
+extension_name = 'fast_cuid2/fast_cuid2'
+dir_config(extension_name)
+
+create_makefile(extension_name)

data/ext/fast_cuid2/fast_cuid2.c

@@ -0,0 +1,119 @@
+#include <ruby.h>
+#include <time.h>
+#include <openssl/rand.h>
+#include <string.h>
+
+/* Constants for CUID2 generation */
+#define CUID2_LENGTH 24
+#define CUID2_BUFFER_SIZE (CUID2_LENGTH + 1)
+#define TIMESTAMP_LENGTH 6
+#define RANDOM_BYTES_LENGTH 12
+#define BASE32_CHARS_LENGTH 32
+#define TIMESTAMP_BITS 5
+#define RANDOM_CHUNK_SIZE 2
+#define BASE32_CHARS_PER_CHUNK 3
+
+/* Base32 alphabet excluding i, l, o, u for better readability */
+static const char BASE32_CHARS[] = "0123456789abcdefghjkmnpqrstvwxyz";
+
+static VALUE rb_mFastCuid2;
+
+/**
+ * Encodes an integer into base32 representation.
+ * @param num The number to encode
+ * @param output The buffer to write to
+ * @param length The number of characters to write
+ */
+static void encode_base32(uint64_t num, char *output, int length) {
+    for (int i = length - 1; i >= 0; i--) {
+        output[i] = BASE32_CHARS[num & 0x1f];
+        num >>= TIMESTAMP_BITS;
+    }
+}
+
+/**
+ * Generates cryptographically secure random bytes.
+ * @param buf Buffer to store random bytes
+ * @param length Number of random bytes to generate
+ * @raises RuntimeError if random byte generation fails
+ */
+static void generate_random_bytes(unsigned char *buf, int length) {
+    if (RAND_bytes(buf, length) != 1) {
+        rb_raise(rb_eRuntimeError, "Failed to generate secure random bytes");
+    }
+}
+
+/**
+ * Ensures the first character of the CUID2 is a letter.
+ * @param cuid The CUID2 string to modify
+ */
+static void ensure_first_char_is_letter(char *cuid) {
+    if (cuid[0] >= '0' && cuid[0] <= '9') {
+        int offset = 10 + (cuid[0] - '0'); // Map digit to letter range
+        cuid[0] = BASE32_CHARS[offset];
+    }
+}
+
+/**
+ * Generates a CUID2 (Collision-resistant Unique IDentifier).
+ * Format: <6 chars timestamp><18 chars random>
+ * @return [String] A 24-character CUID2
+ * @raise [RuntimeError] If generation fails
+ */
+static VALUE rb_generate_cuid2(VALUE self) {
+    char cuid[CUID2_BUFFER_SIZE] = {0};
+    struct timespec ts;
+    unsigned char random_bytes[RANDOM_BYTES_LENGTH];
+
+    // Get current timestamp in milliseconds
+    if (clock_gettime(CLOCK_REALTIME, &ts) != 0) {
+        rb_raise(rb_eRuntimeError, "Failed to get system time");
+    }
+    uint64_t timestamp = (uint64_t)ts.tv_sec * 1000 + (uint64_t)ts.tv_nsec / 1000000;
+
+    // Generate random bytes
+    generate_random_bytes(random_bytes, RANDOM_BYTES_LENGTH);
+
+    // Encode timestamp (first 6 chars)
+    encode_base32(timestamp, cuid, TIMESTAMP_LENGTH);
+
+    // Fill remaining 18 chars with random data
+    // Process 2 bytes at a time to generate 3 base32 chars
+    for (int i = 0; i < RANDOM_BYTES_LENGTH; i += RANDOM_CHUNK_SIZE) {
+        uint32_t rand_chunk =
+            ((uint32_t)random_bytes[i] << 8) |
+            ((uint32_t)random_bytes[i + 1]);
+        encode_base32(rand_chunk, cuid + TIMESTAMP_LENGTH + (i / RANDOM_CHUNK_SIZE) * BASE32_CHARS_PER_CHUNK, BASE32_CHARS_PER_CHUNK);
+    }
+
+    ensure_first_char_is_letter(cuid);
+
+    return rb_str_new2(cuid);
+}
+
+/**
+ * Validates a CUID2 string.
+ * @param str [String] The string to validate
+ * @return [Boolean] true if valid CUID2, false otherwise
+ */
+static VALUE rb_validate_cuid2(VALUE self, VALUE str) {
+    Check_Type(str, T_STRING);
+
+    if (RSTRING_LEN(str) != CUID2_LENGTH) return Qfalse;
+
+    const char *cuid = StringValuePtr(str);
+    for (int i = 0; i < CUID2_LENGTH; i++) {
+        if (!strchr(BASE32_CHARS, cuid[i])) return Qfalse;
+    }
+
+    // First character must be a letter
+    if (strchr("0123456789", cuid[0])) return Qfalse;
+
+    return Qtrue;
+}
+
+void Init_fast_cuid2(void) {
+    rb_mFastCuid2 = rb_define_module("FastCuid2");
+    rb_define_singleton_method(rb_mFastCuid2, "generate", rb_generate_cuid2, 0);
+    rb_define_singleton_method(rb_mFastCuid2, "valid?", rb_validate_cuid2, 1);
+}

data/fast_cuid2.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/gem/fast_cuid2/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'fast_cuid2'
+  spec.version = FastCuid2::VERSION
+  spec.authors = ['sebi']
+  spec.email = ['gore.sebyx@yahoo.com']
+
+  spec.summary = 'Fast CUID2 generator with C extension'
+  spec.description = 'High-performance CUID2 (Collision-resistant Unique ID) generator ' \
+    'implemented in C for maximum speed while maintaining cryptographic security.'
+  spec.homepage = 'https://github.com/sebyx07/fast_cuid2'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  # Include C extension
+  spec.extensions = ['ext/fast_cuid2/extconf.rb']
+
+  # Include both lib and ext directories
+  spec.files = Dir.glob('{lib,ext}/{**/*,*}') +
+    ['README.md', File.basename(__FILE__)]
+
+  # Set require paths for both the gem and extension
+  spec.require_paths = %w[lib/gem lib]
+
+  # Development dependencies
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rake-compiler', '~> 1.2'
+end

data/lib/gem/fast_cuid2/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FastCuid2
+  VERSION = '1.0.0'
+end

data/lib/gem/fast_cuid2.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Dir.glob(File.join(File.dirname(__FILE__), 'fast_cuid2', '**', '*.rb')).each do |file|
+  require file
+end
+
+begin
+  require 'fast_cuid2/fast_cuid2'
+rescue LoadError
+  puts 'Error loading fast_cuid2 extension'
+end
+
+module FastCuid2
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: fast_cuid2
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- sebi
+bindir: bin
+cert_chain: []
+date: 2025-02-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: High-performance CUID2 (Collision-resistant Unique ID) generator implemented
+  in C for maximum speed while maintaining cryptographic security.
+email:
+- gore.sebyx@yahoo.com
+executables: []
+extensions:
+- ext/fast_cuid2/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/fast_cuid2/extconf.rb
+- ext/fast_cuid2/fast_cuid2.c
+- fast_cuid2.gemspec
+- lib/fast_cuid2/fast_cuid2.so
+- lib/gem/fast_cuid2.rb
+- lib/gem/fast_cuid2/version.rb
+homepage: https://github.com/sebyx07/fast_cuid2
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sebyx07/fast_cuid2
+  source_code_uri: https://github.com/sebyx07/fast_cuid2
+rdoc_options: []
+require_paths:
+- lib/gem
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Fast CUID2 generator with C extension
+test_files: []