DynamicLinks

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 and other settings in an initializer or before you start shortening URLs.

Configuration

In your Rails initializer or similar setup code, configure DynamicLinks like this:

DynamicLinks.configure do |config|
  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
2. Install VS Code
3. Install the Remote - Containers extension

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. 4. Access the application at the forwarded port (usually port 3000)

Shortening a URL

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:

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:

{
  "full_url": "https://example.com/original-path"
}

If the URL is not found, you'll receive a 404 status code with an error message:

{
  "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:

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 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, 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.

Installation

Add this line to your application's Gemfile:

gem "dynamic_links"

And then execute:

$ bundle

Or install it yourself as:

$ gem install dynamic_links

Performance

Shorten an URL using Ruby: Shorten an URL using API:

How to run the unit test

When using a Plain PostgreSQL DB

rails db:setup
rails db:test:prepare
rails test

When using PostgreSQL DB with Citus

export CITUS_ENABLED=true
rails db:setup
rails db:test:prepare
rails test

Note: Make sure the Citus extension already enabled on the installed PostgreSQL We don't manage it on Rails.

License

The gem is available as open source under the terms of the MIT License.