dynamic_links 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7f8c21c9c9432cdd2ed12ddc9e86a79b8f3024a240a406bba89157478520c9d
-  data.tar.gz: 30e2a4084f34977c4e267aa940454e53978ad193d99214312f90b6ee948fda2d
+  metadata.gz: 191decc937ca3ca35b6911558962c6ecea550a22e8032c907f01d1098aced607
+  data.tar.gz: 6f983f6713bc399e51fb5990fa888e7a2165b21ed09ec00097d99ee92173ba7e
 SHA512:
-  metadata.gz: 1deecaad47165bae46df566e68661bc77444aa36d143084d7e1a6aa76d05958e9183b1f88a9a083813404778e9f305d8588887a1558b8d8f98c1ec66c1c07e10
-  data.tar.gz: bc0572b2ce3274ada41824867284e47d82263db2b2e2c323c8306f1c5487cd30040fe3b677b950880d17b026a997daa3907bbd060d3fdda3db83076f1566fbe3
+  metadata.gz: 55a751b1dc66a5687d91e430888efd4f96f83ad6e227dca63a1e2c571958131640eae71b5524ebf50e4330c2f9bb6f803dfa28cf413f607aee23f682bd18ff6c
+  data.tar.gz: 261cc6051c78d7a736c560fbc5ffa14eac49c3f0b031a8f1f516b5bbd1fa181f5d26b391fe819c23ef05b6d1c77fe2ae49f7867bef5f7aaf86a2cf387135fa51

data/CHANGELOG.md

@@ -4,6 +4,15 @@ 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)

data/README.md

@@ -88,57 +88,150 @@ To shorten a URL, simply call:
 shortened_url = DynamicLinks.shorten_url("https://example.com")
 ```
 
-### Expanding a Short URL
+### Finding an Existing Short Link
 
-To expand (resolve) a short URL back to its original URL, use the `resolve_short_url` method:
+To find an existing short link for a URL:
 
 ```ruby
-original_url = DynamicLinks.resolve_short_url("abc123")
-# Returns the original URL or nil if not found
+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
 ```
 
-#### Using the REST API to Expand URLs
+## 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"
+  }'
+```
 
-The gem also provides a REST API endpoint to expand short URLs:
+**Example Response:**
 
+```json
+{
+  "shortLink": "https://your-domain.com/abc123",
+  "previewLink": "https://your-domain.com/abc123?preview=true",
+  "warning": []
+}
 ```
-GET /v1/shortLinks/:short_url?api_key=YOUR_API_KEY
+
+#### 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:
+**Example Response (existing link found):**
 
 ```json
 {
-  "full_url": "https://example.com/original-path"
+  "shortLink": "https://your-domain.com/abc123",
+  "previewLink": "https://your-domain.com/abc123?preview=true",
+  "warning": []
 }
 ```
 
-If the URL is not found, you'll receive a 404 status code with an error message:
+**Example Response (new link created):**
 
 ```json
 {
-  "error": "Short link not found"
+  "shortLink": "https://your-domain.com/def456",
+  "previewLink": "https://your-domain.com/def456?preview=true",
+  "warning": []
 }
 ```
 
-## Fallback Mode
+#### Expand Short Link
 
-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.
+Retrieves the original URL from a short link.
 
-To enable this feature:
+**Endpoint:** `GET /v1/shortLinks/{short_url}`
 
-```ruby
-DynamicLinks.configure do |config|
-  config.enable_fallback_mode = true
-  config.firebase_host = "https://your-app.page.link"  # Your Firebase Dynamic Links URL
-end
+**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"
+}
 ```
 
-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.
+### 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 now `NanoIdStrategy` (changed from `MD5` in PR #88), but you can choose among several others, including `MD5Strategy`, `RedisCounterStrategy`, `Sha256Strategy`, and more.
+DynamicLinks supports various shortening strategies. The default strategy is `MD5`, but you can choose among several others, including `NanoIdStrategy`, `RedisCounterStrategy`, `Sha256Strategy`, and more.
 
 Depending on the strategy you choose, you may need to install additional dependencies.
 
@@ -171,8 +264,13 @@ $ gem install dynamic_links
 
 ## Performance
 
-Shorten an URL using Ruby:
-Shorten an URL using API:
+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
 

data/app/controllers/dynamic_links/application_controller.rb

@@ -7,7 +7,9 @@ module DynamicLinks
             yield
           end
         else
-          Rails.logger.warn 'MultiTenant gem is not installed. Please install it to use sharding strategy'
+          # 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

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

@@ -4,7 +4,7 @@ module DynamicLinks
 
     def create
       url = params.require(:url)
-      client = DynamicLinks::Client.find_by({ api_key: params.require(:api_key) })
+      client = DynamicLinks::Client.find_by(api_key: params.require(:api_key))
 
       unless client
         render json: { error: 'Invalid API key' }, status: :unauthorized
@@ -23,7 +23,7 @@ module DynamicLinks
 
     def expand
       api_key = params.require(:api_key)
-      client = DynamicLinks::Client.find_by({ api_key: api_key })
+      client = DynamicLinks::Client.find_by(api_key: api_key)
 
       unless client
         render json: { error: 'Invalid API key' }, status: :unauthorized
@@ -45,6 +45,38 @@ module DynamicLinks
       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
@@ -52,5 +84,12 @@ module DynamicLinks
         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/config/routes.rb

@@ -5,6 +5,7 @@ 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/lib/dynamic_links/configuration.rb

@@ -25,7 +25,7 @@ module DynamicLinks
     #       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')
+    #       config.cache_store = ActiveSupport::Cache::RedisCacheStore.new(url: 'redis://localhost:6379/0/cache')
     #       # if you use Memcached
     #       config.cache_store = ActiveSupport::Cache::MemCacheStore.new('localhost:11211')
     #     end
@@ -44,7 +44,10 @@ module DynamicLinks
     end
 
     def shortening_strategy=(strategy)
-      raise ArgumentError, "Invalid shortening strategy" unless StrategyFactory::VALID_SHORTENING_STRATEGIES.include?(strategy)
+      unless StrategyFactory::VALID_SHORTENING_STRATEGIES.include?(strategy)
+        raise ArgumentError, "Invalid shortening strategy, provided strategy: #{strategy}. Valid strategies are: #{StrategyFactory::VALID_SHORTENING_STRATEGIES.join(', ')}" 
+      end
+
       @shortening_strategy = strategy
     end
 

data/lib/dynamic_links/version.rb

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

data/lib/dynamic_links.rb

@@ -75,4 +75,16 @@ module DynamicLinks
   def self.resolve_short_url(short_link)
     DynamicLinks::ShortenedUrl.find_by(short_url: short_link)&.url
   end
+
+  def self.find_short_link(long_url, client)
+    short_link = DynamicLinks::ShortenedUrl.find_by(url: long_url, client_id: client.id)
+    if short_link
+      {
+        short_url: "#{client.scheme}://#{client.hostname}/#{short_link.short_url}",
+        full_url: long_url
+      }
+    else
+      nil
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dynamic_links
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Saiqul Haq
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-17 00:00:00.000000000 Z
+date: 2025-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails