https://github.com/kg8m/tanshuku
A Rails engine for shortening URLs
https://github.com/kg8m/tanshuku
rails ruby url-shortener
Last synced: 9 months ago
JSON representation
A Rails engine for shortening URLs
- Host: GitHub
- URL: https://github.com/kg8m/tanshuku
- Owner: kg8m
- License: mit
- Created: 2023-02-19T16:30:52.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-07T17:31:20.000Z (9 months ago)
- Last Synced: 2025-10-09T02:05:27.314Z (9 months ago)
- Topics: rails, ruby, url-shortener
- Language: Ruby
- Homepage: https://rubygems.org/gems/tanshuku
- Size: 1.46 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://rubygems.org/gems/tanshuku)
[](https://www.ruby-lang.org)
[](https://rubyonrails.org/)
[](LICENSE)
[](https://github.com/kg8m/tanshuku/actions/workflows/checks.yml)
# 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.
```rb
# 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](#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`.
```rb
# 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`](https://kg8m.github.io/tanshuku/Tanshuku/Configuration/DefaultExceptionReporter.html). 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](https://sentry.io/).
```rb
# 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](https://kg8m.github.io/tanshuku/Tanshuku/Configuration.html)
### 3. Generate shortened URLs
#### Basic cases
You can generate a shortened URL with `Tanshuku::Url.shorten`. For example:
```rb
Tanshuku::Url.shorten("https://google.com/") #=> "https://example.com/t/abcdefghij0123456789"
```
[`config.default_url_options`](https://kg8m.github.io/tanshuku/Tanshuku/Configuration.html#default_url_options-instance_method) 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.
```rb
# 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:
```rb
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.
```rb
# 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"
```
#### More information
cf. [`Tanshuku::Url.shorten`’s API documentation](https://kg8m.github.io/tanshuku/Tanshuku/Url.html#shorten-class_method)
### 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`.
```rb
# Gemfile
gem "tanshuku"
```
### 2. Generate setup files
Execute a shell command as following:
```sh
bin/rails generate tanshuku:install
```
### 3. Apply generated migration files
Execute a shell command as following:
```sh
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](https://github.com/kg8m/tanshuku/issues/new).
## How to develop
1. Fork this repository
1. `git clone` your fork
1. `bundle install` and `rake steep:prepare`
1. Update sources
1. `rake`
1. Fix `rake` errors if `rake` fails
1. Create a pull request
## How to release
1. Make your repository fresh
1. `bump current` and confirm the current version
1. `bump patch`, `bump minor`, or `bump major`
1. `rake release`