tanshuku 0.0.13 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1748ebeb12ae7c094ef0cd34386f6db676b8363c50423b39bf571e92093a1217
-  data.tar.gz: c9d4513adbf7bd8e87d1d218801b108c7a72e4681185d4b7f60705eefff722ce
+  metadata.gz: 0324af7c609277e8e090c37de67cb5c6c86cfd6e72944f6b04d36f58e241e76f
+  data.tar.gz: '08ff837c3b7a985ab8cdc849b0bc2b8bda659b4863d5e2b6a6c1c10a8676c977'
 SHA512:
-  metadata.gz: b18fa0edf40682988bf7c51055f2a59cc100af34ea50ccf52bd9ca320b34a95dd76f9bd864f57e98e4909dbec904da954e02d0b1e4cadd2ff42119f1956cee47
-  data.tar.gz: 0fa9fe03d277660ba8d440429f8f58686d3587dc09db02788ffc79ddeff2e34ef995500b0fde39e19cb841f026e7ce4b918c06ff504120fbf4203bae54cfbe5f
+  metadata.gz: 9750293fcc5dc6baeb2cc5b3e6ab535a4207c6aaaba0a9c9dfa1647134ed04ac48421d87ef85261210618628ecbf36b654ccc63216ed9e769f062e701f1e5611
+  data.tar.gz: dcbf6e0c7cdda1284d5fadd1a7c9c96beb513e595c94e23902973634035d7c7ff5adbe145406f4cfdf22e5fe8a6c85fea6ba67bd8f95e03a569dae1692584823

data/README.md

@@ -31,7 +31,9 @@ end
 
 **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.
+**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`
 
@@ -52,7 +54,7 @@ end
 
 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`.
+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:`.
 
@@ -68,6 +70,10 @@ Tanshuku.configure do |config|
 end
 ```
 
+#### More information
+
+cf. [`Tanshuku::Configuration`'s API documentation](https://kg8m.github.io/tanshuku/Tanshuku/Configuration.html)
+
 ### 3. Generate shortened URLs
 
 #### Basic cases
@@ -78,7 +84,7 @@ 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`](#configdefault_url_options) is used for the shortened URL.
+[`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.
 
@@ -123,6 +129,10 @@ Tanshuku::Url.shorten("https://google.com/", namespace: "a")  #=> "https://examp
 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`.
@@ -165,3 +175,20 @@ bin/rails db:migrate
 ### \*\* (anything you want) isn't implemented?
 
 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`
+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`

data/Rakefile

@@ -20,6 +20,11 @@ namespace :yard do
     puts "See http://localhost:8808/"
     sh "yard server --reload"
   end
+
+  desc "Check YARD docs"
+  task :check do
+    sh "yard --no-output --no-cache --fail-on-warning"
+  end
 end
 
-task default: %i[rubocop spec]
+task default: %i[rubocop spec yard:check]

data/app/models/tanshuku/url.rb

@@ -2,22 +2,30 @@
 
 require "active_record"
 require "addressable"
-require "digest/sha2"
 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 = ""
+    # @!attribute [rw] url
+    #   @return [String] Original, i.e., non-shortened, URL of the record.
+    #
+    # @!attribute [rw] hashed_url
+    #   @return [String] A hashed string of the record's original URL.
+    #   @note This attribute is used for uniqueness of the original URL.
+    #   @api private
+    #
+    # @!attribute [rw] key
+    #   @return [String] A unique key for the record.
+    #
+    # @!attribute [rw] created_at
+    #   @return [ActiveSupport::TimeWithZone] A timestamp when the record is created.
 
-    MAX_URL_LENGTH = 10_000
-    URL_PATTERN = %r{\A(?:https?://\w+|/)}
-    KEY_LENGTH = 20
+    DEFAULT_NAMESPACE = ""
 
     validates :url, :hashed_url, :key, presence: true
-    validates :url, length: { maximum: MAX_URL_LENGTH }
-    validates :url, format: { with: URL_PATTERN }, allow_blank: true
+    validates :url, length: { maximum: proc { Tanshuku.config.max_url_length } }
+    validates :url, format: { with: proc { Tanshuku.config.url_pattern } }, allow_blank: true
 
     # Don't validate uniqueness of unique attributes. Raise ActiveRecord::RecordNotUnique instead if the attributes get
     # duplicated. Then rescue the exception and try to retry.
@@ -34,8 +42,8 @@ module Tanshuku
     #   +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+.
+    # @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.
@@ -44,6 +52,25 @@ module Tanshuku
     #   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
 
@@ -77,10 +104,10 @@ module Tanshuku
     # 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.
+    # @param namespace [String] A namespace for the URL.
     #
     # @return [Tanshuku::Url] A {Tanshuku::Url} instance if found.
-    # @reutnr [nil] +nil+ unless found.
+    # @return [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:)
@@ -100,31 +127,35 @@ module Tanshuku
       parsed_url.normalize.to_s
     end
 
-    # Hashes a URL with +Digest::SHA512.hexdigest+.
+    # Hashes a URL.
+    #
+    # @note This method calls {Tanshuku::Configuration#url_hasher}'s +call+ and returns its return value.
     #
     # @param url [String] A non-hashed URL.
-    # @param namespace: [String] A namespace for the URL.
+    # @param namespace [String] A namespace for the URL.
     #
-    # @return [String] A hashed 128-character string.
+    # @return [String] Depends on your {Tanshuku::Configuration#url_hasher} configuration.
     def self.hash_url(url, namespace: DEFAULT_NAMESPACE)
-      Digest::SHA512.hexdigest(namespace.to_s + url)
+      Tanshuku.config.url_hasher.call(url, namespace:)
     end
 
-    # Generates a key with +SecureRandom.alphanumeric+.
+    # Generates a unique key for a shortened URL.
+    #
+    # @note This method calls {Tanshuku::Configuration#key_generator}'s +call+ and returns its return value.
     #
-    # @return [String] A 20-character alphanumeric string.
+    # @return [String] Depends on your {Tanshuku::Configuration#key_generator} configuration.
     def self.generate_key
-      SecureRandom.alphanumeric(KEY_LENGTH)
+      Tanshuku.config.key_generator.call
     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.
+    # @param exception [Exception] An error instance at shortening a URL.
+    # @param original_url [String] The original URL failed to shorten.
     #
-    # @return [void]
+    # @return [void] Depends on your {Tanshuku::Configuration#exception_reporter} configuration.
     def self.report_exception(exception:, original_url:)
       Tanshuku.config.exception_reporter.call(exception:, original_url:)
     end

data/lib/tanshuku/configuration.rb

@@ -1,14 +1,40 @@
 # frozen_string_literal: true
 
+require "digest/sha2"
+require "securerandom"
+
 module Tanshuku
   # A class for managing Tanshuku configurations.
   class Configuration
+    # The default object to hash a URL. Calls +Digest::SHA512.hexdigest+.
+    module DefaultUrlHasher
+      # Calls +Digest::SHA512.hexdigest+ with the given URL string and the given namespace.
+      #
+      # @param url [String] A URL to hash.
+      # @param namespace [String] A namespace for the URL's uniqueness.
+      #
+      # @return [String] A SHA512 digest string from the given url and namespace.
+      def self.call(url, namespace:)
+        Digest::SHA512.hexdigest("#{namespace}#{url}")
+      end
+    end
+
+    # The default unique key generator. Calls +SecureRandom.alphanumeric+ with {Tanshuku::Configuration#key_length}.
+    module DefaultKeyGenerator
+      # Calls +SecureRandom.alphanumeric+ and returns a string with length of {Tanshuku::Configuration#key_length}.
+      #
+      # @return [String] An alphanumeric string with length of {Tanshuku::Configuration#key_length}.
+      def self.call
+        SecureRandom.alphanumeric(Tanshuku.config.key_length)
+      end
+    end
+
     # The default error-reporter. Calls +Rails.logger.warn+.
     module DefaultExceptionReporter
-      # The default error-reporting procedure. Calls +Rails.logger.warn+.
+      # Calls +Rails.logger.warn+ and logs the exception and the original URL.
       #
-      # @param exception: [Exception] An error instance at shortening a URL.
-      # @param original_url: [String] The original URL failed to shorten.
+      # @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:)
@@ -23,15 +49,147 @@ module Tanshuku
     #
     #   @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] max_url_length
+    #   Maximum length of {Tanshuku::Url#url}. Defaults to +10,000+.
+    #
+    #   @return [Integer]
+    #   @return [void] If you set an invalid object.
+    #
+    #   @note
+    #     The example below means that {Tanshuku::Url#url} can have a URL string with less than or equal to 20,000
+    #     characters.
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.max_url_length = 20_000
+    #     end
+    attribute :max_url_length, :integer, default: 10_000
+
+    # @!attribute [rw] url_pattern
+    #   Allowed pattern of {Tanshuku::Url#url}. Defaults to <code>%r{\A(?:https?://\w+|/)}</code>. This default value
+    #   forces a URL to start with "http://" or "https://", or to be an absolute path without scheme.
+    #
+    #   @return [Regexp]
+    #   @return [void] If you set an invalid object.
+    #
+    #   @note
+    #     The example below means that {Tanshuku::Url#url} should start with a slash +/+.
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.url_pattern = /\A\//
+    #     end
+    attribute :url_pattern, default: %r{\A(?:https?://\w+|/)}
+
+    # @!attribute [rw] key_length
+    #   Length of {Tanshuku::Url#key} when {Tanshuku::Configuration#key_generator} is
+    #   {Tanshuku::Configuration::DefaultKeyGenerator}. Defaults to +20+.
+    #
+    #   @return [Integer]
+    #   @return [void] If you set an invalid object.
+    #
+    #   @note Don't forget to fix the limit of the +tanshuku_urls.key+ column if you change this value.
+    #
+    #   @note
+    #     The example below means that {Tanshuku::Url#key} has 10-char string.
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.key_length = 10
+    #     end
+    attribute :key_length, :integer, default: 20
+
+    # @!attribute [rw] url_hasher
+    #   A class, module, or object to hash a URL. This should respond to +#call+ with a required positional argument
+    #   +url+ and a required keyword argument +namespace:+. Defaults to {Tanshuku::Configuration::DefaultUrlHasher}.
+    #
+    #   @return [#call]
+    #     A class, module, or object that responds to +#call+ with a required positional argument +url+ and a required
+    #     keyword argument +namespace:+.
+    #   @return [void] If you set an invalid object.
+    #
+    #   @note The example below means that URLs are hashed with +Digest::SHA256.hexdigest+.
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.url_hasher = ->(url, namespace:) { Digest::SHA256.hexdigest("#{namespace}#{url}") }
+    #     end
+    attribute :url_hasher, default: DefaultUrlHasher
+
+    # @!attribute [rw] key_generator
+    #   A class, module, or object to generate a unique key for shortened URLs. This should respond to +#call+ without
+    #   any arguments. Defaults to {Tanshuku::Configuration::DefaultKeyGenerator}.
+    #
+    #   @return [#call]
+    #     A class, module, or object that responds to +#call+ without any arguments.
+    #   @return [void] If you set an invalid object.
+    #
+    #   @note The example below means that unique keys for shortened URLs are generated by +SecureRandom.uuid+.
+    #
+    #   @example
+    #     # config/initializers/tanshuku.rb
+    #     Tanshuku.configure do |config|
+    #       config.key_generator = -> { SecureRandom.uuid }
+    #     end
+    attribute :key_generator, default: DefaultKeyGenerator
+
     # @!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}.
+    #   A error-reporter class, module, or object used when shortening a URL fails. This should respond to +#call+ with
+    #   required keyword arguments +exception:+ and +original_url:+. Defaults to
+    #   {Tanshuku::Configuration::DefaultExceptionReporter}.
     #
-    #   @return [Tanshuku::Configuration::DefaultExceptionReporter, #call]
-    #     A +Tanshuku::Configuration::DefaultExceptionReporter+ instance or an object that responds to +#call+.
+    #   @return [#call]
+    #     A class, module, or object that responds to +#call+ with required 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]
+    #
+    # @note Use {Tanshuku.configure} as a public API for configuration.
+    #
+    # @api private
+    def configure
+      @mutex.synchronize do
+        yield self
+      end
+    end
   end
 end

data/lib/tanshuku/engine.rb

@@ -2,6 +2,18 @@
 
 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.13"
+  VERSION = "0.0.15"
 end

data/lib/tanshuku.rb

@@ -9,10 +9,15 @@ 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
 
   # Configures Tanshuku.
@@ -22,11 +27,15 @@ module Tanshuku
   #
   # @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
-    yield config
+  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.13
+  version: 0.0.15
 platform: ruby
 authors:
 - kg8m
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-22 00:00:00.000000000 Z
+date: 2023-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -70,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: []