dynamic_links 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8be4269ba92cfbec08c29ec6a6a871383b8470736057204fa24234ebfc70a98
-  data.tar.gz: 90a2df3615def525638fc53eeb23eef0a367d0137993b6303630d7d868ac3443
+  metadata.gz: d7f8c21c9c9432cdd2ed12ddc9e86a79b8f3024a240a406bba89157478520c9d
+  data.tar.gz: 30e2a4084f34977c4e267aa940454e53978ad193d99214312f90b6ee948fda2d
 SHA512:
-  metadata.gz: 3ca6e9c92116542c9df6895e861843c03e951cb7e87bf567bc189b4811f8fb6cf95e097123b4569843ea18f8780289e1bec70b2de2a8bd92532f929277e0578e
-  data.tar.gz: 50e65b566b1b36f9b169f0a7c35610720027f030c31d4fd7fe861ee077ea1b5c043391a51caf4f34c612f13456fdcf16cbb95d39a019c69f65bb2676bc2d7fd7
+  metadata.gz: 1deecaad47165bae46df566e68661bc77444aa36d143084d7e1a6aa76d05958e9183b1f88a9a083813404778e9f305d8588887a1558b8d8f98c1ec66c1c07e10
+  data.tar.gz: bc0572b2ce3274ada41824867284e47d82263db2b2e2c323c8306f1c5487cd30040fe3b677b950880d17b026a997daa3907bbd060d3fdda3db83076f1566fbe3

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.2.0] - 2025-06-17
+
+- [#88](https://github.com/saiqulhaq/dynamic_links/pull/88)
+
+  - New Feature: Added API method to expand shortened URLs via the `expand` endpoint
+  - New Feature: Added fallback mode to redirect to Firebase host when short URL not found
+  - Enhancement: Improved multi-tenant support in controllers
+
+- [#19](https://github.com/saiqulhaq/dynamic_links/pull/19)
+
+  - New Feature: Added asynchronous URL shortening functionality, improving performance for large-scale operations.
+  - Refactor: Updated DynamicLinks::Configuration class to accommodate new features and improve flexibility.
+  - Test: Expanded test coverage to include new features and functionalities.
+  - Documentation: Updated README with instructions on performance optimization and running unit tests.
+  - Chore: Added benchmarking scripts to measure the performance of synchronous vs asynchronous URL shortening and different versions of `create_or_find` method.
+
+- Custom domain per client
+- Ruby API for URL shortening.
+- Add CRC32, nanoid, Redis counter, and KGS strategies to shorten an URL.
+- URL validation feature.
+- Configuration option to enable/disable REST API.
+- Redirection feature. [#14](https://github.com/saiqulhaq/dynamic_links/pull/14)

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-2025 Saiqul Haq
+
+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

@@ -1,10 +1,14 @@
 # DynamicLinks
 
+[![Unit Tests](https://github.com/saiqulhaq/dynamic_links/actions/workflows/unit_test.yml/badge.svg)](https://github.com/saiqulhaq/dynamic_links/actions/workflows/unit_test.yml)
+
 DynamicLinks is a flexible URL shortening Ruby gem, designed to provide various strategies for URL shortening, similar to Firebase Dynamic Links.
 
+By default, encoding strategies such as MD5 will generate the same short URL for the same input URL. This behavior ensures consistency and prevents the creation of multiple records for identical URLs. For scenarios requiring unique short URLs for each request, strategies like RedisCounterStrategy can be used, which generate a new short URL every time, regardless of the input URL.
+
 ## Usage
 
-To use DynamicLinks, you need to configure the shortening strategy in an initializer or before you start shortening URLs.
+To use DynamicLinks, you need to configure the shortening strategy and other settings in an initializer or before you start shortening URLs.
 
 ### Configuration
 
@@ -12,10 +16,70 @@ In your Rails initializer or similar setup code, configure DynamicLinks like thi
 
 ```ruby
 DynamicLinks.configure do |config|
-  config.shortening_strategy = :MD5
+  config.shortening_strategy = :md5  # Default strategy
+  config.redis_config = { host: 'localhost', port: 6379 }  # Redis configuration
+  config.redis_pool_size = 10  # Redis connection pool size
+  config.redis_pool_timeout = 3  # Redis connection pool timeout in seconds
+  config.enable_rest_api = true  # Enable or disable REST API feature
+
+  # New configuration added in PR #88
+  config.enable_fallback_mode = false  # When true, falls back to Firebase URL if a short link is not found
+  config.firebase_host = "https://example.app.goo.gl"  # Firebase host URL for fallbacks
 end
 ```
 
+## Development Environment
+
+This project supports two development environment options: GitHub Codespaces and local Docker Compose.
+
+### Option 1: GitHub Codespaces
+
+This project is configured to work with GitHub development containers, providing a consistent development environment.
+
+#### Opening in GitHub Codespaces
+
+1. Navigate to the GitHub repository
+2. Click the "Code" button
+3. Select the "Codespaces" tab
+4. Click "Create codespace on main"
+
+#### Development in the Codespace
+
+Once the development container is created and set up:
+
+1. The container includes Ruby 3.2, PostgreSQL, Redis, and other dependencies
+2. Run the test suite: `cd test/dummy && bin/rails test`
+3. Start the Rails server: `cd test/dummy && bin/rails server`
+
+### Option 2: Local Development with Docker Compose
+
+For local development, we use Docker Compose with VS Code's Remote - Containers extension.
+
+#### Prerequisites
+
+1. Install [Docker](https://docs.docker.com/get-docker/)
+2. Install [VS Code](https://code.visualstudio.com/)
+3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+#### Opening in VS Code with Containers
+
+1. Clone the repository to your local machine
+2. Open the project folder in VS Code
+3. VS Code will detect the devcontainer configuration and prompt you to reopen in a container
+4. Click "Reopen in Container"
+
+#### Working with the Docker Compose Setup
+
+- The setup includes three services: app (Ruby), postgres (PostgreSQL), and redis (Redis)
+- Database and Redis connections are automatically configured
+- Use VS Code tasks (F1 -> "Tasks: Run Task") for common operations like:
+  - Starting the Rails server
+  - Running tests
+  - Running the Rails console
+  - Managing Docker Compose services
+
+For more details on the Docker Compose setup, refer to the [Docker Compose documentation](DOCKER_COMPOSE.md). 4. Access the application at the forwarded port (usually port 3000)
+
 ### Shortening a URL
 
 To shorten a URL, simply call:
@@ -24,16 +88,64 @@ To shorten a URL, simply call:
 shortened_url = DynamicLinks.shorten_url("https://example.com")
 ```
 
+### Expanding a Short URL
+
+To expand (resolve) a short URL back to its original URL, use the `resolve_short_url` method:
+
+```ruby
+original_url = DynamicLinks.resolve_short_url("abc123")
+# Returns the original URL or nil if not found
+```
+
+#### Using the REST API to Expand URLs
+
+The gem also provides a REST API endpoint to expand short URLs:
+
+```
+GET /v1/shortLinks/:short_url?api_key=YOUR_API_KEY
+```
+
+Example response:
+
+```json
+{
+  "full_url": "https://example.com/original-path"
+}
+```
+
+If the URL is not found, you'll receive a 404 status code with an error message:
+
+```json
+{
+  "error": "Short link not found"
+}
+```
+
+## Fallback Mode
+
+The fallback mode feature (added in PR #88) allows your application to redirect users to a Firebase Dynamic Links URL when a short URL is not found in your system. This can be useful in migration scenarios or when running both systems in parallel.
+
+To enable this feature:
+
+```ruby
+DynamicLinks.configure do |config|
+  config.enable_fallback_mode = true
+  config.firebase_host = "https://your-app.page.link"  # Your Firebase Dynamic Links URL
+end
+```
+
+When a user visits a short link that doesn't exist in your database, they will be redirected to the equivalent Firebase URL instead of receiving a 404 error.
+
 ## Available Shortening Strategies
 
-DynamicLinks supports various shortening strategies. The default strategy is `MD5`, but you can choose among several others, including `NanoIdStrategy`, `RedisCounterStrategy`, `Sha256Strategy`, and more.
+DynamicLinks supports various shortening strategies. The default strategy is now `NanoIdStrategy` (changed from `MD5` in PR #88), but you can choose among several others, including `MD5Strategy`, `RedisCounterStrategy`, `Sha256Strategy`, and more.
 
 Depending on the strategy you choose, you may need to install additional dependencies.
 
 ### Optional Dependencies
 
 - For `NanoIdStrategy`, add `gem 'nanoid', '~> 2.0'` to your Gemfile.
-- For `RedisCounterStrategy`, add `gem 'redis', '>= 4'` to your Gemfile.
+- For `RedisCounterStrategy`, ensure Redis is available and configured. Redis strategy requires `connection_pool` gem too.
 
 Ensure you bundle these dependencies along with the DynamicLinks gem if you plan to use these strategies.
 
@@ -57,9 +169,33 @@ Or install it yourself as:
 $ gem install dynamic_links
 ```
 
-## Contributing
+## Performance
+
+Shorten an URL using Ruby:
+Shorten an URL using API:
+
+## How to run the unit test
+
+### When using a Plain PostgreSQL DB
+
+```bash
+rails db:setup
+rails db:test:prepare
+rails test
+```
+
+### When using PostgreSQL DB with Citus
+
+```bash
+export CITUS_ENABLED=true
+rails db:setup
+rails db:test:prepare
+rails test
+```
 
-We welcome contributions to DynamicLinks! Please read the contributing guidelines to get started.
+Note:
+Make sure the Citus extension already enabled on the installed PostgreSQL
+We don't manage it on Rails.
 
 ## License
 

data/app/controllers/dynamic_links/application_controller.rb

@@ -1,4 +1,18 @@
 module DynamicLinks
-  class ApplicationController < ActionController::Base
+  class ApplicationController < ActionController::API
+    def multi_tenant(client, db_infra_strategy = DynamicLinks.configuration.db_infra_strategy)
+      if db_infra_strategy == :sharding
+        if defined?(::MultiTenant)
+          ::MultiTenant.with(client) do
+            yield
+          end
+        else
+          Rails.logger.warn 'MultiTenant gem is not installed. Please install it to use sharding strategy'
+          yield
+        end
+      else
+        yield
+      end
+    end
   end
 end

data/app/controllers/dynamic_links/redirects_controller.rb

@@ -0,0 +1,29 @@
+module DynamicLinks
+  class RedirectsController < ApplicationController
+    def show
+      client = DynamicLinks::Client.find_by({ hostname: request.host })
+      unless client
+        render plain: 'URL not found', status: :not_found
+        return
+      end
+
+      multi_tenant(client) do
+        short_url = params[:short_url]
+        link = ShortenedUrl.find_by(short_url: short_url)
+
+        if link.nil?
+          if DynamicLinks.configuration.enable_fallback_mode && DynamicLinks.configuration.firebase_host.present?
+            redirect_to "#{DynamicLinks.configuration.firebase_host}/#{short_url}", status: :found, allow_other_host: true
+          else
+            render plain: 'Not found', status: :not_found
+          end
+          return
+        end
+
+        raise ActiveRecord::RecordNotFound if link.expired?
+
+        redirect_to link.url, status: :found, allow_other_host: true
+      end
+    end
+  end
+end

data/app/controllers/dynamic_links/v1/short_links_controller.rb

@@ -1,14 +1,56 @@
-class DynamicLinks::V1::ShortLinksController < ApplicationController
-  def create
-    url = params.require(:url)
-    # validate url
-    # if !url_shortener.valid_url?(url)
-    #   render json: { error: 'invalid url' }, status: :bad_request
-    #   return
-    # end
-
-    # shorten url
-    # save to db (not implemented yet)
-    render json: DynamicLinks.generate_short_url(url), status: :created
+module DynamicLinks
+  class V1::ShortLinksController < ApplicationController
+    before_action :check_rest_api_enabled
+
+    def create
+      url = params.require(:url)
+      client = DynamicLinks::Client.find_by({ api_key: params.require(:api_key) })
+
+      unless client
+        render json: { error: 'Invalid API key' }, status: :unauthorized
+        return
+      end
+
+      multi_tenant(client) do
+        render json: DynamicLinks.generate_short_url(url, client), status: :created
+      end
+    rescue DynamicLinks::InvalidURIError
+      render json: { error: 'Invalid URL' }, status: :bad_request
+    rescue => e
+      DynamicLinks::Logger.log_error(e)
+      render json: { error: 'An error occurred while processing your request' }, status: :internal_server_error
+    end
+
+    def expand
+      api_key = params.require(:api_key)
+      client = DynamicLinks::Client.find_by({ api_key: api_key })
+
+      unless client
+        render json: { error: 'Invalid API key' }, status: :unauthorized
+        return
+      end
+
+      multi_tenant(client) do
+        short_link = params.require(:short_url)
+        full_url = DynamicLinks.resolve_short_url(short_link)
+
+        if full_url
+          render json: { full_url: full_url }, status: :ok
+        else
+          render json: { error: 'Short link not found' }, status: :not_found
+        end
+      end
+    rescue => e
+      DynamicLinks::Logger.log_error(e)
+      render json: { error: 'An error occurred while processing your request' }, status: :internal_server_error
+    end
+
+    private
+
+    def check_rest_api_enabled
+      unless DynamicLinks.configuration.enable_rest_api
+        render json: { error: 'REST API feature is disabled' }, status: :forbidden
+      end
+    end
   end
 end

data/app/jobs/dynamic_links/generate_short_links_job.rb

@@ -1,5 +1,5 @@
 module DynamicLinks
-  # This job generates short links in the background
+  # This job generates short links in the background for KGS strategy
   # It is intended to be run periodically
   # We can find available short links by querying the database with query:
   # ShortenedUrl.where(available: true)

data/app/jobs/dynamic_links/shorten_url_job.rb

@@ -0,0 +1,31 @@
+module DynamicLinks
+  # @author Saiqul Haq <saiqulhaq@gmail.com>
+  # This job is used to create a shortened url
+  class ShortenUrlJob < ApplicationJob
+    queue_as :default
+
+    def perform(client, url, short_url, lock_key)
+      locker = DynamicLinks::Async::Locker.new
+      strategy = StrategyFactory.get_strategy(DynamicLinks.configuration.shortening_strategy)
+
+      begin
+        if strategy.always_growing?
+          storage.create!(client: client, url: url, short_url: short_url)
+        else
+          storage.find_or_create!(client, short_url, url)
+        end
+        locker.unlock(lock_key)
+        DynamicLinks::Logger.log_info("Lock key #{lock_key} deleted after ShortenUrlJob")
+      rescue => e
+        DynamicLinks::Logger.log_error("Error in ShortenUrlJob: #{e.message}")
+        raise e
+      end
+    end
+
+    private
+
+    def storage
+      @storage ||= ShortenedUrl
+    end
+  end
+end

data/app/models/dynamic_links/client.rb

@@ -15,7 +15,12 @@
 #
 module DynamicLinks
   class Client < ApplicationRecord
+    VALID_SCHEMES = ['http', 'https'].freeze
+
     validates :name, presence: true, uniqueness: true
     validates :api_key, presence: true, uniqueness: true
+    validates :hostname, presence: true, uniqueness: true
+    validates :scheme, presence: true, inclusion: { in: VALID_SCHEMES }
+    validates :hostname, format: { with: /\A[a-z0-9]([a-z0-9\-]{,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9\-]{,61}[a-z0-9])?)*\z/i, message: 'must be a valid hostname' }
   end
 end

data/app/models/dynamic_links/shortened_url.rb

@@ -17,9 +17,27 @@
 #
 module DynamicLinks
   class ShortenedUrl < ApplicationRecord
-    belongs_to :client, optional: true
+    belongs_to :client
+    multi_tenant :client if respond_to?(:multi_tenant)
 
     validates :url, presence: true
-    validates :short_url, presence: true, uniqueness: true
+    validates :short_url, presence: true, uniqueness: { scope: :client_id }
+
+    def self.find_or_create!(client, short_url, url)
+      transaction do
+        record = find_or_create_by!(client: client, short_url: short_url) do |record|
+          record.url = url
+        end
+        record
+      end
+    rescue ActiveRecord::RecordInvalid => e
+      # Log the error and re-raise if needed or return a meaningful error message
+      DynamicLinks::Logger.log_error("ShortenedUrl creation failed: #{e.message}")
+      raise e
+    end
+
+    def expired?
+      expires_at&.past?
+    end
   end
 end

data/config/routes.rb

@@ -2,7 +2,9 @@
 #
 
 DynamicLinks::Engine.routes.draw do
+  get '/:short_url', to: 'redirects#show', as: :shortened
   namespace :v1 do
     post "/shortLinks", to: "short_links#create", as: :short_links
+    get "/shortLinks/:short_url", to: "short_links#expand", as: :expand_short_link
   end
 end

data/db/migrate/20231228165744_create_dynamic_links_clients.rb

@@ -3,11 +3,18 @@ class CreateDynamicLinksClients < ActiveRecord::Migration[7.1]
     create_table :dynamic_links_clients do |t|
       t.string :name, null: false
       t.string :api_key, null: false
+      t.string :scheme, default: 'https', null: false
+      t.string :hostname, null: false
 
       t.timestamps
     end
 
-    add_index :dynamic_links_clients, :name, unique: true
+    if DynamicLinks.configuration.db_infra_strategy == :sharding
+      create_reference_table(:dynamic_links_clients)
+    end
+
+    add_index :dynamic_links_clients, :name
     add_index :dynamic_links_clients, :api_key, unique: true
+    add_index :dynamic_links_clients, :hostname, unique: true
   end
 end

data/db/migrate/20231228175142_create_dynamic_links_shortened_urls.rb

@@ -7,15 +7,14 @@ class CreateDynamicLinksShortenedUrls < ActiveRecord::Migration[7.1]
         t.bigint :id, primary_key: true
       end
 
-      t.references :client, null: true, foreign_key: { to_table: :dynamic_links_clients }, type: :bigint
+      t.references :client, foreign_key: { to_table: :dynamic_links_clients }, type: :bigint
+
       # 2083 is the maximum length of a URL according to the RFC 2616
       t.string :url, null: false, limit: 2083
       # 12 is the maximum length of a short URL if we use the RedisCounterStrategy
-      t.string :short_url, null: false, limit: DynamicLinks::ShorteningStrategies::RedisCounterStrategy::MAX_LENGTH
+      t.string :short_url, null: false, limit: 20
       t.datetime :expires_at
       t.timestamps
     end
-
-    add_index :dynamic_links_shortened_urls, :short_url, unique: true
   end
 end

data/db/migrate/20240128030329_fix_citus_index.rb

@@ -0,0 +1,34 @@
+class FixCitusIndex < ActiveRecord::Migration[7.1]
+  def up
+    if DynamicLinks.configuration.db_infra_strategy == :sharding
+      # execute SQL to remove primary key constraint
+      execute <<-SQL
+        ALTER TABLE dynamic_links_shortened_urls
+        DROP CONSTRAINT dynamic_links_shortened_urls_pkey;
+      SQL
+
+      execute <<-SQL
+        ALTER TABLE dynamic_links_shortened_urls
+        ADD PRIMARY KEY (id, client_id);
+      SQL
+      create_distributed_table :dynamic_links_shortened_urls, :client_id
+    end
+  end
+
+  # this code is untested
+  def down
+    if DynamicLinks.configuration.db_infra_strategy == :sharding
+      drop_distributed_table :dynamic_links_shortened_urls, :client_id
+
+      execute <<-SQL
+        ALTER TABLE dynamic_links_shortened_urls
+        DROP CONSTRAINT dynamic_links_shortened_urls_pkey;
+      SQL
+
+      execute <<-SQL
+        ALTER TABLE dynamic_links_shortened_urls
+        ADD PRIMARY KEY (id);
+      SQL
+    end
+  end
+end

data/db/migrate/20240128030419_add_unique_index_to_shortened_urls.rb

@@ -0,0 +1,5 @@
+class AddUniqueIndexToShortenedUrls < ActiveRecord::Migration[7.1]
+  def change
+    add_index :dynamic_links_shortened_urls, [:client_id, :short_url], unique: true
+  end
+end

data/lib/dynamic_links/async/locker.rb

@@ -0,0 +1,60 @@
+module DynamicLinks
+  module Async
+    # @author Saiqul Haq <saiqulhaq@gmail.com>
+    class Locker
+      LockAcquisitionError = Class.new(StandardError)
+      LockReleaseError = Class.new(StandardError)
+      attr_reader :cache_store
+
+      def initialize(cache_store = DynamicLinks.configuration.cache_store)
+        @cache_store = cache_store
+      end
+
+      def generate_lock_key(client, url)
+        "lock:shorten_url#{client.id}:#{url_to_lock_key(url)}"
+      end
+
+      def locked?(lock_key)
+        cache_store.exist?(lock_key)
+      end
+
+      # Acquires a lock for the given key and executes the block if lock is acquired.
+      # This method won't release the lock after block execution.
+      # We release the lock in the job after the job is done.
+      # @param [String] lock_key, it's better to use generate_lock_key method to generate lock_key
+      # @param [Integer] expires_in, default is 60 seconds
+      # @param [Block] block, the block to be executed if lock is acquired
+      # @return [Boolean]
+      def lock_if_absent(lock_key, expires_in: 60, &block)
+        is_locked = false
+        begin
+          is_locked = cache_store.increment(lock_key, 1, expires_in: expires_in) == 1
+          yield if is_locked && block_given?
+
+          unless is_locked
+            DynamicLinks::Logger.log_info "Unable to acquire lock for key: #{lock_key}"
+          end
+        rescue => e
+          DynamicLinks::Logger.log_error("Locking error: #{e.message}")
+          raise e
+        end
+
+        is_locked
+      end
+
+      # Deletes an entry in the cache. Returns true if an entry is deleted and false otherwise.
+      # @return [Boolean]
+      def unlock(lock_key)
+        deleted = cache_store.delete(lock_key)
+        raise LockReleaseError, "Unable to release lock for key: #{lock_key}" unless deleted
+        deleted
+      end
+
+      private
+
+      def url_to_lock_key(url)
+        Digest::SHA256.hexdigest(url)
+      end
+    end
+  end
+end

data/lib/dynamic_links/configuration.rb

@@ -1,10 +1,99 @@
 module DynamicLinks
+  # @author Saiqul Haq <saiqulhaq@gmail.com>
   class Configuration
-    attr_accessor :shortening_strategy
+    attr_reader :shortening_strategy, :enable_rest_api, :db_infra_strategy,
+                  :async_processing, :redis_counter_config, :cache_store,
+                  :enable_fallback_mode, :firebase_host
 
+    VALID_DB_INFRA_STRATEGIES = [:standard, :sharding].freeze
+
+    DEFAULT_SHORTENING_STRATEGY = :md5
+    DEFAULT_ENABLE_REST_API = true
+    DEFAULT_DB_INFRA_STRATEGY = :standard
+    DEFAULT_ASYNC_PROCESSING = false
+    DEFAULT_REDIS_COUNTER_CONFIG = RedisConfig.new
+    # use any class that extends ActiveSupport::Cache::Store, default is MemoryStore
+    DEFAULT_CACHE_STORE = ActiveSupport::Cache::MemoryStore.new
+    DEFAULT_ENABLE_FALLBACK_MODE = false
+    DEFAULT_FIREBASE_HOST = nil
+
+    # Usage:
+    #     DynamicLinks.configure do |config|
+    #       config.shortening_strategy = :md5 # or other strategy name, see StrategyFactory for available strategies
+    #       config.enable_rest_api = true # or false. when false, the API requests will be rejected
+    #       config.db_infra_strategy = :standard # or :sharding. if sharding is used, then xxx
+    #       config.async_processing = false # or true. if true, the shortening process will be done asynchronously using ActiveJob
+    #       config.redis_counter_config = RedisConfig.new # see RedisConfig documentation for more details
+    #       # if you use Redis
+    #       config.cache_store = ActiveSupport::Cache::RedisStore.new('redis://localhost:6379/0/cache')
+    #       # if you use Memcached
+    #       config.cache_store = ActiveSupport::Cache::MemCacheStore.new('localhost:11211')
+    #     end
+    #
+    # @return [Configuration]
     def initialize
-      @shortening_strategy = :MD5  # Default strategy
+      @shortening_strategy = DEFAULT_SHORTENING_STRATEGY
+      @enable_rest_api = DEFAULT_ENABLE_REST_API
+      @db_infra_strategy = DEFAULT_DB_INFRA_STRATEGY
+      @async_processing = DEFAULT_ASYNC_PROCESSING
+      # config for RedisCounterStrategy
+      @redis_counter_config = DEFAULT_REDIS_COUNTER_CONFIG
+      @cache_store = DEFAULT_CACHE_STORE
+      @enable_fallback_mode = DEFAULT_ENABLE_FALLBACK_MODE
+      @firebase_host = DEFAULT_FIREBASE_HOST
+    end
+
+    def shortening_strategy=(strategy)
+      raise ArgumentError, "Invalid shortening strategy" unless StrategyFactory::VALID_SHORTENING_STRATEGIES.include?(strategy)
+      @shortening_strategy = strategy
+    end
+
+    def enable_rest_api=(value)
+      raise ArgumentError, "enable_rest_api must be a boolean" unless [true, false].include?(value)
+      @enable_rest_api = value
+    end
+
+    def db_infra_strategy=(strategy)
+      raise ArgumentError, "Invalid DB infra strategy" unless VALID_DB_INFRA_STRATEGIES.include?(strategy)
+      @db_infra_strategy = strategy
+    end
+
+    def async_processing=(value)
+      raise ArgumentError, "async_processing must be a boolean" unless [true, false].include?(value)
+      @async_processing = value
+    end
+
+    def redis_counter_config=(config)
+      raise ArgumentError, "redis_counter_config must be an instance of RedisConfig" unless config.is_a?(RedisConfig)
+      @redis_counter_config = config
+    end
+
+    def cache_store=(store)
+      raise ArgumentError, "cache_store must be an instance of ActiveSupport::Cache::Store" unless store.is_a?(ActiveSupport::Cache::Store)
+      @cache_store = store
+    end
+
+    def enable_fallback_mode=(value)
+      raise ArgumentError, "enable_fallback_mode must be a boolean" unless [true, false].include?(value)
+      @enable_fallback_mode = value
+    end
+
+    def firebase_host=(host)
+      # allow nil or blank host (optional, depends on your app logic)
+      if host.nil? || host.strip.empty?
+        @firebase_host = nil
+        return
+      end
+
+      begin
+        uri = URI.parse(host.to_s)
+        valid = uri.is_a?(URI::HTTP) && uri.host.present?
+        raise unless valid
+      rescue
+        raise ArgumentError, "firebase_host must be a valid URL with a host"
+      end
+
+      @firebase_host = host
     end
   end
 end
-

data/lib/dynamic_links/error_classes.rb

@@ -0,0 +1,6 @@
+module DynamicLinks
+  class InvalidURIError < ::URI::InvalidURIError; end
+  class ConfigurationError < StandardError; end
+  class MissingDependency < LoadError; end
+  class ShorteningFailed < StandardError; end
+end

data/lib/dynamic_links/logger.rb

@@ -0,0 +1,32 @@
+module DynamicLinks
+  # @author Saiqul Haq <saiqulhaq@gmail.com>
+  class Logger
+    def self.instance
+      @logger ||= Rails.logger
+    end
+
+    def self.log_info(message)
+      instance.info(message)
+    end
+
+    def self.log_error(message)
+      instance.error(message)
+    end
+
+    def self.log_warn(message)
+      instance.warn(message)
+    end
+
+    def self.log_debug(message)
+      instance.debug(message)
+    end
+
+    def self.log_fatal(message)
+      instance.fatal(message)
+    end
+
+    def self.log_unknown(message)
+      instance.unknown(message)
+    end
+  end
+end

data/lib/dynamic_links/redis_config.rb

@@ -0,0 +1,22 @@
+# @author Saiqul Haq <saiqulhaq@gmail.com>
+
+module DynamicLinks
+  # RedisConfig is a class to hold Redis configuration
+  class RedisConfig
+    attr_accessor :config, :pool_size, :pool_timeout
+
+    # @param [Hash] config
+    # Default to an empty hash, can be overridden
+    #    config = {
+    #      host: 'localhost',
+    #      port: 6379
+    #    }
+    # @param [Integer] pool_size Default to 5, can be overridden
+    # @param [Integer] pool_timeout Default to 5, can be overridden
+    def initialize(config = {}, pool_size = 5, pool_timeout = 5)
+      @config = config
+      @pool_size = pool_size
+      @pool_timeout = pool_timeout
+    end
+  end
+end

data/lib/dynamic_links/shortener.rb

@@ -0,0 +1,52 @@
+module DynamicLinks
+  # @author Saiqul Haq <saiqulhaq@gmail.com>
+  class Shortener
+    attr_reader :locker, :strategy, :storage, :async_worker
+
+    def initialize(locker: DynamicLinks::Async::Locker.new,
+                   strategy: StrategyFactory.get_strategy(DynamicLinks.configuration.shortening_strategy),
+                   storage: ShortenedUrl,
+                   async_worker: ShortenUrlJob)
+      @locker = locker
+      @strategy = strategy
+      @storage = storage
+      @async_worker = async_worker
+    end
+
+    # @param client [Client] the client that owns the url
+    # @param url [String] the url to be shortened
+    # @return [String] the shortened url
+    def shorten(client, url)
+      short_url = strategy.shorten(url)
+
+      if strategy.always_growing?
+        storage.create!(client: client, url: url, short_url: short_url)
+      else
+        storage.find_or_create!(client, short_url, url)
+      end
+      URI::Generic.build({scheme: client.scheme, host: client.hostname, path: "/#{short_url}"}).to_s
+    rescue => e
+      DynamicLinks::Logger.log_error("Error shortening URL: #{e.message}")
+      raise e
+    end
+
+    # @param client [Client] the client that owns the url
+    # @param url [String] the url to be shortened
+    def shorten_async(client, url)
+      lock_key = locker.generate_lock_key(client, url)
+
+      locker.lock_if_absent(lock_key) do
+        short_url = strategy.shorten(url)
+        content = {
+          url: url,
+          short_url: short_url
+        }
+
+        async_worker.perform_later(client, url, short_url, lock_key)
+      end
+    rescue => e
+      DynamicLinks::Logger.log_error("Error shortening URL asynchronously: #{e.message}")
+      raise e
+    end
+  end
+end

data/lib/dynamic_links/shortening_strategies/base_strategy.rb

@@ -9,6 +9,12 @@ module DynamicLinks
         raise NotImplementedError, "You must implement the shorten method"
       end
 
+      # Determines if the strategy always generates a new shortened URL
+      # @return [Boolean]
+      def always_growing?
+        false  # Default behavior is not to always grow
+      end
+
       private
 
       # Convert an integer into a Base62 string

data/lib/dynamic_links/shortening_strategies/nano_id_strategy.rb

@@ -3,17 +3,15 @@ module DynamicLinks
     # Shortens the given URL using Nano ID
     # This strategy will generate a different short URL for the same given URL
     class NanoIDStrategy < BaseStrategy
-      begin
-        require 'nanoid'
-      rescue LoadError
-        raise 'Missing dependency: Please add "nanoid" to your Gemfile to use NanoIdStrategy.'
-      end
-
       # Shortens the given URL using Nano ID
       # @param url [String] The URL to shorten (not directly used in Nano ID strategy)
-      # @param size [Integer] The size (length) of the generated Nano ID
-      def shorten(url, size: MIN_LENGTH)
-        ::Nanoid.generate(size: size)
+      # @param min_length [Integer] The size (length) of the generated Nano ID
+      def shorten(url, min_length: MIN_LENGTH)
+        ::Nanoid.generate(size: min_length)
+      end
+
+      def always_growing?
+        true  # This strategy always generates a new shortened URL
       end
     end
   end

data/lib/dynamic_links/shortening_strategies/redis_counter_strategy.rb

@@ -1,29 +1,40 @@
-
 module DynamicLinks
   module ShorteningStrategies
+    # usage:
+    # Using default configuration from DynamicLinks configuration
+    # default_strategy = DynamicLinks::ShorteningStrategies::RedisCounterStrategy.new
+    #
+    # Using a custom configuration
+    # custom_redis_config = { host: 'custom-host', port: 6380 }
+    # custom_strategy = DynamicLinks::ShorteningStrategies::RedisCounterStrategy.new(custom_redis_config)
     class RedisCounterStrategy < BaseStrategy
-      begin
-        require 'redis'
-      rescue LoadError
-        raise 'Missing dependency: Please add "redis" to your Gemfile to use RedisCounterStrategy.'
-      end
-
       MIN_LENGTH = 12
       REDIS_COUNTER_KEY = "dynamic_links:counter".freeze
 
-      def initialize
-        # TODO: use pool of connections
-        @redis = Redis.new
+      # @param redis_config [Hash]
+      def initialize(redis_config = nil)
+        super()
+
+        configuration = redis_config.nil? ? DynamicLinks.configuration.redis_counter_config : DynamicLinks::Configuration::RedisConfig.new(redis_config)
+        @redis = ConnectionPool.new(size: configuration.pool_size, timeout: configuration.pool_timeout) do
+          Redis.new(configuration.config)
+        end
+      end
+
+      def always_growing?
+        true  # This strategy always generates a new shortened URL
       end
 
       # Shortens the given URL using a Redis counter
       # @param url [String] The URL to shorten
       # @return [String] The shortened URL, 12 characters long
       def shorten(url, min_length: MIN_LENGTH)
-        counter = @redis.incr(REDIS_COUNTER_KEY)
-
-        short_url = base62_encode("#{counter}#{url.hash.abs}".to_i)
-        short_url.ljust(min_length, '0')
+        @redis.with do |conn|
+          counter = conn.incr(REDIS_COUNTER_KEY)
+          short_url = base62_encode("#{counter}#{url.hash.abs}".to_i)
+          short_url = short_url.ljust(min_length, '0')
+          short_url
+        end
       end
     end
   end

data/lib/dynamic_links/strategy_factory.rb

@@ -1,5 +1,8 @@
 module DynamicLinks
   class StrategyFactory
+    VALID_SHORTENING_STRATEGIES = [:md5, :sha256, :crc32,
+                                   :nano_id, :redis_counter, :mock].freeze
+
     def self.get_strategy(strategy_name)
       case strategy_name
       when :md5
@@ -9,8 +12,10 @@ module DynamicLinks
       when :crc32
         ShorteningStrategies::CRC32Strategy.new
       when :nano_id
-        ShorteningStrategies::NanoIdStrategy.new
+        ensure_nanoid_available
+        ShorteningStrategies::NanoIDStrategy.new
       when :redis_counter
+        ensure_redis_available
         ShorteningStrategies::RedisCounterStrategy.new
       when :mock
         ShorteningStrategies::MockStrategy.new
@@ -18,6 +23,28 @@ module DynamicLinks
         raise "Unknown strategy: #{strategy_name}"
       end
     end
+
+    def self.ensure_nanoid_available
+      begin
+        require 'nanoid'
+      rescue LoadError
+        raise 'Missing dependency: Please add "nanoid" to your Gemfile to use NanoIdStrategy.'
+      end
+    end
+
+    def self.ensure_redis_available
+      begin
+        require 'redis'
+      rescue LoadError
+        raise 'Missing dependency: Please add "redis" to your Gemfile to use RedisCounterStrategy.'
+      end
+
+      begin
+        require 'connection_pool'
+      rescue LoadError
+        raise 'Missing dependency: Please add "connection_pool" to your Gemfile to use RedisCounterStrategy.'
+      end
+    end
   end
 end
 

data/lib/dynamic_links/validator.rb

@@ -0,0 +1,14 @@
+module DynamicLinks
+  class Validator
+    # Validates if the given URL is a valid HTTP or HTTPS URL
+    # @param url [String] The URL to validate
+    # @return [Boolean] true if valid, false otherwise
+    def self.valid_url?(url)
+      uri = URI.parse(url)
+      uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end
+

data/lib/dynamic_links/version.rb

@@ -1,3 +1,3 @@
 module DynamicLinks
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/dynamic_links.rb

@@ -1,5 +1,31 @@
+# @author Saiqul Haq <saiqulhaq@gmail.com>
+
+if ENV['RAILS_ENV'] == 'test'
+  require 'simplecov'
+
+  SimpleCov.start do
+    load_profile "test_frameworks"
+
+    add_filter %r{^/config/}
+    add_filter %r{^/db/}
+
+    add_group "Controllers", "app/controllers"
+    add_group "Channels", "app/channels"
+    add_group "Models", "app/models"
+    add_group "Mailers", "app/mailers"
+    add_group "Helpers", "app/helpers"
+    add_group "Jobs", %w[app/jobs app/workers]
+    add_group "DynamicLinks", "lib/"
+  end
+end
+
 require "dynamic_links/version"
 require "dynamic_links/engine"
+require "dynamic_links/logger"
+require "dynamic_links/error_classes"
+require "dynamic_links/redis_config"
+require "dynamic_links/configuration"
+require "dynamic_links/validator"
 require "dynamic_links/strategy_factory"
 require "dynamic_links/shortening_strategies/base_strategy"
 require "dynamic_links/shortening_strategies/sha256_strategy"
@@ -8,7 +34,8 @@ require "dynamic_links/shortening_strategies/crc32_strategy"
 require "dynamic_links/shortening_strategies/nano_id_strategy"
 require "dynamic_links/shortening_strategies/redis_counter_strategy"
 require "dynamic_links/shortening_strategies/mock_strategy"
-require "dynamic_links/configuration"
+require "dynamic_links/async/locker"
+require "dynamic_links/shortener"
 
 module DynamicLinks
   class << self
@@ -23,26 +50,20 @@ module DynamicLinks
     end
   end
 
-  def self.shorten_url(url)
-    strategy_key = configuration.shortening_strategy
-
-    begin
-      strategy = StrategyFactory.get_strategy(strategy_key)
-    rescue RuntimeError => e
-      # This will catch the 'Unknown strategy' error from the factory
-      raise "Invalid shortening strategy: #{strategy_key}. Error: #{e.message}"
-    rescue ArgumentError
-      raise "#{strategy_key} strategy needs to be initialized with arguments"
-    rescue => e
-      raise "Unexpected error while initializing the strategy: #{e.message}"
-    end
+  def self.shorten_url(url, client, async: DynamicLinks.configuration.async_processing)
+    raise InvalidURIError, 'Invalid URL' unless Validator.valid_url?(url)
 
-    strategy.shorten(url)
+    shortener = Shortener.new
+    if async
+      shortener.shorten_async(client, url)
+    else
+      shortener.shorten(client, url)
+    end
   end
 
   # mimic Firebase Dynamic Links API
-  def self.generate_short_url(original_url)
-    short_link = shorten_url(original_url)
+  def self.generate_short_url(original_url, client)
+    short_link = shorten_url(original_url, client)
 
     {
       shortLink: short_link,
@@ -50,4 +71,8 @@ module DynamicLinks
       warning: []
     }
   end
+
+  def self.resolve_short_url(short_link)
+    DynamicLinks::ShortenedUrl.find_by(short_url: short_link)&.url
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dynamic_links
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Saiqul Haq
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-01 00:00:00.000000000 Z
+date: 2025-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,20 +27,29 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '8'
 - !ruby/object:Gem::Dependency
   name: nanoid
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -45,6 +57,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -52,34 +67,63 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
 - !ruby/object:Gem::Dependency
   name: annotate
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: dotenv-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: Rails engine to shorten any URL with custom domain.
 email:
 - saiqulhaq@gmail.com
@@ -87,15 +131,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- MIT-LICENSE
 - README.md
 - Rakefile
 - app/assets/config/dynamic_links_manifest.js
 - app/assets/stylesheets/dynamic_links/application.css
 - app/controllers/dynamic_links/application_controller.rb
+- app/controllers/dynamic_links/redirects_controller.rb
 - app/controllers/dynamic_links/v1/short_links_controller.rb
 - app/helpers/dynamic_links/application_helper.rb
 - app/jobs/dynamic_links/application_job.rb
 - app/jobs/dynamic_links/generate_short_links_job.rb
+- app/jobs/dynamic_links/shorten_url_job.rb
 - app/mailers/dynamic_links/application_mailer.rb
 - app/models/dynamic_links/application_record.rb
 - app/models/dynamic_links/client.rb
@@ -104,9 +152,16 @@ files:
 - config/routes.rb
 - db/migrate/20231228165744_create_dynamic_links_clients.rb
 - db/migrate/20231228175142_create_dynamic_links_shortened_urls.rb
+- db/migrate/20240128030329_fix_citus_index.rb
+- db/migrate/20240128030419_add_unique_index_to_shortened_urls.rb
 - lib/dynamic_links.rb
+- lib/dynamic_links/async/locker.rb
 - lib/dynamic_links/configuration.rb
 - lib/dynamic_links/engine.rb
+- lib/dynamic_links/error_classes.rb
+- lib/dynamic_links/logger.rb
+- lib/dynamic_links/redis_config.rb
+- lib/dynamic_links/shortener.rb
 - lib/dynamic_links/shortening_strategies/base_strategy.rb
 - lib/dynamic_links/shortening_strategies/crc32_strategy.rb
 - lib/dynamic_links/shortening_strategies/md5_strategy.rb
@@ -115,17 +170,19 @@ files:
 - lib/dynamic_links/shortening_strategies/redis_counter_strategy.rb
 - lib/dynamic_links/shortening_strategies/sha256_strategy.rb
 - lib/dynamic_links/strategy_factory.rb
+- lib/dynamic_links/validator.rb
 - lib/dynamic_links/version.rb
 - lib/generators/dynamic_links/add_kgs_migration_generator.rb
 - lib/generators/dynamic_links/templates/migration_template.rb
 - lib/tasks/dynamic_links_tasks.rake
 homepage: https://saiqulhaq.id/dynamic_links
-licenses: []
+licenses:
+- MIT
 metadata:
   homepage_uri: https://saiqulhaq.id/dynamic_links
   source_code_uri: https://github.com/saiqulhaq/dynamic_links
   changelog_uri: https://github.com/saiqulhaq/dynamic_links/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -133,15 +190,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Alternative to Firebase Dynamic Links feature
 test_files: []