tanshuku 0.0.11 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58228d834716ae9f1a9415212f4976816aeaf61bd6ff2a1e92672a62bd202a93
-  data.tar.gz: e8ecd16d19d73cdff428f08cd5a3b801e59934fa86d69fa1b182e0da40da1feb
+  metadata.gz: 1748ebeb12ae7c094ef0cd34386f6db676b8363c50423b39bf571e92093a1217
+  data.tar.gz: c9d4513adbf7bd8e87d1d218801b108c7a72e4681185d4b7f60705eefff722ce
 SHA512:
-  metadata.gz: f786879cc78304a288487079e4b2e218be8df2d7c6df4edc8f629ca672369fa583998e2b44bc4d62876b1f242dd24ae0f67201a1a85f391d20fb26dd07d80ca1
-  data.tar.gz: 2b7af5d5181be59774b1d6ae13e12df32347c862cec776139a4ba31da153a38fb63959380e8bebcc931fa707b658799b33eb5a248a7bf765ba77dc9de3397bf9
+  metadata.gz: b18fa0edf40682988bf7c51055f2a59cc100af34ea50ccf52bd9ca320b34a95dd76f9bd864f57e98e4909dbec904da954e02d0b1e4cadd2ff42119f1956cee47
+  data.tar.gz: 0fa9fe03d277660ba8d440429f8f58686d3587dc09db02788ffc79ddeff2e34ef995500b0fde39e19cb841f026e7ce4b918c06ff504120fbf4203bae54cfbe5f

data/README.md

@@ -0,0 +1,167 @@
+# 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**: The initializer file can be generated by `bin/rails generate tanshuku:install`. See the "[Installation](#installation)" section for more information.
+
+#### `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`. 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
+```
+
+### 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`](#configdefault_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.
+
+```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"
+```
+
+### 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
+
+### What does "tanshuku" mean?
+
+"Tanshuku" is a Japanese word "短縮." It means "shortening." "短縮URL" in Japanese means "shortened URL" in English.
+
+### \*\* (anything you want) isn't implemented?
+
+Does Tanshuku have some missing features? Please [create an issue](https://github.com/kg8m/tanshuku/issues/new).

data/Rakefile

@@ -8,3 +8,18 @@ load "rails/tasks/engine.rake"
 load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+namespace :yard do
+  desc "Start YARD server"
+  task :server do
+    puts "See http://localhost:8808/"
+    sh "yard server --reload"
+  end
+end
+
+task default: %i[rubocop spec]

data/app/controllers/tanshuku/urls_controller.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Tanshuku
+  # A Rails controller class for finding a {Tanshuku::Url} record and redirecting to its shortened URL.
   class UrlsController < ActionController::API
+    # Finds a {Tanshuku::Url} record from the given +key+ parameter and redirects to its shortened URL.
+    #
+    # @return [void]
+    #
+    # @raise [ActiveRecord::NotFound] If no {Tanshuku::Url} record is found for the given +key+.
     def show
       url = Url.find_by!(key: params[:key])
       redirect_to url.url, status: :moved_permanently, allow_other_host: true

data/app/models/tanshuku/url.rb

@@ -7,6 +7,7 @@ require "rack"
 require "securerandom"
 
 module Tanshuku
+  # An +ActiveRecord::Base+ inherited class for a shortened URL. This class also have some logics for shortening URLs.
   class Url < ActiveRecord::Base
     DEFAULT_NAMESPACE = ""
 
@@ -22,7 +23,28 @@ module Tanshuku
     # duplicated. Then rescue the exception and try to retry.
     # validates :url, :hashed_url, :key, uniqueness: true
 
-    def self.shorten(original_url, namespace: DEFAULT_NAMESPACE)
+    # Shortens a URL. Builds and saves a {Tanshuku::Url} record with generating a unique key for the given URL and
+    # namespace. Then returns the record's shortened URL with the given URL options.
+    #
+    # @note
+    #   If a {Tanshuku::Url} record already exists, no additional record will be created and the existing record will be
+    #   used.
+    # @note
+    #   The given URL will be normalized before shortening. So for example, +shorten("https://google.com/")+ and
+    #   +shorten("https://google.com")+ have the same result.
+    #
+    # @param original_url [String] The original, i.e., non-shortened, URL.
+    # @param namespace: [String] A namespace for shorteting URL. Shortened URLs are unique in namespaces.
+    # @param url_options: [Hash] An option for Rails' +url_for+.
+    #
+    # @return [String] A shortened URL if succeeded to shorten the original URL.
+    # @return [String] The original URL if failed to shorten it.
+    #
+    # @example If succeeded to shorten a URL.
+    #   Tanshuku::Url.shorten("https://google.com/")  #=> "http://localhost/t/abcdefghij0123456789"
+    # @example If failed to shorten a URL.
+    #   Tanshuku::Url.shorten("https://google.com/")  #=> "https://google.com/"
+    def self.shorten(original_url, namespace: DEFAULT_NAMESPACE, url_options: {})
       raise ArgumentError, "original_url should be present" unless original_url
 
       url = normalize_url(original_url)
@@ -35,7 +57,7 @@ module Tanshuku
               r.attributes = { url:, key: generate_key }
             end
 
-          record.shortened_url
+          record.shortened_url(url_options)
         end
       # ActiveRecord::RecordNotFound is raised when the key is duplicated.
       rescue ActiveRecord::RecordNotFound => e
@@ -52,6 +74,13 @@ module Tanshuku
       original_url
     end
 
+    # Finds a {Tanshuku::Url} record by a non-shortened URL.
+    #
+    # @param url [String] A non-shortened URL.
+    # @param namespace: [String] A namespace for the URL.
+    #
+    # @return [Tanshuku::Url] A {Tanshuku::Url} instance if found.
+    # @reutnr [nil] +nil+ unless found.
     def self.find_by_url(url, namespace: DEFAULT_NAMESPACE)
       normalized_url = normalize_url(url)
       hashed_url = hash_url(normalized_url, namespace:)
@@ -59,27 +88,59 @@ module Tanshuku
       find_by(hashed_url:)
     end
 
-    # Normalize a trailing slash, `?` for an empty query, and so on, and sort query keys.
+    # Normalizes a URL. Adds or removes a trailing slash, removes +?+ for an empty query, and so on. And sorts query
+    # keys.
+    #
+    # @param url [String] A non-normalized URL.
+    #
+    # @return [String] A normalized URL.
     def self.normalize_url(url)
       parsed_url = Addressable::URI.parse(url)
       parsed_url.query_values = Rack::Utils.parse_query(parsed_url.query)
       parsed_url.normalize.to_s
     end
 
+    # Hashes a URL with +Digest::SHA512.hexdigest+.
+    #
+    # @param url [String] A non-hashed URL.
+    # @param namespace: [String] A namespace for the URL.
+    #
+    # @return [String] A hashed 128-character string.
     def self.hash_url(url, namespace: DEFAULT_NAMESPACE)
       Digest::SHA512.hexdigest(namespace.to_s + url)
     end
 
+    # Generates a key with +SecureRandom.alphanumeric+.
+    #
+    # @return [String] A 20-character alphanumeric string.
     def self.generate_key
       SecureRandom.alphanumeric(KEY_LENGTH)
     end
 
+    # Reports an exception when failed to shorten a URL.
+    #
+    # @note This method calls {Tanshuku::Configuration#exception_reporter}'s +call+ and returns its return value.
+    #
+    # @param exception: [Exception] An error instance at shortening a URL.
+    # @param original_url: [String] The original URL failed to shorten.
+    #
+    # @return [void]
     def self.report_exception(exception:, original_url:)
       Tanshuku.config.exception_reporter.call(exception:, original_url:)
     end
 
-    def shortened_url
-      Tanshuku::Engine.routes.url_for(controller: "tanshuku/urls", action: :show, key:)
+    # The record's shortened URL.
+    #
+    # @param url_options [Hash] An option for Rails' +url_for+.
+    #
+    # @return [String] A shortened URL.
+    def shortened_url(url_options = {})
+      url_options = url_options.symbolize_keys
+      url_options[:controller] = "tanshuku/urls"
+      url_options[:action] = :show
+      url_options[:key] = key
+
+      Tanshuku::Engine.routes.url_for(url_options)
     end
   end
 end

data/lib/generators/tanshuku/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Tanshuku
+  # A generator class for Tanshuku configuration files.
+  #
+  # @api private
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("../templates", __dir__)
+
+    # Generates a configuration file +config/initializers/tanshuku.rb+.
+    #
+    # @return [void]
+    def copy_initializer_file
+      copy_file "initializer.rb", "config/initializers/tanshuku.rb"
+    end
+
+    # Generates a migration file +db/migrate/20230220123456_create_tanshuku_urls.rb+.
+    #
+    # @return [void]
+    def copy_migration_file
+      filename = "20230220123456_create_tanshuku_urls.rb"
+      copy_file "../../../db/migrate/#{filename}", "db/migrate/#{filename}"
+    end
+  end
+end

data/lib/generators/templates/initializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Tanshuku.configure do |config|
+  # Your default URL options for `url_for`. Defaults to `{}`.
+  # config.default_url_options = { Your configurations here }
+
+  # Your default error reporter that is used when failed to shorten a URL. Defaults to
+  # `Tanshuku::Configuration::DefaultExceptionReporter`. It logs the exception and the original URL with
+  # `Rails.logger.warn`. This value should respond to `#call` with keyword arguments `exception:` and `original_url:`.
+  # config.exception_reporter =
+  #   lambda { |exception:, original_url:|
+  #     Your configurations here
+  #   }
+end

data/lib/tanshuku/configuration.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
 module Tanshuku
+  # A class for managing Tanshuku configurations.
   class Configuration
+    # The default error-reporter. Calls +Rails.logger.warn+.
     module DefaultExceptionReporter
+      # The default error-reporting procedure. Calls +Rails.logger.warn+.
+      #
+      # @param exception: [Exception] An error instance at shortening a URL.
+      # @param original_url: [String] The original URL failed to shorten.
+      #
+      # @return [void]
       def self.call(exception:, original_url:)
         Rails.logger.warn("Tanshuku - Failed to shorten a URL: #{exception.inspect} for #{original_url.inspect}")
       end
@@ -10,7 +18,20 @@ module Tanshuku
 
     include ActiveModel::Attributes
 
+    # @!attribute [rw] default_url_options
+    #   Default URL options for Rails' +url_for+. Defaults to +{}+.
+    #
+    #   @return [Hash]
+    #   @return [void] If you set an invalid object.
     attribute :default_url_options, default: {}
+
+    # @!attribute [rw] exception_reporter
+    #   A error-reporter class, module, or object used when shortening a URL fails. This should respond to +#call+.
+    #   Defaults to {Tanshuku::Configuration::DefaultExceptionReporter}.
+    #
+    #   @return [Tanshuku::Configuration::DefaultExceptionReporter, #call]
+    #     A +Tanshuku::Configuration::DefaultExceptionReporter+ instance or an object that responds to +#call+.
+    #   @return [void] If you set an invalid object.
     attribute :exception_reporter, default: DefaultExceptionReporter
   end
 end

data/lib/tanshuku/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Tanshuku
+  # Tanshuku's Rails engine.
   class Engine < ::Rails::Engine
     isolate_namespace Tanshuku
 

data/lib/tanshuku/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tanshuku
-  VERSION = "0.0.11"
+  VERSION = "0.0.13"
 end

data/lib/tanshuku.rb

@@ -4,13 +4,28 @@ require_relative "tanshuku/configuration"
 require_relative "tanshuku/engine"
 require_relative "tanshuku/version"
 
+# Tanshuku's namespace.
 module Tanshuku
+  # Returns a configuration object for Tanshuku.
+  #
+  # @return [Tanshuku::Configuration]
   def self.config
     Mutex.new.synchronize do
       @config ||= Configuration.new
     end
   end
 
+  # Configures Tanshuku.
+  #
+  # @yieldparam config [Tanshuku::Configuration] A configuration object that is yielded.
+  # @yieldreturn [void]
+  #
+  # @return [void]
+  #
+  # @example
+  #   Tanshuku.configure do |config|
+  #     config.default_url_options = { host: "localhost", protocol: :https }
+  #   end
   def self.configure
     yield config
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tanshuku
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.13
 platform: ruby
 authors:
 - kg8m
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-10 00:00:00.000000000 Z
+date: 2023-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -48,6 +48,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.md
 - Rakefile
 - app/controllers/tanshuku/urls_controller.rb
 - app/models/tanshuku/url.rb
@@ -55,10 +56,13 @@ files:
 - config/locales/ja.yml
 - config/routes.rb
 - db/migrate/20230220123456_create_tanshuku_urls.rb
+- lib/generators/tanshuku/install_generator.rb
+- lib/generators/templates/initializer.rb
 - lib/tanshuku.rb
 - lib/tanshuku/configuration.rb
 - lib/tanshuku/engine.rb
 - lib/tanshuku/version.rb
+- tmp/.keep
 homepage: https://github.com/kg8m/tanshuku
 licenses:
 - MIT