wikiwiki 0.5.0

data/lib/wikiwiki/rate_limiter.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  # Rate limiter with pluggable strategies
+  #
+  # @example Raise on limit
+  #   limiter = Wikiwiki::RateLimiter.raise_on_limit([
+  #     { window: 60, max_requests: 120 },     # 120 requests per minute
+  #     { window: 3600, max_requests: 2000 }   # 2000 requests per hour
+  #   ])
+  #   limiter.acquire!  # raises RateLimitError if limit exceeded
+  #
+  # @example Wait on limit
+  #   limiter = Wikiwiki::RateLimiter.wait_on_limit([
+  #     { window: 60, max_requests: 120 }
+  #   ])
+  #   limiter.acquire!  # waits automatically if limit exceeded
+  #
+  # @example No limit
+  #   limiter = Wikiwiki::RateLimiter.no_limit
+  #   limiter.acquire!  # always succeeds immediately
+  class RateLimiter
+    # Default rate limits for Wikiwiki REST API
+    WIKIWIKI_API_LIMITS = [
+      {window: 60, max_requests: 120},     # 120 requests per minute
+      {window: 3600, max_requests: 2000}   # 2000 requests per hour
+    ].freeze
+    public_constant :WIKIWIKI_API_LIMITS
+
+    # Create a rate limiter that raises error when limit is exceeded
+    #
+    # @param limits [Array<Hash>] array of limit configurations
+    # @option limits [Integer] :window time window in seconds
+    # @option limits [Integer] :max_requests maximum requests allowed in the window
+    # @return [RateLimiter]
+    # @raise [ArgumentError] if limits is empty
+    def self.raise_on_limit(limits)
+      raise ArgumentError, "limits cannot be empty (use .no_limit for no rate limiting)" if limits.empty?
+
+      new(limits, Strategy::Raise.new)
+    end
+
+    # Create a rate limiter that waits when limit is exceeded
+    #
+    # @param limits [Array<Hash>] array of limit configurations
+    # @option limits [Integer] :window time window in seconds
+    # @option limits [Integer] :max_requests maximum requests allowed in the window
+    # @return [RateLimiter]
+    # @raise [ArgumentError] if limits is empty
+    def self.wait_on_limit(limits)
+      raise ArgumentError, "limits cannot be empty (use .no_limit for no rate limiting)" if limits.empty?
+
+      new(limits, Strategy::Wait.new)
+    end
+
+    # Create a null rate limiter that never limits
+    #
+    # @return [RateLimiter]
+    def self.no_limit = new([], Strategy::Null.new)
+
+    # Create a rate limiter with default limits (120 requests/min, 2000 requests/hour)
+    #
+    # These are the rate limits for the Wikiwiki REST API.
+    #
+    # @return [RateLimiter]
+    def self.default = wait_on_limit(WIKIWIKI_API_LIMITS)
+
+    private_class_method :new
+
+    # @param limits [Array<Hash>] array of limit configurations
+    # @param strategy [Strategy] rate limiting strategy
+    def initialize(limits, strategy)
+      @windows = limits.map {|limit| SlidingWindow.new(**limit) }
+      @mutex = Mutex.new
+      @strategy = strategy
+    end
+
+    # Acquire permission to make a request
+    #
+    # Behavior depends on the strategy:
+    # - raise_on_limit: raises RateLimitError if limit exceeded
+    # - wait_on_limit: waits until request can be made
+    # - no_limit: always succeeds immediately
+    #
+    # @return [void]
+    # @raise [RateLimitError] if rate limit is exceeded (with raise strategy)
+    def acquire!
+      @strategy.acquire!(self)
+    end
+
+    # Get time in seconds until next request can be made
+    #
+    # @return [Float] seconds to wait (0.0 if request can be made now)
+    def wait_time_until_available
+      @mutex.synchronize do
+        @windows.map(&:wait_time).max || 0.0
+      end
+    end
+
+    # Check if a request can be made without exceeding any limits
+    #
+    # @return [Boolean] true if request is allowed
+    def can_request?
+      @windows.all?(&:can_request?)
+    end
+
+    # Record a new request across all window limiters
+    #
+    # @return [void]
+    def record!
+      @windows.each(&:record!)
+    end
+
+    # Get maximum wait time across all window limiters
+    #
+    # @return [Float, nil] seconds to wait
+    def wait_time
+      @windows.map(&:wait_time).max
+    end
+
+    attr_reader :mutex
+  end
+
+  # Rate limiting strategies
+  module Strategy
+    # Strategy that raises error when limit is exceeded
+    class Raise
+      # @param limiter [RateLimiter]
+      # @return [void]
+      # @raise [RateLimitError] if rate limit is exceeded
+      def acquire!(limiter)
+        limiter.mutex.synchronize do
+          raise RateLimitError, "Rate limit exceeded" unless limiter.can_request?
+
+          limiter.record!
+        end
+      end
+    end
+
+    # Strategy that waits when limit is exceeded
+    class Wait
+      # @param limiter [RateLimiter]
+      # @return [void]
+      def acquire!(limiter)
+        limiter.mutex.synchronize do
+          until limiter.can_request?
+            wait_time = limiter.wait_time
+            sleep wait_time if wait_time&.positive?
+          end
+          limiter.record!
+        end
+      end
+    end
+
+    # Strategy that never limits (null object pattern)
+    class Null
+      # @param limiter [RateLimiter]
+      # @return [void]
+      def acquire!(limiter)
+        # no-op
+      end
+    end
+  end
+end

data/lib/wikiwiki/sliding_window.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  # Sliding window algorithm for rate limiting
+  class SlidingWindow
+    # Initialize a new window limiter
+    #
+    # @param window [Integer] time window in seconds
+    # @param max_requests [Integer] maximum requests allowed in the window
+    def initialize(window:, max_requests:)
+      @window = window
+      @max_requests = max_requests
+      @requests = []
+    end
+
+    # Check if a request can be made without exceeding the limit
+    #
+    # @return [Boolean] true if request is allowed
+    def can_request?
+      cleanup!
+      @requests.size < @max_requests
+    end
+
+    # Record a new request timestamp
+    #
+    # @return [void]
+    def record!
+      @requests << Time.now
+    end
+
+    # Get time in seconds until next request can be made
+    #
+    # @return [Float] seconds to wait (0.0 if request can be made now)
+    def wait_time
+      cleanup!
+      return 0.0 if @requests.size < @max_requests
+
+      # Time until oldest request expires
+      oldest = @requests.first
+      time_until_expiry = @window - (Time.now - oldest)
+      [time_until_expiry, 0.0].max
+    end
+
+    private def cleanup!
+      cutoff = Time.now - @window
+      @requests.reject! {|timestamp| timestamp < cutoff }
+    end
+  end
+end

data/lib/wikiwiki/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  # The gem version
+  VERSION = "0.5.0"
+  public_constant :VERSION
+end

data/lib/wikiwiki/wiki.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest/md5"
+require "erb"
+require "logger"
+require "time"
+
+module Wikiwiki
+  # Represents a Wikiwiki wiki instance
+  #
+  # @example
+  #   auth = Wikiwiki::Auth.password(password: "admin_password")
+  #   wiki = Wikiwiki::Wiki.new(wiki_id: "my-wiki", auth:)
+  #   wiki.page_names # => ["FrontPage", "SideBar", ...]
+  #   page = wiki.page(page_name: "FrontPage")
+  class Wiki
+    attr_reader :logger
+
+    private attr_reader :api, :wiki_id
+
+    # Initializes a new Wiki instance
+    #
+    # @param wiki_id [String] the wiki ID
+    # @param auth [Wikiwiki::Auth::Password, Wikiwiki::Auth::ApiKey] authentication credentials
+    # @param rate_limiter [RateLimiter] rate limiter instance (default: RateLimiter.default)
+    # @param logger [Logger] logger instance for API request/response logging (default: Logger.new($stdout))
+    # @raise [ArgumentError] if logger is explicitly set to nil
+    def initialize(wiki_id:, auth:, rate_limiter: RateLimiter.default, logger: Logger.new($stdout))
+      raise ArgumentError, "logger cannot be nil" if logger.nil?
+
+      @wiki_id = wiki_id
+      @logger = logger
+      @api = API.new(wiki_id:, auth:, logger:, rate_limiter:)
+    end
+
+    # Returns the wiki URL
+    #
+    # @return [URI::HTTPS] the frozen wiki URL
+    def url
+      @url ||= URI.parse("https://wikiwiki.jp/#{wiki_id}/").freeze
+    end
+
+    # Returns the list of all page names in the wiki
+    #
+    # @return [Array<String>] array of page names
+    def page_names = api.get_pages["pages"].map {|p| p["name"] }
+
+    # Retrieves a page by name
+    #
+    # @param page_name [String] the name of the page
+    # @return [Wikiwiki::Page] the page object
+    # @raise [Wikiwiki::Error] if the page does not exist
+    def page(page_name:)
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      page_data = api.get_page(encoded_page_name:)
+      Page.new(
+        name: page_name,
+        source: page_data["source"],
+        # NOTE: API returns timestamp as ISO8601 string for pages
+        timestamp: Time.iso8601(page_data["timestamp"])
+      )
+    end
+
+    # Updates a page with new content
+    #
+    # @param page_name [String] the name of the page to update
+    # @param source [String] the new page source content
+    # @return [void]
+    # @raise [Wikiwiki::Error] if the update fails
+    def update_page(page_name:, source:)
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      api.put_page(encoded_page_name:, source:)
+    end
+
+    # Retrieves attachment file names on a page
+    #
+    # @param page_name [String] the name of the page
+    # @return [Array<String>] array of attachment file names
+    # @raise [Wikiwiki::Error] if the request fails
+    def attachment_names(page_name:)
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      attachments_data = api.get_attachments(encoded_page_name:)
+      attachments = attachments_data["attachments"]
+      # API returns [] when no attachments, or Hash when attachments exist
+      attachments.is_a?(Hash) ? attachments.keys : []
+    end
+
+    # Retrieves a specific attachment on a page
+    #
+    # @param page_name [String] the name of the page
+    # @param attachment_name [String] the name of the attachment file
+    # @param rev [String, nil] optional MD5 hash to retrieve a specific revision
+    # @return [Wikiwiki::Attachment] the attachment object with decoded file data
+    # @raise [Wikiwiki::Error] if the attachment does not exist
+    # @raise [ArgumentError] if rev is not a valid MD5 hash format
+    def attachment(page_name:, attachment_name:, rev: nil)
+      if rev && !rev.match?(/\A[0-9a-f]{32}\z/i)
+        raise ArgumentError, "rev must be a valid MD5 hash (32 hexadecimal characters)"
+      end
+
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      encoded_attachment_name = ERB::Util.url_encode(attachment_name)
+      data = api.get_attachment(encoded_page_name:, encoded_attachment_name:, rev:)
+
+      content = Base64.strict_decode64(data["src"])
+
+      if content.bytesize != data["size"]
+        raise ContentIntegrityError, "Size mismatch: expected #{data["size"]}, got #{content.bytesize}"
+      end
+
+      calculated_md5 = Digest::MD5.hexdigest(content)
+      if calculated_md5 != data["md5hash"]
+        raise ContentIntegrityError, "MD5 hash mismatch: expected #{data["md5hash"]}, got #{calculated_md5}"
+      end
+
+      Attachment.new(
+        page_name: data["page"],
+        name: data["file"],
+        size: data["size"],
+        # NOTE: API returns time as Unix timestamp (integer) for attachments, not ISO8601 string
+        time: Time.at(data["time"]),
+        type: data["type"],
+        content:
+      )
+    end
+
+    # Adds an attachment to a page
+    #
+    # @param page_name [String] the name of the page
+    # @param attachment_name [String] the name of the file
+    # @param content [String] the binary file content
+    # @return [void]
+    # @raise [Wikiwiki::Error] if the upload fails
+    def add_attachment(page_name:, attachment_name:, content:)
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      encoded_content = Base64.strict_encode64(content)
+      api.put_attachment(encoded_page_name:, attachment_name:, encoded_content:)
+    end
+
+    # Deletes an attachment from a page
+    #
+    # @param page_name [String] the name of the page
+    # @param attachment_name [String] the name of the attachment file
+    # @return [void]
+    # @raise [Wikiwiki::Error] if the deletion fails
+    def delete_attachment(page_name:, attachment_name:)
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      encoded_attachment_name = ERB::Util.url_encode(attachment_name)
+      api.delete_attachment(encoded_page_name:, encoded_attachment_name:)
+    end
+  end
+end

data/lib/wikiwiki.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require_relative "wikiwiki/version"
+
+# Wikiwiki REST API client library
+#
+# @example
+#   auth = Wikiwiki::Auth.password(password: "admin_password")
+#   wiki = Wikiwiki::Wiki.new(wiki_id: "my-wiki", auth:)
+#   page = wiki.page(page_name: "FrontPage")
+#   page.name # => "FrontPage"
+module Wikiwiki
+  # Base error class for Wikiwiki gem
+  class Error < StandardError; end
+
+  # Rate limit exceeded error
+  class RateLimitError < Error; end
+
+  # Content integrity error
+  # Raised when downloaded file content doesn't match expected size or MD5 hash
+  class ContentIntegrityError < Error; end
+
+  # API request error
+  class APIError < Error; end
+
+  # Authentication error
+  # Raised when HTTP status is 401
+  class AuthenticationError < APIError; end
+
+  # Resource not found error
+  # Raised when HTTP status is 404
+  class ResourceNotFoundError < APIError; end
+
+  # Server error
+  # Raised when HTTP status is 5xx
+  class ServerError < APIError; end
+
+  loader = Zeitwerk::Loader.for_gem
+  loader.inflector.inflect("api" => "API")
+  loader.setup
+  loader.eager_load
+end

data/mise.toml

@@ -0,0 +1,6 @@
+[tools]
+ruby = "3.2"
+
+[env]
+_.path = ["bin", "exe"]
+_.file = '.env'

data/rbs_collection.yaml

@@ -0,0 +1,12 @@
+# Download sources
+sources:
+  - type: stdlib
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+# A directory to install the downloaded RBSs
+gems:
+  # Use standard library type definitions
+  - name: net-http
+  - name: uri

data/sig/wikiwiki/api.rbs

@@ -0,0 +1,36 @@
+module Wikiwiki
+  class API
+    attr_reader logger: Logger
+
+    def initialize: (wiki_id: String, auth: Auth::Password | Auth::ApiKey, logger: Logger, ?rate_limiter: RateLimiter) -> void
+
+    def get_pages: () -> Hash[String, Array[Hash[String, String]]]
+
+    def get_page: (encoded_page_name: String) -> Hash[String, String]
+
+    def put_page: (encoded_page_name: String, source: String) -> void
+
+    def get_attachments: (encoded_page_name: String) -> Hash[String, Hash[String, Hash[String, untyped]]]
+
+    def get_attachment: (encoded_page_name: String, encoded_attachment_name: String, ?rev: String?) -> Hash[String, untyped]
+
+    def put_attachment: (encoded_page_name: String, attachment_name: String, encoded_content: String) -> void
+
+    def delete_attachment: (encoded_page_name: String, encoded_attachment_name: String) -> void
+
+    private
+
+    def authenticate: (Auth::Password | Auth::ApiKey auth) -> String
+
+    def parse_json_response: (Net::HTTPResponse response) -> Hash[String, untyped]
+
+    def request: (Symbol method, URI::HTTPS uri, ?body: Hash[String, String]?, ?authenticate: bool) -> Net::HTTPResponse
+
+    def log_request: (Symbol method, URI::HTTPS uri, Net::HTTPRequest request) -> void
+
+    def log_response: (Net::HTTPResponse response) -> void
+
+    attr_reader wiki_id: String
+    attr_reader token: String
+  end
+end

data/sig/wikiwiki/attachment.rbs

@@ -0,0 +1,12 @@
+module Wikiwiki
+  class Attachment
+    attr_reader page_name: String
+    attr_reader name: String
+    attr_reader size: Integer
+    attr_reader time: Time
+    attr_reader type: String
+    attr_reader content: String
+
+    def initialize: (page_name: String, name: String, size: Integer, time: Time, type: String, content: String) -> void
+  end
+end

data/sig/wikiwiki/auth/api_key.rbs

@@ -0,0 +1,10 @@
+module Wikiwiki
+  module Auth
+    class ApiKey
+      attr_reader api_key_id: String
+      attr_reader secret: String
+
+      def initialize: (api_key_id: String, secret: String) -> void
+    end
+  end
+end

data/sig/wikiwiki/auth/password.rbs

@@ -0,0 +1,9 @@
+module Wikiwiki
+  module Auth
+    class Password
+      attr_reader password: String
+
+      def initialize: (password: String) -> void
+    end
+  end
+end

data/sig/wikiwiki/auth.rbs

@@ -0,0 +1,7 @@
+module Wikiwiki
+  module Auth
+    def self.password: (String password) -> Auth::Password
+
+    def self.api_key: (String api_key_id, String secret) -> Auth::ApiKey
+  end
+end

data/sig/wikiwiki/page.rbs

@@ -0,0 +1,9 @@
+module Wikiwiki
+  class Page
+    attr_reader name: String
+    attr_reader source: String
+    attr_reader timestamp: Time
+
+    def initialize: (name: String, source: String, timestamp: Time) -> void
+  end
+end

data/sig/wikiwiki/rate_limiter.rbs

@@ -0,0 +1,41 @@
+module Wikiwiki
+  class RateLimiter
+    def self.raise_on_limit: (Array[{ window: Integer, max_requests: Integer }] limits) -> RateLimiter
+
+    def self.wait_on_limit: (Array[{ window: Integer, max_requests: Integer }] limits) -> RateLimiter
+
+    def self.no_limit: () -> RateLimiter
+
+    def self.default: () -> RateLimiter
+
+    def acquire!: () -> void
+
+    def wait_time_until_available: () -> Float
+
+    def can_request?: () -> bool
+
+    def record!: () -> void
+
+    def wait_time: () -> Float?
+
+    attr_reader mutex: Thread::Mutex
+  end
+
+  module Strategy
+    interface _Strategy
+      def acquire!: (RateLimiter limiter) -> void
+    end
+
+    class Raise
+      include _Strategy
+    end
+
+    class Wait
+      include _Strategy
+    end
+
+    class Null
+      include _Strategy
+    end
+  end
+end

data/sig/wikiwiki/sliding_window.rbs

@@ -0,0 +1,19 @@
+module Wikiwiki
+  class SlidingWindow
+    def initialize: (window: Integer, max_requests: Integer) -> void
+
+    def can_request?: () -> bool
+
+    def record!: () -> void
+
+    def wait_time: () -> Float
+
+    private
+
+    def cleanup!: () -> void
+
+    attr_reader window: Integer
+    attr_reader max_requests: Integer
+    attr_reader requests: Array[Time]
+  end
+end

data/sig/wikiwiki/wiki.rbs

@@ -0,0 +1,28 @@
+module Wikiwiki
+  class Wiki
+    attr_reader logger: Logger
+
+    def initialize: (wiki_id: String, auth: Auth::Password | Auth::ApiKey, ?rate_limiter: RateLimiter, ?logger: Logger) -> void
+
+    def url: () -> URI::HTTPS
+
+    def page_names: () -> Array[String]
+
+    def page: (page_name: String) -> Page
+
+    def update_page: (page_name: String, source: String) -> void
+
+    def attachment_names: (page_name: String) -> Array[String]
+
+    def attachment: (page_name: String, attachment_name: String, ?rev: String?) -> Attachment
+
+    def add_attachment: (page_name: String, attachment_name: String, content: String) -> void
+
+    def delete_attachment: (page_name: String, attachment_name: String) -> void
+
+    private
+
+    attr_reader api: API
+    attr_reader wiki_id: String
+  end
+end

data/sig/wikiwiki.rbs

@@ -0,0 +1,24 @@
+module Wikiwiki
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class RateLimitError < Error
+  end
+
+  class ContentIntegrityError < Error
+  end
+
+  class APIError < Error
+  end
+
+  class AuthenticationError < APIError
+  end
+
+  class ResourceNotFoundError < APIError
+  end
+
+  class ServerError < APIError
+  end
+end