tanshuku 0.0.12 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06377e7737ccb49d4080ce2a728f4ba5ca98d00bd14f85838e3e888c899327d1
-  data.tar.gz: 63065a557df15b3c6ca45b9af168a9562a8aae1f9a41bb7b3db7a2ad9adaa82f
+  metadata.gz: b280080f53f8fb1f57a0b05cd1f4549f81a8c5c6a893501eec056bf0ff49e894
+  data.tar.gz: c2dea1c5782731a81c2f961186211cddff5c9494be925f1d395a53cea17a11c4
 SHA512:
-  metadata.gz: 5bab0a2c9c7b26ec1f34ef02d465ecea40435e890e6381a6e3140850e5738a803141906f5bb6ca2b2ff715935d5380eb3119b66f556ce231d8f584b21d5f66d3
-  data.tar.gz: 14d22e0bb7de15a6c37de42e314be5521f2e3ff77bd8511cacfd1cf0847791b4a234c98e459a01e1443f52990672b9be636828f90a3aaf10fb67bc6d4fb9e8f6
+  metadata.gz: 8c96f4614d77af55d6a3889956967ab5244819071a0ec77d415df5af76fd288eefc0554cbb32b661ea7349fd5e8175201e02fe5309ec8dd53634eefa30508cc5
+  data.tar.gz: 9f8ed89f16d6531f60303f03feded46ff98a35f5319bd6ec7b77e5526664fd830dad0da8eec51e8fbd7432d87702d88d34df9b1db1fdc03a4a04a006d87af3d2

data/README.md

@@ -0,0 +1,177 @@
+# 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
+
+### 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,23 @@ 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
+
+  desc "Generate YARD docs"
+  task :generate do
+    sh "yard --output-dir docs"
+  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,6 +23,46 @@ module Tanshuku
     # duplicated. Then rescue the exception and try to retry.
     # validates :url, :hashed_url, :key, uniqueness: true
 
+    # 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/"
+    # @example With ad hoc URL options.
+    #   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"
+    # @example With 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"
     def self.shorten(original_url, namespace: DEFAULT_NAMESPACE, url_options: {})
       raise ArgumentError, "original_url should be present" unless original_url
 
@@ -52,6 +93,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,25 +107,52 @@ 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
 
+    # 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"

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,60 @@ 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.
+    #
+    #   @note
+    #     The example below means that the configured host and protocol are used. Shortened URLs will be like
+    #     +https://example.com/t/abcdefghij0123456789+.
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.default_url_options = { host: "example.com", protocol: :https }
+    #     end
     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+ with
+    #   keyword arguments +exception:+ and +original_url:+. Defaults to
+    #   {Tanshuku::Configuration::DefaultExceptionReporter}.
+    #
+    #   @return [#call] An object that responds to +#call+ with keyword arguments +exception:+ and +original_url:+.
+    #   @return [void] If you set an invalid object.
+    #
+    #   @note The example below means that an exception and a URL will be reported to Sentry (https://sentry.io).
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.exception_reporter =
+    #         lambda { |exception:, original_url:|
+    #           Sentry.capture_exception(exception, tags: { original_url: })
+    #         }
+    #     end
     attribute :exception_reporter, default: DefaultExceptionReporter
+
+    def initialize(...)
+      super
+      @mutex = Mutex.new
+    end
+
+    # Configures Tanshuku thread-safely.
+    #
+    # @yieldparam config [Tanshuku::Configuration] A configuration object that is yielded.
+    # @yieldreturn [void]
+    #
+    # @return [void]
+    #
+    # @api private
+    def configure
+      @mutex.synchronize do
+        yield self
+      end
+    end
   end
 end

data/lib/tanshuku/engine.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module Tanshuku
+  # Tanshuku's Rails engine.
+  #
+  # @note
+  #   The example below 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.
+  #
+  # @example To mount Tanshuku to your Rails app
+  #   # config/routes.rb
+  #   Rails.application.routes.draw do
+  #     mount Tanshuku::Engine, at: "/t"
+  #   end
   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.12"
+  VERSION = "0.0.14"
 end

data/lib/tanshuku.rb

@@ -4,14 +4,38 @@ 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]
+  #
+  # @note
+  #   Mutating a {Tanshuku::Configuration} object is thread-<em><b>unsafe</b></em>. It is recommended to use
+  #   {Tanshuku.configure} for configuration.
   def self.config
-    Mutex.new.synchronize do
-      @config ||= Configuration.new
-    end
+    # Disable this cop but use `Tanshuku::Configuration#configure` for thread-safety.
+    # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
+    @config ||= Configuration.new
+    # rubocop:enable ThreadSafety/InstanceVariableInClassMethod
   end
 
-  def self.configure
-    yield config
+  # Configures Tanshuku.
+  #
+  # @yieldparam config [Tanshuku::Configuration] A configuration object that is yielded.
+  # @yieldreturn [void]
+  #
+  # @return [void]
+  #
+  # @note
+  #   This method is thread-safe. When mutating a {Tanshuku::Configuration} object for configuration, it is recommended
+  #   to use this method.
+  #
+  # @example
+  #   Tanshuku.configure do |config|
+  #     config.default_url_options = { host: "localhost", protocol: :https }
+  #   end
+  def self.configure(&)
+    config.configure(&)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tanshuku
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.14
 platform: ruby
 authors:
 - kg8m
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-11 00:00:00.000000000 Z
+date: 2023-03-26 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
@@ -66,6 +70,7 @@ metadata:
   homepage_uri: https://github.com/kg8m/tanshuku
   source_code_uri: https://github.com/kg8m/tanshuku
   changelog_uri: https://github.com/kg8m/tanshuku/releases
+  documentation_uri: https://kg8m.github.io/tanshuku/
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []