add documentation for encode/decode operations

lib/event_source/operations/mime_decode.rb

@@ -5,16 +5,21 @@
 
 module EventSource
   module Operations
-      # A class for handling payload decoding using Zlib.
+    # Operation for decoding payloads, including decompression using Zlib.
     class MimeDecode
       include Dry::Monads[:result, :do]
 
+      # Supported MIME types for decoding.
       MIME_TYPES = %w[application/zlib application/json].freeze
 
-      # Compresses the payload into a compressed string using Zlib.
+      # Decodes the payload based on the specified MIME type.
+      # For example, decompresses the payload using Zlib for 'application/zlib'.
       #
-      # @return [Dry::Monads::Success<String>] if compression is successful
-      # @return [Dry::Monads::Failure<String>] if an error occurs
+      # @param mime_type [String] the MIME type of the payload (e.g., 'application/zlib', 'application/json')
+      # @param payload [String] the encoded payload to decode
+      #
+      # @return [Dry::Monads::Success<String>] if decoding is successful
+      # @return [Dry::Monads::Failure<String>] if an error occurs (e.g., invalid MIME type, decoding failure)
       def call(mime_type, payload)
         valid_payload = yield validate_payload(payload, mime_type)
         decoded_data = yield decode(valid_payload, mime_type)
@@ -24,22 +29,34 @@ def call(mime_type, payload)
 
       private
 
-      # Validates the payload is binary
+      # Validates the payload based on the MIME type.
+      # Ensures the payload is binary-encoded for 'application/zlib' MIME type.
+      #
+      # @param payload [String] the payload to validate
+      # @param mime_type [String] the MIME type of the payload
       #
       # @return [Dry::Monads::Success<String>] if the payload is valid
       # @return [Dry::Monads::Failure<String>] if the payload is invalid
       def validate_payload(payload, mime_type)
         unless MIME_TYPES.include?(mime_type.to_s)
-          return Failure("Invalid mime type '#{mime_type}'. Supported types are: #{MIME_TYPES.join(', ')}.")
+          return Failure("Invalid MIME type '#{mime_type}'. Supported types are: #{MIME_TYPES.join(', ')}.")
         end
 
         if mime_type.to_s == 'application/zlib' && !binary_payload?(payload)
-          return Failure("Payload must be binary-encoded for mime type 'application/zlib'.")
+          return Failure("Payload must be binary-encoded for MIME type 'application/zlib'.")
         end
 
         Success(payload)
       end
 
+      # Decodes the payload using the specified MIME type.
+      # For 'application/zlib', it decompresses the payload using Zlib.
+      #
+      # @param payload [String] the payload to decode
+      # @param mime_type [String] the MIME type of the payload
+      #
+      # @return [Dry::Monads::Success<String>] if decoding is successful
+      # @return [Dry::Monads::Failure<String>] if decoding fails
       def decode(payload, mime_type)
         decoded_data = Zlib.inflate(payload) if mime_type.to_s == 'application/zlib'
 
@@ -48,14 +65,16 @@ def decode(payload, mime_type)
         Failure("Failed to decode payload using Zlib: #{e.message}")
       end
 
-      # Checks if the payload is in binary encoding.
+      # Checks whether the payload is binary-encoded.
+      #
+      # @param payload [String] the payload to check
       #
-      # @return [Boolean] true if the payload is binary, false otherwise
+      # @return [Boolean] true if the payload is binary-encoded, false otherwise
       def binary_payload?(payload)
         return false unless payload.respond_to?(:encoding)
 
         payload.encoding == Encoding::BINARY
       end
     end
   end
-end
+end

lib/event_source/operations/mime_encode.rb

@@ -5,17 +5,23 @@
 
 module EventSource
   module Operations
-      # A class for handling payload compression.
+    # Operation for encoding payloads into specified MIME types.
+    # For example, it supports compression using Zlib for 'application/zlib'.
     class MimeEncode
       include Dry::Monads[:result, :do]
       include EventSource::Logging
 
+      # Supported MIME types for encoding.
       MIME_TYPES = %w[application/zlib application/json].freeze
 
-      # Compresses the payload into a compressed string using Zlib.
+      # Encodes the given payload into the specified MIME type.
+      # For example, compresses the payload using Zlib for 'application/zlib'.
       #
-      # @return [Dry::Monads::Success<String>] if compression is successful
-      # @return [Dry::Monads::Failure<String>] if an error occurs
+      # @param mime_type [String] the MIME type for encoding (e.g., 'application/zlib', 'application/json')
+      # @param payload [String, Hash] the payload to encode; must be a Hash or String
+      #
+      # @return [Dry::Monads::Success<String>] if encoding is successful
+      # @return [Dry::Monads::Failure<String>] if an error occurs (e.g., invalid MIME type, payload type, or encoding failure)
       def call(mime_type, payload)
         json_payload = yield validate_payload(payload, mime_type)
         encoded_data = yield encode(json_payload, mime_type)
@@ -25,13 +31,17 @@ def call(mime_type, payload)
 
       private
 
-      # Validates the payload before compression and ensures it is a Hash or String.
+      # Validates the payload and MIME type before encoding.
+      # Ensures the MIME type is supported and the payload is either a Hash or a String.
+      #
+      # @param payload [String, Hash] the payload to validate
+      # @param mime_type [String] the MIME type for encoding
       #
-      # @return [Dry::Monads::Success<String>] if the payload is valid
-      # @return [Dry::Monads::Failure<String>] if the payload is invalid
+      # @return [Dry::Monads::Success<String>] if the payload and MIME type are valid
+      # @return [Dry::Monads::Failure<String>] if the MIME type is unsupported or the payload is invalid
       def validate_payload(payload, mime_type)
         unless MIME_TYPES.include?(mime_type.to_s)
-          return Failure("Invalid mime type '#{mime_type}'. Supported types are: #{MIME_TYPES.join(', ')}.")
+          return Failure("Invalid MIME type '#{mime_type}'. Supported types are: #{MIME_TYPES.join(', ')}.")
         end
 
         unless payload.is_a?(Hash) || payload.is_a?(String)
@@ -41,6 +51,15 @@ def validate_payload(payload, mime_type)
         Success(payload.is_a?(Hash) ? payload.to_json : payload)
       end
 
+      # Encodes the payload based on the MIME type.
+      # For 'application/zlib', compresses the payload using Zlib.
+      # Logs the original and encoded payload sizes for debugging.
+      #
+      # @param json_payload [String] the JSON stringified payload to encode
+      # @param mime_type [String] the MIME type for encoding
+      #
+      # @return [Dry::Monads::Success<String>] if encoding is successful
+      # @return [Dry::Monads::Failure<String>] if encoding fails
       def encode(json_payload, mime_type)
         encoded_data = Zlib.deflate(json_payload) if mime_type.to_s == 'application/zlib'
 
@@ -55,6 +74,11 @@ def encode(json_payload, mime_type)
         Failure("Failed to compress payload using Zlib: #{e.message}")
       end
 
+      # Calculates the size of the data in kilobytes (KB).
+      #
+      # @param data [String] the data whose size is to be calculated
+      #
+      # @return [Float] the size of the data in KB, rounded to two decimal places
       def data_size_in_kb(data)
         (data.bytesize / 1024.0).round(2)
       end