Tanshuku is a simple and small Rails engine that makes it easier to shorten URLs.
- 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.
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"
endNote: You can customize the path /t as you like.
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.
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 }
endIf 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: })
}
endcf. Tanshuku::Configuration’s API documentation
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"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"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"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_urlstable 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_reporterlogs 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}")
}
endTanshuku 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)cf. Tanshuku::Url.shorten’s API documentation
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.
Add gem "tanshuku" to your application’s Gemfile.
# Gemfile
gem "tanshuku"Execute a shell command as following:
bin/rails generate tanshuku:installExecute a shell command as following:
bin/rails db:migrateA. “Tanshuku” is a Japanese word “短縮.” It means “shortening.” And “短縮URL” in Japanese means “shortened URL” in English.
A. Does Tanshuku have some missing features? Please create an issue.
- Fork this repository
git cloneyour forkbundle installandrake steep:prepare- Update sources
rake- Fix
rakeerrors ifrakefails - Create a pull request
- Make your repository fresh
bump currentand confirm the current versionbump patch,bump minor, orbump majorgem_push=no rake releaseto create a tag and push it with the branch- Approve the triggered “Create a Release” workflow, which pushes the gem to RubyGems.org and creates a GitHub Release