From 6c1d34848fa542af68b6ef09e48ee63720ac78ea Mon Sep 17 00:00:00 2001 From: Raghu Ram Date: Mon, 30 Dec 2024 17:35:36 -0500 Subject: [PATCH] add documentation for encode/decode operations --- lib/event_source/operations/mime_decode.rb | 39 +++++++++++++++------ lib/event_source/operations/mime_encode.rb | 40 +++++++++++++++++----- 2 files changed, 61 insertions(+), 18 deletions(-) diff --git a/lib/event_source/operations/mime_decode.rb b/lib/event_source/operations/mime_decode.rb index bf3ae80..f147182 100644 --- a/lib/event_source/operations/mime_decode.rb +++ b/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] if compression is successful - # @return [Dry::Monads::Failure] 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] if decoding is successful + # @return [Dry::Monads::Failure] 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] if the payload is valid # @return [Dry::Monads::Failure] 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] if decoding is successful + # @return [Dry::Monads::Failure] if decoding fails def decode(payload, mime_type) decoded_data = Zlib.inflate(payload) if mime_type.to_s == 'application/zlib' @@ -48,9 +65,11 @@ 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) @@ -58,4 +77,4 @@ def binary_payload?(payload) end end end -end \ No newline at end of file +end diff --git a/lib/event_source/operations/mime_encode.rb b/lib/event_source/operations/mime_encode.rb index 7e28290..c5b6f8e 100644 --- a/lib/event_source/operations/mime_encode.rb +++ b/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] if compression is successful - # @return [Dry::Monads::Failure] 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] if encoding is successful + # @return [Dry::Monads::Failure] 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] if the payload is valid - # @return [Dry::Monads::Failure] if the payload is invalid + # @return [Dry::Monads::Success] if the payload and MIME type are valid + # @return [Dry::Monads::Failure] 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] if encoding is successful + # @return [Dry::Monads::Failure] 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