tanshuku 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1748ebeb12ae7c094ef0cd34386f6db676b8363c50423b39bf571e92093a1217
-  data.tar.gz: c9d4513adbf7bd8e87d1d218801b108c7a72e4681185d4b7f60705eefff722ce
+  metadata.gz: b280080f53f8fb1f57a0b05cd1f4549f81a8c5c6a893501eec056bf0ff49e894
+  data.tar.gz: c2dea1c5782731a81c2f961186211cddff5c9494be925f1d395a53cea17a11c4
 SHA512:
-  metadata.gz: b18fa0edf40682988bf7c51055f2a59cc100af34ea50ccf52bd9ca320b34a95dd76f9bd864f57e98e4909dbec904da954e02d0b1e4cadd2ff42119f1956cee47
-  data.tar.gz: 0fa9fe03d277660ba8d440429f8f58686d3587dc09db02788ffc79ddeff2e34ef995500b0fde39e19cb841f026e7ce4b918c06ff504120fbf4203bae54cfbe5f
+  metadata.gz: 8c96f4614d77af55d6a3889956967ab5244819071a0ec77d415df5af76fd288eefc0554cbb32b661ea7349fd5e8175201e02fe5309ec8dd53634eefa30508cc5
+  data.tar.gz: 9f8ed89f16d6531f60303f03feded46ff98a35f5319bd6ec7b77e5526664fd830dad0da8eec51e8fbd7432d87702d88d34df9b1db1fdc03a4a04a006d87af3d2

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`.

data/Rakefile

@@ -20,6 +20,11 @@ namespace :yard 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/models/tanshuku/url.rb

@@ -44,6 +44,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
 

data/lib/tanshuku/configuration.rb

@@ -23,15 +23,55 @@ 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] 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
+    #   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] 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

@@ -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.14"
 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.14
 platform: ruby
 authors:
 - kg8m
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-22 00:00:00.000000000 Z
+date: 2023-03-26 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: []