tanshuku 0.0.14 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b280080f53f8fb1f57a0b05cd1f4549f81a8c5c6a893501eec056bf0ff49e894
-  data.tar.gz: c2dea1c5782731a81c2f961186211cddff5c9494be925f1d395a53cea17a11c4
+  metadata.gz: 6aee43e7ffa3cbc23f12aa56267742a5efdae9b88eab48e4c8abce0e1ffac241
+  data.tar.gz: f4d85b7c7583b4415772c3a3208f6a2242fb49966f5acbc3bf0d864e647bbffb
 SHA512:
-  metadata.gz: 8c96f4614d77af55d6a3889956967ab5244819071a0ec77d415df5af76fd288eefc0554cbb32b661ea7349fd5e8175201e02fe5309ec8dd53634eefa30508cc5
-  data.tar.gz: 9f8ed89f16d6531f60303f03feded46ff98a35f5319bd6ec7b77e5526664fd830dad0da8eec51e8fbd7432d87702d88d34df9b1db1fdc03a4a04a006d87af3d2
+  metadata.gz: 83408c401bf65bf47ca10da7b27ea6e4f8c7b66f19657c8835780692ad30c1ffc398d01560395b04cfa4f4a077964a8d5f505feb5e852a77876e86c78b01a23c
+  data.tar.gz: e6c324b2d3d6e36dd6b7e15901f5102e720c08954b2d93ef0a31baecf55affe7ed46d0eb21b8fb6ea15d5a6de6c0b4a2ecd6aff3dd98de07894fcba7ffd7f8fd

data/README.md

@@ -175,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

@@ -21,10 +21,10 @@ namespace :yard do
     sh "yard server --reload"
   end
 
-  desc "Generate YARD docs"
-  task :generate do
-    sh "yard --output-dir docs"
+  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.
@@ -96,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:)
@@ -119,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:)
@@ -35,12 +61,102 @@ module Tanshuku
     #     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+ with
-    #   keyword arguments +exception:+ and +original_url:+. Defaults to
+    #   required 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 [#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).
@@ -67,6 +183,8 @@ module Tanshuku
     #
     # @return [void]
     #
+    # @note Use {Tanshuku.configure} as a public API for configuration.
+    #
     # @api private
     def configure
       @mutex.synchronize do

data/lib/tanshuku/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tanshuku
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.16
 platform: ruby
 authors:
 - kg8m
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-26 00:00:00.000000000 Z
+date: 2023-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable