dynamic_links 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8be4269ba92cfbec08c29ec6a6a871383b8470736057204fa24234ebfc70a98
-  data.tar.gz: 90a2df3615def525638fc53eeb23eef0a367d0137993b6303630d7d868ac3443
+  metadata.gz: 191decc937ca3ca35b6911558962c6ecea550a22e8032c907f01d1098aced607
+  data.tar.gz: 6f983f6713bc399e51fb5990fa888e7a2165b21ed09ec00097d99ee92173ba7e
 SHA512:
-  metadata.gz: 3ca6e9c92116542c9df6895e861843c03e951cb7e87bf567bc189b4811f8fb6cf95e097123b4569843ea18f8780289e1bec70b2de2a8bd92532f929277e0578e
-  data.tar.gz: 50e65b566b1b36f9b169f0a7c35610720027f030c31d4fd7fe861ee077ea1b5c043391a51caf4f34c612f13456fdcf16cbb95d39a019c69f65bb2676bc2d7fd7
+  metadata.gz: 55a751b1dc66a5687d91e430888efd4f96f83ad6e227dca63a1e2c571958131640eae71b5524ebf50e4330c2f9bb6f803dfa28cf413f607aee23f682bd18ff6c
+  data.tar.gz: 261cc6051c78d7a736c560fbc5ffa14eac49c3f0b031a8f1f516b5bbd1fa181f5d26b391fe819c23ef05b6d1c77fe2ae49f7867bef5f7aaf86a2cf387135fa51

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.3.0] - 2025-07-25
+
+- [#101](https://github.com/saiqulhaq/dynamic_links/pull/101)
+
+  - New Feature: Added `find_or_create` REST API endpoint that finds existing short links or creates new ones
+  - New Feature: Added `DynamicLinks.find_short_link` method to search for existing short links by URL and client
+  - Enhancement: Improved URL validation in REST API controllers with dedicated `valid_url?` method
+  - Enhancement: Code cleanup - removed unnecessary hash brackets in `find_by` calls
+
+## [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,6 +88,147 @@ To shorten a URL, simply call:
 shortened_url = DynamicLinks.shorten_url("https://example.com")
 ```
 
+### Finding an Existing Short Link
+
+To find an existing short link for a URL:
+
+```ruby
+short_link_data = DynamicLinks.find_short_link("https://example.com", client)
+if short_link_data
+  puts short_link_data[:short_url]  # e.g., "https://client.com/abc123"
+  puts short_link_data[:full_url]   # e.g., "https://example.com"
+else
+  puts "No existing short link found"
+end
+```
+
+## REST API
+
+DynamicLinks provides a REST API for URL shortening operations when `enable_rest_api` is set to `true` in the configuration.
+
+### Authentication
+
+All API endpoints require an `api_key` parameter that corresponds to a registered client.
+
+### Endpoints
+
+#### Create Short Link
+
+Creates a new short link for a URL.
+
+**Endpoint:** `POST /v1/shortLinks`
+
+**Parameters:**
+
+- `url` (required): The URL to shorten
+- `api_key` (required): Client API key
+
+**Example Request:**
+
+```bash
+curl -X POST "http://localhost:3000/v1/shortLinks" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com/long-url",
+    "api_key": "your-api-key"
+  }'
+```
+
+**Example Response:**
+
+```json
+{
+  "shortLink": "https://your-domain.com/abc123",
+  "previewLink": "https://your-domain.com/abc123?preview=true",
+  "warning": []
+}
+```
+
+#### Find or Create Short Link
+
+Finds an existing short link for a URL, or creates a new one if none exists. This prevents duplicate short links for the same URL and client.
+
+**Endpoint:** `POST /v1/shortLinks/findOrCreate`
+
+**Parameters:**
+
+- `url` (required): The URL to find or shorten
+- `api_key` (required): Client API key
+
+**Example Request:**
+
+```bash
+curl -X POST "http://localhost:3000/v1/shortLinks/findOrCreate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com/long-url",
+    "api_key": "your-api-key"
+  }'
+```
+
+**Example Response (existing link found):**
+
+```json
+{
+  "shortLink": "https://your-domain.com/abc123",
+  "previewLink": "https://your-domain.com/abc123?preview=true",
+  "warning": []
+}
+```
+
+**Example Response (new link created):**
+
+```json
+{
+  "shortLink": "https://your-domain.com/def456",
+  "previewLink": "https://your-domain.com/def456?preview=true",
+  "warning": []
+}
+```
+
+#### Expand Short Link
+
+Retrieves the original URL from a short link.
+
+**Endpoint:** `GET /v1/shortLinks/{short_url}`
+
+**Parameters:**
+
+- `short_url` (in URL): The short URL code to expand
+- `api_key` (required): Client API key
+
+**Example Request:**
+
+```bash
+curl "http://localhost:3000/v1/shortLinks/abc123?api_key=your-api-key"
+```
+
+**Example Response:**
+
+```json
+{
+  "url": "https://example.com/long-url"
+}
+```
+
+### Error Responses
+
+The API returns appropriate HTTP status codes and error messages:
+
+- `400 Bad Request`: Invalid URL format
+- `401 Unauthorized`: Invalid or missing API key
+- `403 Forbidden`: REST API feature is disabled
+- `404 Not Found`: Short link not found (expand endpoint)
+- `500 Internal Server Error`: Server error
+
+**Example Error Response:**
+
+```json
+{
+  "error": "Invalid URL"
+}
+```
+
 ## 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.
@@ -33,7 +238,7 @@ Depending on the strategy you choose, you may need to install additional depende
 ### 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 +262,38 @@ Or install it yourself as:
 $ gem install dynamic_links
 ```
 
-## Contributing
+## Performance
+
+Benchmarking scripts are available in the `benchmarks/` directory to measure performance:
+
+- `ruby_api.rb`: Benchmarks Ruby API URL shortening performance
+- `rest_api.py`: Benchmarks REST API URL shortening performance
+- `create_or_find.rb`: Compares performance of different `create_or_find` methods
+
+You can run these benchmarks to measure performance in your specific environment.
+
+## 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,20 @@
 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'
+          DynamicLinks::Logger.log_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,95 @@
-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
+
+    def find_or_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
+
+      unless valid_url?(url)
+        render json: { error: 'Invalid URL' }, status: :bad_request
+        return
+      end
+
+      multi_tenant(client) do
+        short_link = DynamicLinks.find_short_link(url, client)
+
+        if short_link
+          render json: {
+            shortLink: short_link[:short_url],
+            previewLink: "#{short_link[:short_url]}?preview=true",
+            warning: []
+          }, status: :ok
+        else
+          render json: DynamicLinks.generate_short_url(url, client), status: :created
+        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
+
+    def valid_url?(url)
+      uri = URI.parse(url)
+      uri.is_a?(URI::HTTP) && uri.host.present? && uri.scheme.present?
+    rescue URI::InvalidURIError
+      false
+    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,10 @@
 #
 
 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
+    post "/shortLinks/findOrCreate", to: "short_links#find_or_create", as: :find_or_create_short_link
+    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