letter_opener_web-s3 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f8303ddd8e04e9bfc35eb37bff20c0c641e1bf1b3886dfecb730653848c144e
+  data.tar.gz: cca476d21c279b3dd9fe566bc72b71a5328e91c4d77961b44157f8c81db17bb8
+SHA512:
+  metadata.gz: 7c68324796054e9a89e592797a79f07ad1e4d66b2ee01a16b3a3068d7d3f8af0c6bd2449eda2bb7e2ae97d516fd40f7bd119e473f284fb4ba98a881c1d7efca6
+  data.tar.gz: 8bd2d3ea6f70b94a1e28d1d18b1241790585a5c043e88e61c6489de8eb3d00b484fcdbfc78a85a000444cd2a92d2033169dd28eb8af3b2c929ca4de7453b2f0d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Letter Opener Web Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# LetterOpenerWeb::S3
+
+Amazon S3 storage backend for [letter_opener_web](https://github.com/fgrehm/letter_opener_web).
+
+This gem allows you to store email letters and attachments on Amazon S3 instead of the local filesystem, enabling multi-instance deployments on platforms like Heroku, Kubernetes, or any containerized environment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'letter_opener_web'
+gem 'letter_opener_web-s3', require: 'letter_opener_web_s3'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+### 1. Configure AWS Credentials
+
+Set up your AWS credentials and S3 bucket in your Rails configuration file (e.g., `config/environments/development.rb`):
+
+```ruby
+# Require the gem first
+require 'letter_opener_web_s3'
+
+LetterOpenerWeb.configure do |config|
+  # Use the S3 storage backend
+  config.letter_class = LetterOpenerWeb::S3Letter
+
+  # AWS Configuration
+  config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  config.aws_region = 'us-east-1'
+  config.aws_bucket = 'my-app-development-emails'
+  config.aws_bucket_prefix = 'letters'  # Optional, defaults to 'letters'
+end
+```
+
+### 2. Configure ActionMailer
+
+Update your ActionMailer configuration to use the S3 delivery method:
+
+```ruby
+config.action_mailer.delivery_method = :letter_opener_web_s3
+```
+
+## Storage Structure
+
+Emails are stored in S3 with the following structure (using default prefix `letters`):
+
+```
+YOUR-BUCKET-NAME/
+└── letters/                    # Configurable via aws_bucket_prefix
+    ├── {timestamp_id_1}/
+    │   ├── plain.html
+    │   ├── rich.html
+    │   └── attachments/
+    │       ├── file1.pdf
+    │       └── file2.jpg
+    └── {timestamp_id_2}/
+        └── ...
+```
+
+You can customize the prefix by setting `config.aws_bucket_prefix` to organize emails under different paths in your bucket.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/letter_opener_web/s3_delivery_method.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'letter_opener'
+
+module LetterOpenerWeb
+  class S3DeliveryMethod < LetterOpener::DeliveryMethod
+    def deliver!(mail)
+      location = create_location
+      message = S3Message.new(mail, location: location)
+      message.render
+    end
+
+    private
+
+    def create_location
+      location = File.join(settings[:location], "#{Time.now.to_i}_#{SecureRandom.hex(16)}")
+      FileUtils.mkdir_p(location)
+      location
+    end
+  end
+end

data/lib/letter_opener_web/s3_letter.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-s3'
+
+module LetterOpenerWeb
+  # S3-based Letter implementation
+  #
+  # Stores and retrieves letters from Amazon S3 instead of the local filesystem.
+  # This enables multi-instance deployments (Heroku, containers, etc.)
+  class S3Letter
+    include LetterOpenerWeb::LetterInterface
+
+    def self.aws_client
+      @aws_client ||= Aws::S3::Client.new(
+        access_key_id: LetterOpenerWeb.config.aws_access_key_id,
+        secret_access_key: LetterOpenerWeb.config.aws_secret_access_key,
+        region: LetterOpenerWeb.config.aws_region
+      )
+    end
+
+    def self.bucket
+      LetterOpenerWeb.config.aws_bucket
+    end
+
+    def self.bucket_prefix
+      LetterOpenerWeb.config.aws_bucket_prefix
+    end
+
+    def self.search
+      response = aws_client.list_objects_v2(
+        bucket: bucket,
+        delimiter: '/',
+        prefix: "#{bucket_prefix}/"
+      )
+
+      letters = response.common_prefixes.map do |prefix|
+        id = prefix.prefix.delete_prefix("#{bucket_prefix}/").delete_suffix('/')
+
+        # Get the last modified time from one of the files in this letter
+        obj = aws_client.list_objects_v2(
+          bucket: bucket,
+          prefix: prefix.prefix,
+          max_keys: 1
+        ).contents.first
+
+        new(id: id, sent_at: obj&.last_modified || Time.now)
+      end
+
+      letters.sort_by(&:sent_at).reverse
+    end
+
+    def self.find(id)
+      new(id: id)
+    end
+
+    def self.destroy_all
+      response = aws_client.list_objects_v2(
+        bucket: bucket,
+        prefix: "#{bucket_prefix}/"
+      )
+
+      return if response.contents.empty?
+
+      objects_to_delete = response.contents.map { |obj| { key: obj.key } }
+
+      aws_client.delete_objects(
+        bucket: bucket,
+        delete: { objects: objects_to_delete }
+      )
+    end
+
+    attr_reader :id, :sent_at
+
+    def initialize(params)
+      @id = params.fetch(:id)
+      @sent_at = params[:sent_at]
+    end
+
+    def headers
+      html = read_file('rich') if file_exists?('rich')
+      html ||= read_file('plain')
+
+      return 'UNABLE TO PARSE HEADERS' if html.blank?
+
+      match_data = html.match(%r{<body>\s*<div[^>]+id="container">\s*<div[^>]+id="message_headers">\s*(<dl>.+</dl>)}m)
+      return remove_attachments_link(match_data[1]).html_safe if match_data && match_data[1].present?
+
+      'UNABLE TO PARSE HEADERS'
+    end
+
+    def plain_text
+      @plain_text ||= adjust_link_targets(read_file('plain'))
+    end
+
+    def rich_text
+      @rich_text ||= adjust_link_targets(read_file('rich'))
+    end
+
+    def attachments
+      @attachments ||= begin
+        response = aws_client.list_objects_v2(
+          bucket: self.class.bucket,
+          prefix: "#{self.class.bucket_prefix}/#{id}/attachments/"
+        )
+
+        response.contents.each_with_object({}) do |obj, hash|
+          filename = File.basename(obj.key)
+          # Generate presigned URL valid for 1 week
+          hash[filename] = presigned_url(obj.key)
+        end
+      end
+    end
+
+    def delete
+      return unless valid?
+
+      response = aws_client.list_objects_v2(
+        bucket: self.class.bucket,
+        prefix: "#{self.class.bucket_prefix}/#{id}/"
+      )
+
+      return if response.contents.empty?
+
+      objects_to_delete = response.contents.map { |obj| { key: obj.key } }
+
+      aws_client.delete_objects(
+        bucket: self.class.bucket,
+        delete: { objects: objects_to_delete }
+      )
+    end
+
+    def valid?
+      file_exists?('rich') || file_exists?('plain')
+    end
+
+    def to_param
+      id
+    end
+
+    def default_style
+      file_exists?('rich') ? 'rich' : 'plain'
+    end
+
+    def send_attachment(controller, filename)
+      return unless attachments.key?(filename)
+
+      response = aws_client.get_object(
+        bucket: self.class.bucket,
+        key: "#{self.class.bucket_prefix}/#{id}/attachments/#{filename}"
+      )
+
+      content = response.body.read
+      content_type = response.content_type || 'application/octet-stream'
+
+      controller.send_data(content, filename: filename, type: content_type, disposition: 'inline')
+    rescue Aws::S3::Errors::NoSuchKey
+      nil
+    end
+
+    private
+
+    def aws_client
+      self.class.aws_client
+    end
+
+    def read_file(style)
+      response = aws_client.get_object(
+        bucket: self.class.bucket,
+        key: "#{self.class.bucket_prefix}/#{id}/#{style}.html"
+      )
+      response.body.read
+    rescue Aws::S3::Errors::NoSuchKey
+      ''
+    end
+
+    def file_exists?(style)
+      aws_client.head_object(
+        bucket: self.class.bucket,
+        key: "#{self.class.bucket_prefix}/#{id}/#{style}.html"
+      )
+      true
+    rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+      false
+    end
+
+    def presigned_url(key)
+      signer = Aws::S3::Presigner.new(client: aws_client)
+      signer.presigned_url(
+        :get_object,
+        bucket: self.class.bucket,
+        key: key,
+        expires_in: 7 * 24 * 60 * 60 # 1 week
+      )
+    end
+
+    def remove_attachments_link(headers)
+      xml = REXML::Document.new(headers)
+      label_element = xml.root.elements.find { |e| e.get_text&.value&.match?(/attachments:/i) }
+
+      if label_element
+        xml.root.delete_element(label_element.next_element)
+        xml.root.delete_element(label_element)
+      end
+
+      xml.to_s
+    end
+
+    def adjust_link_targets(contents)
+      return contents if contents.blank?
+
+      contents.scan(%r{<a\s[^>]+>(?:.|\s)*?</a>}).each do |link|
+        fixed_link = fix_link_html(link)
+        xml = REXML::Document.new(fixed_link).root
+        next if xml.attributes['href'] =~ /(plain|rich).html/
+
+        xml.attributes['target'] = '_blank'
+        xml.add_text('') unless xml.text
+        contents.gsub!(link, xml.to_s)
+      end
+      contents
+    end
+
+    def fix_link_html(link_html)
+      link_html.dup.tap do |fixed_link|
+        fixed_link.gsub!('<br>', '<br/>')
+        fixed_link.scan(/<img(?:[^>]+?)>/).each do |img|
+          fixed_img = img.dup
+          fixed_img.gsub!(/>$/, '/>') unless img =~ %r{/>$}
+          fixed_link.gsub!(img, fixed_img)
+        end
+      end
+    end
+  end
+end

data/lib/letter_opener_web/s3_message.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'letter_opener'
+
+module LetterOpenerWeb
+  # Extends LetterOpener::Message to upload email content to S3
+  #
+  # This class intercepts the message delivery and uploads the generated
+  # HTML files and attachments to S3 instead of keeping them on local disk.
+  class S3Message < LetterOpener::Message
+    def render
+      # Call parent to generate the HTML files locally first
+      super
+
+      # Upload to S3
+      upload_to_s3
+
+      # Clean up local files after uploading
+      cleanup_local_files
+    end
+
+    private
+
+    attr_reader :location
+
+    def upload_to_s3
+      upload_html_files
+      upload_attachments
+    end
+
+    def upload_html_files
+      %w[rich plain].each do |style|
+        file_path = "#{location}/#{style}.html"
+        next unless File.exist?(file_path)
+
+        s3_key = "#{bucket_prefix}/#{letter_id}/#{style}.html"
+        upload_file(file_path, s3_key, 'text/html')
+      end
+    end
+
+    def upload_attachments
+      attachments_dir = "#{location}/attachments"
+      return unless Dir.exist?(attachments_dir)
+
+      Dir.glob("#{attachments_dir}/*").each do |file_path|
+        filename = File.basename(file_path)
+        s3_key = "#{bucket_prefix}/#{letter_id}/attachments/#{filename}"
+        content_type = detect_content_type(file_path)
+        upload_file(file_path, s3_key, content_type)
+      end
+    end
+
+    def upload_file(file_path, s3_key, content_type)
+      File.open(file_path, 'rb') do |file|
+        aws_client.put_object(
+          bucket: bucket,
+          key: s3_key,
+          body: file,
+          content_type: content_type
+        )
+      end
+    end
+
+    def cleanup_local_files
+      FileUtils.rm_rf(location)
+    end
+
+    def letter_id
+      @letter_id ||= File.basename(location)
+    end
+
+    def aws_client
+      @aws_client ||= Aws::S3::Client.new(
+        access_key_id: LetterOpenerWeb.config.aws_access_key_id,
+        secret_access_key: LetterOpenerWeb.config.aws_secret_access_key,
+        region: LetterOpenerWeb.config.aws_region
+      )
+    end
+
+    def bucket
+      LetterOpenerWeb.config.aws_bucket
+    end
+
+    def bucket_prefix
+      LetterOpenerWeb.config.aws_bucket_prefix
+    end
+
+    def detect_content_type(file_path)
+      # Try Marcel if available (comes with Rails/ActiveStorage)
+      if defined?(Marcel)
+        Marcel::MimeType.for(Pathname.new(file_path))
+      else
+        # Fallback: let S3 detect or use generic binary
+        'application/octet-stream'
+      end
+    rescue StandardError
+      'application/octet-stream'
+    end
+  end
+end

data/lib/letter_opener_web_s3.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'letter_opener_web'
+require 'letter_opener_web/s3_letter'
+require 'letter_opener_web/s3_message'
+require 'letter_opener_web/s3_delivery_method'
+
+# Add S3-specific configuration to LetterOpenerWeb::Config immediately
+LetterOpenerWeb::Config.class_eval do
+  attr_accessor :aws_access_key_id,
+                :aws_secret_access_key,
+                :aws_region,
+                :aws_bucket
+  attr_writer :aws_bucket_prefix
+
+  def aws_bucket_prefix
+    @aws_bucket_prefix ||= 'letters'
+  end
+end
+
+module LetterOpenerWeb
+  module S3
+    class Railtie < Rails::Railtie
+      initializer 'letter_opener_web_s3.configure' do
+        # Register custom delivery method that uses S3DeliveryMethod
+        ActionMailer::Base.add_delivery_method(
+          :letter_opener_web_s3,
+          LetterOpenerWeb::S3DeliveryMethod,
+          location: Rails.root.join('tmp', 'letter_opener')
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: letter_opener_web-s3
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Adnan Ali
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: letter_opener_web
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Provides S3-based storage for letter_opener_web, enabling multi-instance
+  deployments on Heroku, containers, and other platforms.
+email:
+- adnan.ali@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/letter_opener_web/s3_delivery_method.rb
+- lib/letter_opener_web/s3_letter.rb
+- lib/letter_opener_web/s3_message.rb
+- lib/letter_opener_web_s3.rb
+homepage: https://github.com/WizaCo/letter_opener_web-s3
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Amazon S3 storage backend for letter_opener_web
+test_files: []