Skip to content
kg8mPublic

About

A Rails engine for shortening URLs

Topics

Resources

Stars

6 stars

Watchers

1 watching

Forks

Repository files navigation

RubyGems.org Ruby 2.5+ Rails 5.1+ MIT License Checks

Tanshuku

Tanshuku is a simple and small Rails engine that makes it easier to shorten URLs.

Key Features

  • Generates a unique key for a URL.
    • The uniqueness is ensured at database level.
  • Creates no additional shortened URL record if the given URL has already been shortened.
    • You can create an additional record for the same URL with using a different namespace from existing records’.
    • Checks its existence considering the performance.
  • Provides a Rails controller and action for finding a shortened URL record and redirecting to its original, i.e., non-shortened, URL.
    • The redirection is done with 301 HTTP status.

Usage

1. Mount Tanshuku::Engine

For example, the following code generates a routing GET `/t/:key` to `Tanshuku::UrlsController#show`. When your Rails app receives a request to /t/abcdefghij0123456789, Tanshuku::UrlsController#show will be called and a Tanshuku::Url record with a key abcdefghij0123456789 will be found. Then the request will be redirected to the Tanshuku::Url record’s original URL.

# config/routes.rb
Rails.application.routes.draw do
  mount Tanshuku::Engine, at: "/t"
end

Note: You can customize the path /t as you like.

2. Configure Tanshuku (Optional)

Note: This step is optional.

Note: An initializer file for configuration can be generated by bin/rails generate tanshuku:install. See the “Installation” section below for more information.

Note: Mutating a Tanshuku::Configuration object is thread-unsafe. It is recommended to use Tanshuku.configure for configuration.

config.default_url_options

Tanshuku uses configured config.default_url_options when generating shortened URLs.

Default value is {}.

The following example means that the configured host and protocol are used. Shortened URLs will be like https://example.com/t/abcdefghij0123456789.

# config/initializers/tanshuku.rb
Tanshuku.configure do |config|
  config.default_url_options = { host: "example.com", protocol: :https }
end

config.exception_reporter

If an exception occurs when shortening a URL, Tanshuku reports it with configured config.exception_reporter object.

Default value is Tanshuku::Configuration::DefaultExceptionReporter. It logs the exception and the original URL with Rails.logger.warn.

Value of config.exception_reporter should respond to #call with keyword arguments exception: and original_url:.

The following example means that an exception and a URL will be reported to Sentry.

# config/initializers/tanshuku.rb
Tanshuku.configure do |config|
  config.exception_reporter =
    lambda { |exception:, original_url:|
      Sentry.capture_exception(exception, tags: { original_url: })
    }
end

More information

cf. Tanshuku::Configuration’s API documentation

3. Generate shortened URLs

Basic cases

You can generate a shortened URL with Tanshuku::Url.shorten. For example:

Tanshuku::Url.shorten("https://google.com/")  #=> "https://example.com/t/abcdefghij0123456789"

config.default_url_options is used for the shortened URL.

Note: If a Tanshuku::Url record for the given URL already exists, no additional record will be created and always the existing record is used.

# When no record exists for "https://google.com/", a new record will be created.
Tanshuku::Url.shorten("https://google.com/")  #=> "https://example.com/t/abcde0123456789fghij"

# When a record already exists for "https://google.com/", no additional record will be created.
Tanshuku::Url.shorten("https://google.com/")  #=> "https://example.com/t/abcde0123456789fghij"
Tanshuku::Url.shorten("https://google.com/")  #=> "https://example.com/t/abcde0123456789fghij"
Tanshuku::Url.shorten("https://google.com/")  #=> "https://example.com/t/abcde0123456789fghij"

Shortening a URL with ad hoc URL options

You can specify URL options to Tanshuku::Url.shorten. For example:

Tanshuku::Url.shorten("https://google.com/", url_options: { host: "verycool.example.com" })
#=> "https://verycool.example.com/t/0123456789abcdefghij"

Tanshuku::Url.shorten("https://google.com/", url_options: { protocol: :http })
#=> "http://example.com/t/abcde01234fghij56789"

Shortening a URL with a namespace

You can create additional records for the same URL with specifying a namespace.

# When no record exists for “https://google.com/”, a new record will be created.
Tanshuku::Url.shorten("https://google.com/")  #=> "https://example.com/t/abc012def345ghi678j9"

# Even when a record already exists for “https://google.com/”, an additional record will be created if namespace is
# specified.
Tanshuku::Url.shorten("https://google.com/", namespace: "a")  #=> "https://example.com/t/ab01cd23ef45gh67ij89"
Tanshuku::Url.shorten("https://google.com/", namespace: "b")  #=> "https://example.com/t/a0b1c2d3e4f5g6h7i8j9"
Tanshuku::Url.shorten("https://google.com/", namespace: "c")  #=> "https://example.com/t/abcd0123efgh4567ij89"

# When the same URL and the same namespace is specified, no additional record will be created.
Tanshuku::Url.shorten("https://google.com/", namespace: "a")  #=> "https://example.com/t/ab01cd23ef45gh67ij89"
Tanshuku::Url.shorten("https://google.com/", namespace: "a")  #=> "https://example.com/t/ab01cd23ef45gh67ij89"

Security considerations

Shortening URLs that contain secrets

You can shorten URLs that contain secrets such as access tokens, but be aware of the following risks.

  • Original URLs are stored in the tanshuku_urls table as plain text. Anyone who can read the database or its backups can see the secrets.
  • Anyone who knows a shortened URL can access its original URL. Shortened URLs tend to spread through sharing and forwarding.
  • When shortening a URL fails, the default config.exception_reporter logs the original URL as is.

If you want to keep secrets out of your logs, configure config.exception_reporter. The following example filters query parameters of the original URL with your app’s config.filter_parameters and removes its fragment before logging it. If the URL can’t be parsed, it removes the query and the fragment instead.

# config/initializers/tanshuku.rb
Tanshuku.configure do |config|
  config.exception_reporter =
    lambda { |exception:, original_url:|
      filtered_url =
        begin
          parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
          uri = Addressable::URI.parse(original_url)

          if uri.query
            params = parameter_filter.filter(Rack::Utils.parse_nested_query(uri.query))
            uri.query = Rack::Utils.build_nested_query(params)
          end

          # Fragments might also contain secrets, e.g., `#access_token=...`.
          uri.fragment = nil
          uri.to_s
        # Shortening a URL often fails because the URL is invalid.
        rescue StandardError
          original_url&.sub(/[?#].*/m, "")
        end

      # Log only the exception’s class because its message might contain the original URL.
      Rails.logger.warn("Failed to shorten a URL: #{exception.class} for #{filtered_url.inspect}")
    }
end
Shortening URLs from user input

Tanshuku redirects users to original URLs without checking their hosts, i.e., it redirects to any host. config.url_pattern only checks the format of URLs and doesn’t ensure that their destinations are safe. For example, both https://evil.example/ and //evil.example/ match the default pattern.

So if you shorten URLs from user input, check them in your Rails app, e.g., with an allowlist of hosts. Otherwise, the following risks arise.

  • Attackers can abuse your shortened URLs as open redirects. They can lead users to phishing sites with URLs of your trusted domain.
  • Your domain might be added to blocklists of spam filters or safe browsing services. Then emails containing your legitimate shortened URLs might not be delivered, and browsers might show warnings when users access them.

The following example shortens a URL only if it is an absolute path in your app, or if its scheme is HTTP(S) and its host is allowed.

# Checks whether a URL can be shortened.
module ShortenableUrl
  ALLOWED_HOSTS = %w[example.com www.example.com].freeze

  # Returns true if the URL is an absolute path or an HTTP(S) URL with an allowed host.
  def self.allowed?(url)
    uri = Addressable::URI.parse(url)

    if uri.host
      %w[http https].include?(uri.normalized_scheme) && ALLOWED_HOSTS.include?(uri.normalized_host)
    else
      uri.scheme.nil? && uri.path.start_with?("/")
    end
  rescue Addressable::URI::InvalidURIError
    false
  end
end

Tanshuku::Url.shorten(user_input) if ShortenableUrl.allowed?(user_input)

More information

cf. Tanshuku::Url.shorten’s API documentation

4. Share the shortened URLs

You can share the shortened URLs, e.g., https://example.com/t/abcdefghij0123456789.

When a user clicks a link with a shortened URL, your Rails app redirects the user to its original URL.

Installation

1. Enable Tanshuku

Add gem "tanshuku" to your application’s Gemfile.

# Gemfile
gem "tanshuku"

2. Generate setup files

Execute a shell command as following:

bin/rails generate tanshuku:install

3. Apply generated migration files

Execute a shell command as following:

bin/rails db:migrate

Q&A

Q. What does “tanshuku” mean?

A. “Tanshuku” is a Japanese word “短縮.” It means “shortening.” And “短縮URL” in Japanese means “shortened URL” in English.

Q. ** (anything you want) isn’t implemented?

A. Does Tanshuku have some missing features? Please create an issue.

How to develop

  1. Fork this repository
  2. git clone your fork
  3. bundle install and rake steep:prepare
  4. Update sources
  5. rake
  6. Fix rake errors if rake fails
  7. Create a pull request

How to release

  1. Make your repository fresh
  2. bump current and confirm the current version
  3. bump patch, bump minor, or bump major
  4. gem_push=no rake release to create a tag and push it with the branch
  5. Approve the triggered “Create a Release” workflow, which pushes the gem to RubyGems.org and creates a GitHub Release

About

A Rails engine for shortening URLs

Topics

Resources

Stars

6 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages