middleman-s3_sync 4.5.0 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e217a8648de15ba3454749ebf5373e9e2bf31591078be5ae0f5128aeac21d79
-  data.tar.gz: 4f82b54882d96b1ece6585e2075a19d8ef54af78fb8aaec42c07ca14cf41fc7d
+  metadata.gz: 7d5baff2d2863949eb480b7ac94d105d3fdcc2c7df67fab66c649f575dd686a4
+  data.tar.gz: 70c12f42e60eabb0bf063d47a3e42f2766ea883bf47c17557cf323b15a9e546a
 SHA512:
-  metadata.gz: 2640264fb1f0d4c2be50526d966842176ab9997537a4d2f271b0e1e0e29e4398da44f2c66969b08d9f9f4ddeaeef2014a2b2afe3eb68c95986725aa399524f3c
-  data.tar.gz: b9fa2b48b0f63638627750a532e7c7f1fd94a15cf1af4bd9a9826a24021b9fce288d83c9e5d240b4483a0e0488f57b0a7726ede24af9a861d922095bd26eabda
+  metadata.gz: 663ab12a585095543adb3843976e1d24bbf5d3e6bb52a5285b3ce7de5cc7796cb916b72dc330d110225e191325add7e6eed81797abccae9c4e66d0b1d84c8608
+  data.tar.gz: b9b720083616f701318747b661aa04d9257c9539136ae0a2d153cc314eced337baa7ca158cb6e10de1d86ef1bd29cb90cd49b7ee1160c69bdf7b9bab09d4c27f

data/.s3_sync.sample

@@ -1,3 +1,23 @@
 ---
 aws_access_key_id: <AWS Access Key>
 aws_secret_access_key: <AWS Secret Access Key>
+bucket: <S3 Bucket Name>
+region: us-east-1
+delete: true
+after_build: false
+prefer_gzip: true
+path_style: true
+reduced_redundancy_storage: false
+acl: public-read
+encryption: false
+prefix: ''
+version_bucket: false
+index_document: index.html
+error_document: 404.html
+
+# CloudFront Invalidation Settings
+cloudfront_distribution_id: <CloudFront Distribution ID>  # e.g., E1234567890123
+cloudfront_invalidate: false                              # Set to true to enable
+cloudfront_invalidate_all: false                          # Set to true to invalidate all paths (/*) 
+cloudfront_invalidation_batch_size: 1000                  # Max paths per invalidation request
+cloudfront_wait: false                                    # Set to true to wait for invalidation to complete

data/README.md

@@ -54,6 +54,9 @@ activate :s3_sync do |s3_sync|
   s3_sync.version_bucket             = false
   s3_sync.index_document             = 'index.html'
   s3_sync.error_document             = '404.html'
+  s3_sync.cloudfront_distribution_id = 'E1234567890123' # CloudFront distribution ID
+  s3_sync.cloudfront_invalidate      = false # Enable CloudFront invalidation
+  s3_sync.cloudfront_invalidate_all  = false # Invalidate all paths (/*) or only changed files
 end
 ```
 
@@ -76,44 +79,45 @@ The following defaults apply to the configuration items:
 | encryption                 | ```false```                        |
 | acl                        | ```'public-read'```                |
 | version_bucket             | ```false```                        |
+| cloudfront_distribution_id | -                                  |
+| cloudfront_invalidate      | ```false```                        |
+| cloudfront_invalidate_all  | ```false```                        |
+| cloudfront_wait            | ```false```                        |
 
 ## Setting AWS Credentials
 
-There are several ways to provide the AWS credentials for s3_sync. I strongly recommend using some form of federation to assume a role with permissions to publish to your
-S3 bucket. However, you can still use the following methods::We
+There are several secure ways to provide AWS credentials for s3_sync. Using temporary, least-privilege credentials is strongly recommended.
 
-#### Through `config.rb`
+#### Best Practices for AWS Credentials (Recommended)
 
-You can set the aws_access_key_id and aws_secret_access_key in the block
-that is passed to the activate method.
+##### 1. AWS IAM Roles (Most Secure)
 
-> I strongly discourage using this method. This will lead you to add and commit these changes
-> to your SCM and potentially expose sensitive information to the world.
+###### For CI/CD and Cloud Environments
+- **EC2 Instance Profiles**: If running on EC2, use IAM roles attached to your instance. Credentials are automatically rotated and managed by AWS.
+- **ECS Task Roles**: For container workloads, use task roles to provide permissions to specific containers.
+- **CI/CD Service Roles**: Most CI/CD services (GitHub Actions, CircleCI, etc.) offer native AWS integrations that support assuming IAM roles.
 
-#### Through `.s3_sync` File
+###### For Local Development
+- **AWS IAM Identity Center (SSO)** and configured profiles in your AWS config file
+- **AWS CLI credential process** to integrate with external identity providers
+- **Role assumption** with short-lived credentials through `aws sts assume-role`
 
-You can create a `.s3_sync` at the root of your middleman project.
-The credentials are passed in the YAML format. The keys match the
-options keys.
-
-The .s3_sync file takes precedence to the configuration passed in the
-activate method.
-
-A sample `.s3_sync` file is included at the root of this repo.
-
-> Make sure to add .s3_sync to your ignore list if you choose this approach. Not doing so may expose
-> credentials to the world.
+To use these methods, you don't need to specify credentials in your Middleman configuration. The AWS SDK will automatically detect and use them.
 
-#### Through the Command Line
+##### 2. Environment Variables with Temporary Credentials
 
-The aws credentials can also be passed via a command line options
-`--aws_access_key_id` (`-k`) and `--aws_secret_access_key` (`-s`). They should override
-any other settings if specified.
+Using environment variables with short-lived credentials from role assumption:
 
-#### Through Environment
+```bash
+# Obtain temporary credentials via assume-role or similar
+# Then set these environment variables
+export AWS_ACCESS_KEY_ID="temporary-access-key"
+export AWS_SECRET_ACCESS_KEY="temporary-secret-key"
+export AWS_SESSION_TOKEN="temporary-session-token"
+export AWS_BUCKET="your-bucket-name"
+```
 
-You can also pass the credentials through environment variables. They
-map to the following values:
+These environment variables are used when credentials are not otherwise specified:
 
 | Setting               | Environment Variable               |
 | --------------------- | ---------------------------------- |
@@ -122,37 +126,207 @@ map to the following values:
 | aws_session_token     | ```ENV['AWS_SESSION_TOKEN']```     |
 | bucket                | ```ENV['AWS_BUCKET']```            |
 
-The environment is used when the credentials are not set in the activate
-method or passed through the ```.s3_sync``` configuration file.
+#### Alternative Methods (Not Recommended for Production)
 
-#### Through IAM role
+The following methods are less secure and should be avoided in production environments:
 
-Alternatively, if you are running builds on EC2 instance which has approrpiate IAM role, then you don't need to think about specifying credentials at all – they will be pulled from AWS metadata service.
+##### Through `.s3_sync` File
 
-#### IAM Policy
+You can create a `.s3_sync` at the root of your middleman project.
+The credentials are passed in the YAML format. The keys match the options keys.
+
+A sample `.s3_sync` file is included at the root of this repo.
+
+> **SECURITY WARNING**: If using this approach, ensure you add `.s3_sync` to your `.gitignore` to prevent
+> accidentally committing credentials to your repository. Consider using this only for local development
+> and only with temporary credentials.
+
+##### Through `config.rb`
+
+You can set the AWS credentials in the activation block, but this is strongly discouraged:
+
+> **SECURITY WARNING**: This method could lead to credentials being committed to version control,
+> potentially exposing sensitive information. Never use long-lived credentials with this method.
+
+##### Through Command Line
+
+Credentials can be passed via command line options, but this may expose them in shell history:
+
+> **SECURITY WARNING**: Command line parameters may be visible in process listings or shell history.
+> Consider using environment variables or IAM roles instead.
+
+## CloudFront Invalidation
 
-Here's a sample IAM policy that will allow a user to update the site
-contained in a bucket named "mysite.com":
+The gem can automatically invalidate CloudFront cache after a successful sync. This ensures that your CloudFront distribution serves the latest content immediately after deployment.
 
+### Configuration
+
+```ruby
+activate :s3_sync do |s3_sync|
+  # ... other configuration ...
+  s3_sync.cloudfront_distribution_id = 'E1234567890123'  # Your CloudFront distribution ID
+  s3_sync.cloudfront_invalidate      = true             # Enable invalidation
+  s3_sync.cloudfront_invalidate_all  = false            # Invalidate only changed files
+end
 ```
+
+### Configuration Options
+
+| Setting                           | Default     | Description |
+| --------------------------------- | ----------- | ----------- |
+| cloudfront_distribution_id        | -           | CloudFront distribution ID to invalidate |
+| cloudfront_invalidate             | ```false``` | Enable CloudFront invalidation after sync |
+| cloudfront_invalidate_all         | ```false``` | Invalidate all paths (/*) instead of only changed files |
+| cloudfront_invalidation_batch_size| ```1000```  | Maximum paths per invalidation request |
+| cloudfront_wait                   | ```false``` | Wait for CloudFront invalidation to complete |
+</edits>
+
+### Command Line Options
+
+You can also control CloudFront invalidation via command line:
+
+```bash
+# Enable CloudFront invalidation for this sync
+middleman s3_sync --cloudfront-invalidate --cloudfront-distribution-id E1234567890123
+
+# Invalidate all paths instead of just changed files
+middleman s3_sync --cloudfront-invalidate-all --cloudfront-distribution-id E1234567890123
+
+# Wait for invalidation to complete before exiting
+middleman s3_sync --cloudfront-invalidate --cloudfront-wait --cloudfront-distribution-id E1234567890123
+
+# Custom batch size for large numbers of files
+middleman s3_sync --cloudfront-invalidate --cloudfront-invalidation-batch-size 500 --cloudfront-distribution-id E1234567890123
+
+# Short aliases
+middleman s3_sync -c -d E1234567890123              # Basic invalidation
+middleman s3_sync -a -d E1234567890123              # Invalidate all paths
+middleman s3_sync -c -w -d E1234567890123           # Invalidate and wait
+middleman s3_sync -c -a -w -d E1234567890123        # Invalidate all and wait
+```
+
+#### Available CloudFront Command Line Options
+
+| Option | Short | Description |
+| ------ | ----- | ----------- |
+| `--cloudfront-distribution-id` | `-d` | CloudFront distribution ID |
+| `--cloudfront-invalidate` | `-c` | Enable CloudFront invalidation |
+| `--cloudfront-invalidate-all` | `-a` | Invalidate all paths (/*) |
+| `--cloudfront-invalidation-batch-size` | - | Max paths per request (default: 1000) |
+| `--cloudfront-wait` | `-w` | Wait for invalidation to complete |
+
+### How It Works
+
+1. **Smart Invalidation**: By default, only files that were created, updated, or deleted during the sync are invalidated
+2. **Path Optimization**: Duplicate paths are removed and redundant paths (covered by wildcards) are eliminated
+3. **Batch Processing**: Large numbers of paths are split into multiple invalidation requests to respect CloudFront limits
+4. **Error Handling**: Invalidation failures are logged but don't stop the sync process
+5. **Dry Run Support**: Use `--dry-run` to see what would be invalidated without making actual API calls
+
+### IAM Permissions
+
+Your AWS credentials need CloudFront permissions in addition to S3:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "cloudfront:CreateInvalidation",
+        "cloudfront:GetInvalidation",
+        "cloudfront:ListInvalidations"
+      ],
+      "Resource": "arn:aws:cloudfront::*:distribution/E1234567890123"
+    }
+  ]
+}
+```
+
+### Cost Considerations
+
+- CloudFront allows 1,000 free invalidation paths per month
+- Additional invalidations cost $0.005 per path
+- Use `cloudfront_invalidate_all: true` for major updates to minimize costs (counts as 1 path)
+- Consider the trade-off between immediate cache invalidation and cost
+
+#### IAM Policy
+
+Here's a sample IAM policy with least-privilege permissions that will allow syncing to a bucket named "mysite.com":
+
+```json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
       "Effect": "Allow",
-      "Action": "s3:*",
+      "Action": [
+        "s3:ListBucket",
+        "s3:GetBucketLocation",
+        "s3:GetBucketVersioning"
+      ],
       "Resource": "arn:aws:s3:::mysite.com"
     },
     {
       "Effect": "Allow",
-      "Action": "s3:*",
+      "Action": [
+        "s3:PutObject",
+        "s3:PutObjectAcl",
+        "s3:GetObject",
+        "s3:GetObjectAcl",
+        "s3:DeleteObject",
+        "s3:HeadObject"
+      ],
       "Resource": "arn:aws:s3:::mysite.com/*"
     }
   ]
 }
 ```
 
-This will give full access to both the bucket and it's contents.
+If you're using additional features, you may need these permissions as well:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutBucketWebsite",
+        "s3:PutBucketVersioning"
+      ],
+      "Resource": "arn:aws:s3:::mysite.com",
+      "Condition": {
+        "Bool": {
+          "aws:SecureTransport": "true"
+        }
+      }
+    }
+  ]
+}
+```
+
+This policy grants only the specific permissions needed:
+
+- **For the bucket itself**:
+  - `s3:ListBucket`: To list objects in the bucket
+  - `s3:GetBucketLocation`: To determine the bucket's region
+  - `s3:GetBucketVersioning`: To check versioning status
+  - `s3:PutBucketVersioning`: If using the `version_bucket` option
+  - `s3:PutBucketWebsite`: If using website configuration (index/error documents)
+
+- **For objects in the bucket**:
+  - `s3:PutObject`: To create/update objects
+  - `s3:PutObjectAcl`: To set ACLs on objects
+  - `s3:GetObject`: To retrieve objects for comparison
+  - `s3:GetObjectAcl`: To read existing ACLs
+  - `s3:DeleteObject`: To delete stray objects (when `delete: true`)
+  - `s3:HeadObject`: To retrieve object metadata via HEAD requests
+
+The source code shows that middleman-s3_sync uses HEAD requests (`object.head`) to compare resources, checks and sets bucket versioning when configured, and can set website configuration for index and error documents.
+
+Note: You can further restrict these permissions by adding conditions or limiting them to specific prefixes if you're only publishing to a subdirectory of the bucket.
 
 ## Command Line Usage
 

data/lib/middleman/s3_sync/cloudfront.rb

@@ -0,0 +1,192 @@
+require 'aws-sdk-cloudfront'
+require 'securerandom'
+
+module Middleman
+  module S3Sync
+    module CloudFront
+      class << self
+        include Status
+
+        def invalidate(invalidation_paths, options)
+          return unless should_invalidate?(options)
+          return if invalidation_paths.empty? && !options.cloudfront_invalidate_all
+
+          paths = prepare_invalidation_paths(invalidation_paths, options)
+          return if paths.empty?
+
+          say_status "Invalidating CloudFront distribution #{options.cloudfront_distribution_id}"
+          
+          if options.dry_run
+            say_status "#{ANSI.yellow{'DRY RUN:'}} Would invalidate #{paths.length} paths in CloudFront"
+            paths.each { |path| say_status "  #{path}" } if options.verbose
+            return
+          end
+
+          # Split paths into batches to respect CloudFront limits
+          batch_size = [options.cloudfront_invalidation_batch_size, 3000].min
+          path_batches = paths.each_slice(batch_size).to_a
+
+          invalidation_ids = []
+          
+          path_batches.each_with_index do |batch, index|
+            say_status "Creating invalidation batch #{index + 1}/#{path_batches.length} (#{batch.length} paths)"
+            
+            invalidation_id = create_invalidation(batch, options)
+            invalidation_ids << invalidation_id if invalidation_id
+            
+            # Add a small delay between batches to avoid rate limiting
+            sleep(1) if path_batches.length > 1 && index < path_batches.length - 1
+          end
+
+          if invalidation_ids.any?
+            say_status "CloudFront invalidation(s) created: #{invalidation_ids.join(', ')}"
+            
+            if options.cloudfront_wait
+              say_status "Waiting for CloudFront invalidation(s) to complete..."
+              wait_for_invalidations(invalidation_ids, options)
+              say_status "CloudFront invalidation(s) completed successfully"
+            else
+              say_status "Invalidations may take 10-15 minutes to complete"
+            end
+          end
+
+          invalidation_ids
+        rescue Aws::CloudFront::Errors::ServiceError => e
+          say_status "#{ANSI.red{'CloudFront invalidation failed:'}} #{e.message}"
+          raise e unless options.verbose # Re-raise unless we're being verbose
+        end
+
+        private
+
+        def should_invalidate?(options)
+          return false unless options.cloudfront_invalidate
+          
+          unless options.cloudfront_distribution_id
+            say_status "#{ANSI.yellow{'CloudFront invalidation skipped:'}} no distribution ID provided"
+            return false
+          end
+
+          true
+        end
+
+        def prepare_invalidation_paths(invalidation_paths, options)
+          if options.cloudfront_invalidate_all
+            return ['/*']
+          end
+
+          # Normalize paths for CloudFront
+          paths = invalidation_paths.map do |path|
+            # Ensure path starts with /
+            normalized_path = path.start_with?('/') ? path : "/#{path}"
+            
+            # Remove any double slashes
+            normalized_path.gsub(/\/+/, '/')
+          end.uniq.sort
+
+          # Remove any paths that would be covered by a wildcard
+          if paths.include?('/*')
+            paths = ['/*']
+          else
+            # Remove redundant paths (e.g., if we have /path/* and /path/file.html)
+            paths = remove_redundant_paths(paths)
+          end
+
+          say_status "Prepared #{paths.length} paths for CloudFront invalidation" if options.verbose
+
+          paths
+        end
+
+        def remove_redundant_paths(paths)
+          # Sort paths to ensure wildcards come before specific files
+          sorted_paths = paths.sort
+          result = []
+          
+          sorted_paths.each do |path|
+            # Check if this path is already covered by a wildcard we've added
+            is_redundant = result.any? do |existing_path|
+              if existing_path.end_with?('/*')
+                # Check if current path is under this wildcard
+                wildcard_prefix = existing_path[0..-3] # Remove /*
+                path.start_with?(wildcard_prefix + '/')
+              else
+                false
+              end
+            end
+            
+            result << path unless is_redundant
+          end
+          
+          result
+        end
+
+        def create_invalidation(paths, options)
+          caller_reference = "middleman-s3_sync-#{Time.now.to_i}-#{SecureRandom.hex(4)}"
+          
+          response = cloudfront_client(options).create_invalidation({
+            distribution_id: options.cloudfront_distribution_id,
+            invalidation_batch: {
+              paths: {
+                quantity: paths.length,
+                items: paths
+              },
+              caller_reference: caller_reference
+            }
+          })
+
+          response.invalidation.id
+        rescue Aws::CloudFront::Errors::ServiceError => e
+          say_status "#{ANSI.red{'Failed to create CloudFront invalidation:'}} #{e.message}"
+          say_status "Paths: #{paths.join(', ')}" if options.verbose
+          raise e unless options.verbose
+          nil
+        end
+
+        def cloudfront_client(options)
+          client_options = {
+            region: 'us-east-1' # CloudFront is always in us-east-1
+          }
+
+          # Use the same credentials as S3 if available
+          if options.aws_access_key_id && options.aws_secret_access_key
+            client_options.merge!({
+              access_key_id: options.aws_access_key_id,
+              secret_access_key: options.aws_secret_access_key
+            })
+
+            # If using an assumed role
+            client_options.merge!({
+              session_token: options.aws_session_token
+            }) if options.aws_session_token
+          end
+
+          Aws::CloudFront::Client.new(client_options)
+        end
+
+        def wait_for_invalidations(invalidation_ids, options)
+          invalidation_ids.each do |invalidation_id|
+            say_status "Waiting for invalidation #{invalidation_id}..."
+            
+            client = cloudfront_client(options)
+            client.wait_until(:invalidation_completed, 
+              distribution_id: options.cloudfront_distribution_id,
+              id: invalidation_id
+            ) do |waiter|
+              waiter.max_attempts = 30  # Wait up to 30 minutes (30 * 60s checks)
+              waiter.delay = 60         # Check every 60 seconds
+              
+              waiter.before_attempt do |attempt|
+                say_status "Checking invalidation status (attempt #{attempt}/30)..." if options.verbose
+              end
+            end
+          end
+        rescue Aws::Waiters::Errors::WaiterFailed => e
+          say_status "#{ANSI.yellow{'Warning:'}} CloudFront invalidation wait timed out: #{e.message}"
+          say_status "Invalidation is still in progress but sync will continue"
+        rescue Aws::CloudFront::Errors::ServiceError => e
+          say_status "#{ANSI.yellow{'Warning:'}} CloudFront invalidation wait failed: #{e.message}"
+          say_status "Invalidation may still be in progress"
+        end
+      end
+    end
+  end
+end

data/lib/middleman/s3_sync/version.rb

@@ -1,5 +1,5 @@
 module Middleman
   module S3Sync
-    VERSION = "4.5.0"
+    VERSION = "4.6.0"
   end
 end

data/lib/middleman/s3_sync.rb

@@ -5,6 +5,7 @@ require 'middleman/s3_sync/options'
 require 'middleman/s3_sync/caching_policy'
 require 'middleman/s3_sync/status'
 require 'middleman/s3_sync/resource'
+require 'middleman/s3_sync/cloudfront'
 require 'middleman-s3_sync/extension'
 require 'middleman/redirect'
 require 'parallel'
@@ -25,13 +26,22 @@ module Middleman
       attr_reader   :app
 
       THREADS_COUNT = 8
+      
+      # Track paths that were changed during sync for CloudFront invalidation
+      attr_accessor :invalidation_paths
 
       def sync()
         @app ||= ::Middleman::Application.new
+        @invalidation_paths = []
 
         say_status "Let's see if there's work to be done..."
         unless work_to_be_done?
           say_status "All S3 files are up to date."
+          
+          # Still run CloudFront invalidation if requested for all paths
+          if s3_sync_options.cloudfront_invalidate && s3_sync_options.cloudfront_invalidate_all
+            CloudFront.invalidate([], s3_sync_options)
+          end
           return
         end
 
@@ -45,6 +55,11 @@ module Middleman
         create_resources
         update_resources
         delete_resources
+        
+        # Invalidate CloudFront cache if requested
+        if s3_sync_options.cloudfront_invalidate
+          CloudFront.invalidate(@invalidation_paths, s3_sync_options)
+        end
       end
 
       def bucket
@@ -60,6 +75,13 @@ module Middleman
       def add_local_resource(mm_resource)
         s3_sync_resources[mm_resource.destination_path] = S3Sync::Resource.new(mm_resource, remote_resource_for_path(mm_resource.destination_path)).tap(&:status)
       end
+      
+      def add_invalidation_path(path)
+        @invalidation_paths ||= []
+        # Normalize path for CloudFront (ensure it starts with /)
+        normalized_path = path.start_with?('/') ? path : "/#{path}"
+        @invalidation_paths << normalized_path unless @invalidation_paths.include?(normalized_path)
+      end
 
       def remote_only_paths
         paths - s3_sync_resources.keys
@@ -168,15 +190,24 @@ module Middleman
       end
 
       def create_resources
-        Parallel.map(files_to_create, in_threads: THREADS_COUNT, &:create!)
+        Parallel.map(files_to_create, in_threads: THREADS_COUNT) do |resource|
+          resource.create!
+          add_invalidation_path(resource.path)
+        end
       end
 
       def update_resources
-        Parallel.map(files_to_update, in_threads: THREADS_COUNT, &:update!)
+        Parallel.map(files_to_update, in_threads: THREADS_COUNT) do |resource|
+          resource.update!
+          add_invalidation_path(resource.path)
+        end
       end
 
       def delete_resources
-        Parallel.map(files_to_delete, in_threads: THREADS_COUNT, &:destroy!)
+        Parallel.map(files_to_delete, in_threads: THREADS_COUNT) do |resource|
+          resource.destroy!
+          add_invalidation_path(resource.path)
+        end
       end
 
       def ignore_resources

data/lib/middleman-s3_sync/commands.rb

@@ -65,6 +65,30 @@ module Middleman
                    type: :string,
                    desc: 'Print instrument messages.'
 
+      class_option :cloudfront_distribution_id,
+                   aliases: '-d',
+                   type: :string,
+                   desc: 'CloudFront distribution ID for invalidation.'
+
+      class_option :cloudfront_invalidate,
+                   aliases: '-c',
+                   type: :boolean,
+                   desc: 'Invalidate CloudFront cache after sync.'
+
+      class_option :cloudfront_invalidate_all,
+                   aliases: '-a',
+                   type: :boolean,
+                   desc: 'Invalidate all paths (/*) instead of only changed files.'
+
+      class_option :cloudfront_invalidation_batch_size,
+                   type: :numeric,
+                   desc: 'Maximum number of paths to invalidate in a single request (default: 1000).'
+
+      class_option :cloudfront_wait,
+                   aliases: '-w',
+                   type: :boolean,
+                   desc: 'Wait for CloudFront invalidation to complete before exiting.'
+
       def s3_sync
         env = options[:environment].to_s.to_sym
         verbose = options[:verbose] ? 0 : 1
@@ -99,6 +123,11 @@ module Middleman
           s3_sync_options.prefix = s3_sync_options.prefix.end_with?('/') ? s3_sync_options.prefix : s3_sync_options.prefix + '/'
         end
         s3_sync_options.dry_run = options[:dry_run] if options[:dry_run]
+        s3_sync_options.cloudfront_distribution_id = options[:cloudfront_distribution_id] if options[:cloudfront_distribution_id]
+        s3_sync_options.cloudfront_invalidate = options[:cloudfront_invalidate] if options[:cloudfront_invalidate]
+        s3_sync_options.cloudfront_invalidate_all = options[:cloudfront_invalidate_all] if options[:cloudfront_invalidate_all]
+        s3_sync_options.cloudfront_invalidation_batch_size = options[:cloudfront_invalidation_batch_size] if options[:cloudfront_invalidation_batch_size]
+        s3_sync_options.cloudfront_wait = options[:cloudfront_wait] if options[:cloudfront_wait]
 
         ::Middleman::S3Sync.sync()
       end

data/lib/middleman-s3_sync/extension.rb

@@ -29,6 +29,11 @@ module Middleman
     option :error_document, nil, 'S3 custom error document path'
     option :content_types, {}, 'Custom content types'
     option :ignore_paths, [], 'Paths that should be ignored during sync, strings or regex are allowed'
+    option :cloudfront_distribution_id, nil, 'CloudFront distribution ID for invalidation'
+    option :cloudfront_invalidate, false, 'Whether to invalidate CloudFront cache after sync'
+    option :cloudfront_invalidate_all, false, 'Whether to invalidate all paths (/*) or only changed files'
+    option :cloudfront_invalidation_batch_size, 1000, 'Maximum number of paths to invalidate in a single request'
+    option :cloudfront_wait, false, 'Whether to wait for CloudFront invalidation to complete'
 
     expose_to_config :s3_sync_options, :default_caching_policy, :caching_policy
 

data/middleman-s3_sync.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency 'middleman-cli'
   gem.add_runtime_dependency 'unf'
   gem.add_runtime_dependency 'aws-sdk-s3'
+  gem.add_runtime_dependency 'aws-sdk-cloudfront'
   gem.add_runtime_dependency 'map'
   gem.add_runtime_dependency 'parallel'
   gem.add_runtime_dependency 'ruby-progressbar'

data/spec/cloudfront_spec.rb

@@ -0,0 +1,391 @@
+require 'spec_helper'
+require 'middleman/s3_sync/cloudfront'
+
+describe Middleman::S3Sync::CloudFront do
+  let(:options) do
+    double(
+      cloudfront_invalidate: true,
+      cloudfront_distribution_id: 'E1234567890123',
+      cloudfront_invalidate_all: false,
+      cloudfront_invalidation_batch_size: 1000,
+      cloudfront_wait: false,
+      aws_access_key_id: 'test_key',
+      aws_secret_access_key: 'test_secret',
+      aws_session_token: nil,
+      dry_run: false,
+      verbose: false
+    )
+  end
+
+  let(:invalidation_response) do
+    double(
+      invalidation: double(id: 'I1234567890123')
+    )
+  end
+
+  before do
+    allow(described_class).to receive(:say_status)
+  end
+
+  describe '.invalidate' do
+    context 'when CloudFront invalidation is disabled' do
+      let(:options) do
+        double(cloudfront_invalidate: false)
+      end
+
+      it 'returns early without doing anything' do
+        expect(Aws::CloudFront::Client).not_to receive(:new)
+        result = described_class.invalidate(['/path1', '/path2'], options)
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when no distribution ID is provided' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: nil
+        )
+      end
+
+      it 'skips invalidation and shows warning' do
+        expect(described_class).to receive(:say_status).with(
+          match(/CloudFront invalidation skipped.*no distribution ID/)
+        )
+        expect(Aws::CloudFront::Client).not_to receive(:new)
+        result = described_class.invalidate(['/path1', '/path2'], options)
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when dry run is enabled' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: false,
+          dry_run: true,
+          verbose: true
+        )
+      end
+
+      it 'shows what would be invalidated without making API calls' do
+        expect(described_class).to receive(:say_status).with(
+          'Invalidating CloudFront distribution E1234567890123'
+        )
+        expect(described_class).to receive(:say_status).with(
+          match(/DRY RUN.*Would invalidate 2 paths/)
+        )
+        expect(described_class).to receive(:say_status).with('  /path1')
+        expect(described_class).to receive(:say_status).with('  /path2')
+        expect(Aws::CloudFront::Client).not_to receive(:new)
+
+        result = described_class.invalidate(['/path1', '/path2'], options)
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when invalidating all paths' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: true,
+          cloudfront_invalidation_batch_size: 1000,
+          cloudfront_wait: false,
+          aws_access_key_id: 'test_key',
+          aws_secret_access_key: 'test_secret',
+          aws_session_token: nil,
+          dry_run: false,
+          verbose: false
+        )
+      end
+
+      it 'invalidates all paths with /*' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).with({
+          distribution_id: 'E1234567890123',
+          invalidation_batch: {
+            paths: {
+              quantity: 1,
+              items: ['/*']
+            },
+            caller_reference: match(/middleman-s3_sync-\d+-[a-f0-9]{8}/)
+          }
+        }).and_return(invalidation_response)
+
+        result = described_class.invalidate(['/path1', '/path2'], options)
+        expect(result).to eq(['I1234567890123'])
+      end
+    end
+
+    context 'when invalidating specific paths' do
+      it 'creates invalidation for the provided paths' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).with({
+          distribution_id: 'E1234567890123',
+          invalidation_batch: {
+            paths: {
+              quantity: 2,
+              items: ['/path1', '/path2']
+            },
+            caller_reference: match(/middleman-s3_sync-\d+-[a-f0-9]{8}/)
+          }
+        }).and_return(invalidation_response)
+
+        result = described_class.invalidate(['/path1', '/path2'], options)
+        expect(result).to eq(['I1234567890123'])
+      end
+
+      it 'normalizes paths to start with /' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).with({
+          distribution_id: 'E1234567890123',
+          invalidation_batch: {
+            paths: {
+              quantity: 2,
+              items: ['/path1', '/path2']
+            },
+            caller_reference: match(/middleman-s3_sync-\d+-[a-f0-9]{8}/)
+          }
+        }).and_return(invalidation_response)
+
+        result = described_class.invalidate(['path1', '/path2'], options)
+        expect(result).to eq(['I1234567890123'])
+      end
+
+      it 'removes duplicate paths' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).with({
+          distribution_id: 'E1234567890123',
+          invalidation_batch: {
+            paths: {
+              quantity: 2,
+              items: ['/path1', '/path2']
+            },
+            caller_reference: match(/middleman-s3_sync-\d+-[a-f0-9]{8}/)
+          }
+        }).and_return(invalidation_response)
+
+        result = described_class.invalidate(['/path1', 'path1', '/path2'], options)
+        expect(result).to eq(['I1234567890123'])
+      end
+
+      it 'removes double slashes from paths' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).with({
+          distribution_id: 'E1234567890123',
+          invalidation_batch: {
+            paths: {
+              quantity: 1,
+              items: ['/path/to/file.html']
+            },
+            caller_reference: match(/middleman-s3_sync-\d+-[a-f0-9]{8}/)
+          }
+        }).and_return(invalidation_response)
+
+        result = described_class.invalidate(['//path//to//file.html'], options)
+        expect(result).to eq(['I1234567890123'])
+      end
+    end
+
+    context 'with large batch sizes' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: false,
+          cloudfront_invalidation_batch_size: 2,
+          cloudfront_wait: false,
+          aws_access_key_id: 'test_key',
+          aws_secret_access_key: 'test_secret',
+          aws_session_token: nil,
+          dry_run: false,
+          verbose: false
+        )
+      end
+
+      it 'splits paths into multiple batches' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        paths = ['/path1', '/path2', '/path3', '/path4']
+        
+        expect(client).to receive(:create_invalidation).twice.and_return(invalidation_response)
+        expect(described_class).to receive(:sleep).with(1)
+
+        result = described_class.invalidate(paths, options)
+        expect(result).to eq(['I1234567890123', 'I1234567890123'])
+      end
+    end
+
+    context 'when CloudFront API returns an error' do
+      let(:error) { Aws::CloudFront::Errors::ServiceError.new(nil, 'Distribution not found') }
+
+      it 'handles API errors gracefully' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).and_raise(error)
+        expect(described_class).to receive(:say_status).with(
+          match(/Failed to create CloudFront invalidation.*Distribution not found/)
+        )
+
+        expect {
+          described_class.invalidate(['/path1'], options)
+        }.to raise_error(Aws::CloudFront::Errors::ServiceError)
+      end
+
+      context 'when verbose mode is enabled' do
+        let(:options) do
+          double(
+            cloudfront_invalidate: true,
+            cloudfront_distribution_id: 'E1234567890123',
+            cloudfront_invalidate_all: false,
+            cloudfront_invalidation_batch_size: 1000,
+            cloudfront_wait: false,
+            aws_access_key_id: 'test_key',
+            aws_secret_access_key: 'test_secret',
+            aws_session_token: nil,
+            dry_run: false,
+            verbose: true
+          )
+        end
+
+        it 'does not re-raise errors in verbose mode' do
+          client = double('cloudfront_client')
+          allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+          expect(client).to receive(:create_invalidation).and_raise(error)
+          expect(described_class).to receive(:say_status).with(
+            match(/Failed to create CloudFront invalidation/)
+          )
+
+          expect {
+            described_class.invalidate(['/path1'], options)
+          }.not_to raise_error
+        end
+      end
+    end
+
+    context 'with empty paths and invalidate_all false' do
+      it 'returns early without making API calls' do
+        expect(Aws::CloudFront::Client).not_to receive(:new)
+        result = described_class.invalidate([], options)
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when cloudfront_wait is enabled' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: false,
+          cloudfront_invalidation_batch_size: 1000,
+          cloudfront_wait: true,
+          aws_access_key_id: 'test_key',
+          aws_secret_access_key: 'test_secret',
+          aws_session_token: nil,
+          dry_run: false,
+          verbose: false
+        )
+      end
+
+      it 'waits for invalidation to complete' do
+        client = double('cloudfront_client')
+        allow(Aws::CloudFront::Client).to receive(:new).and_return(client)
+        expect(client).to receive(:create_invalidation).and_return(invalidation_response)
+        expect(client).to receive(:wait_until).with(:invalidation_completed, 
+          distribution_id: 'E1234567890123',
+          id: 'I1234567890123'
+        )
+        expect(described_class).to receive(:say_status).with(
+          'Waiting for CloudFront invalidation(s) to complete...'
+        )
+        expect(described_class).to receive(:say_status).with(
+          'CloudFront invalidation(s) completed successfully'
+        )
+
+        result = described_class.invalidate(['/path1'], options)
+        expect(result).to eq(['I1234567890123'])
+      end
+    end
+  end
+
+  describe 'CloudFront client configuration' do
+    it 'creates client with correct credentials' do
+      client = double('cloudfront_client')
+      expect(Aws::CloudFront::Client).to receive(:new).with({
+        region: 'us-east-1',
+        access_key_id: 'test_key',
+        secret_access_key: 'test_secret'
+      }).and_return(client)
+
+      expect(client).to receive(:create_invalidation).and_return(invalidation_response)
+
+      described_class.invalidate(['/test'], options)
+    end
+
+    context 'with session token' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: false,
+          cloudfront_invalidation_batch_size: 1000,
+          cloudfront_wait: false,
+          aws_access_key_id: 'test_key',
+          aws_secret_access_key: 'test_secret',
+          aws_session_token: 'test_token',
+          dry_run: false,
+          verbose: false
+        )
+      end
+
+      it 'includes session token in client configuration' do
+        client = double('cloudfront_client')
+        expect(Aws::CloudFront::Client).to receive(:new).with({
+          region: 'us-east-1',
+          access_key_id: 'test_key',
+          secret_access_key: 'test_secret',
+          session_token: 'test_token'
+        }).and_return(client)
+
+        expect(client).to receive(:create_invalidation).and_return(invalidation_response)
+
+        described_class.invalidate(['/test'], options)
+      end
+    end
+
+    context 'without explicit credentials' do
+      let(:options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: false,
+          cloudfront_invalidation_batch_size: 1000,
+          cloudfront_wait: false,
+          aws_access_key_id: nil,
+          aws_secret_access_key: nil,
+          aws_session_token: nil,
+          dry_run: false,
+          verbose: false
+        )
+      end
+
+      it 'creates client without explicit credentials (uses default chain)' do
+        client = double('cloudfront_client')
+        expect(Aws::CloudFront::Client).to receive(:new).with({
+          region: 'us-east-1'
+        }).and_return(client)
+
+        expect(client).to receive(:create_invalidation).and_return(invalidation_response)
+
+        described_class.invalidate(['/test'], options)
+      end
+    end
+  end
+end

data/spec/s3_sync_integration_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+require 'middleman/s3_sync'
+
+describe 'S3Sync CloudFront Integration' do
+  let(:app) { double('middleman_app') }
+  let(:s3_sync_options) do
+    double(
+      cloudfront_invalidate: true,
+      cloudfront_distribution_id: 'E1234567890123',
+      cloudfront_invalidate_all: false,
+      cloudfront_invalidation_batch_size: 1000,
+      aws_access_key_id: 'test_key',
+      aws_secret_access_key: 'test_secret',
+      aws_session_token: nil,
+      dry_run: false,
+      verbose: false,
+      delete: true,
+      bucket: 'test-bucket'
+    )
+  end
+
+  before do
+    allow(::Middleman::Application).to receive(:new).and_return(app)
+    allow(Middleman::S3Sync).to receive(:s3_sync_options).and_return(s3_sync_options)
+    allow(Middleman::S3Sync).to receive(:say_status)
+    allow(Middleman::S3Sync).to receive(:work_to_be_done?).and_return(true)
+    allow(Middleman::S3Sync).to receive(:update_bucket_versioning)
+    allow(Middleman::S3Sync).to receive(:update_bucket_website)
+    allow(Middleman::S3Sync).to receive(:ignore_resources)
+    allow(Middleman::S3Sync).to receive(:create_resources)
+    allow(Middleman::S3Sync).to receive(:update_resources)
+    allow(Middleman::S3Sync).to receive(:delete_resources)
+    allow(Middleman::S3Sync::CloudFront).to receive(:invalidate)
+  end
+
+  describe 'CloudFront invalidation integration' do
+    it 'calls CloudFront invalidation after sync operations' do
+      # Reset invalidation paths for this test
+      Middleman::S3Sync.instance_variable_set(:@invalidation_paths, [])
+      
+      expect(Middleman::S3Sync::CloudFront).to receive(:invalidate).with(
+        [], # Initially empty, gets populated during resource operations
+        s3_sync_options
+      )
+
+      Middleman::S3Sync.sync
+    end
+
+    it 'calls CloudFront invalidation with collected paths' do
+      # Mock the methods to inject paths during sync
+      allow(Middleman::S3Sync).to receive(:create_resources) do
+        Middleman::S3Sync.add_invalidation_path('/updated/file.html')
+      end
+      allow(Middleman::S3Sync).to receive(:update_resources) do
+        Middleman::S3Sync.add_invalidation_path('/new/file.css')
+      end
+
+      expect(Middleman::S3Sync::CloudFront).to receive(:invalidate) do |paths, options|
+        expect(paths).to include('/updated/file.html')
+        expect(paths).to include('/new/file.css')
+        expect(options).to eq(s3_sync_options)
+      end
+
+      Middleman::S3Sync.sync
+    end
+
+    context 'when cloudfront_invalidate_all is true' do
+      let(:s3_sync_options) do
+        double(
+          cloudfront_invalidate: true,
+          cloudfront_distribution_id: 'E1234567890123',
+          cloudfront_invalidate_all: true,
+          bucket: 'test-bucket'
+        )
+      end
+
+      it 'still calls CloudFront invalidation even when no work is needed' do
+        allow(Middleman::S3Sync).to receive(:work_to_be_done?).and_return(false)
+        
+        expect(Middleman::S3Sync::CloudFront).to receive(:invalidate).with(
+          [], s3_sync_options
+        )
+
+        Middleman::S3Sync.sync
+      end
+    end
+
+    context 'when CloudFront invalidation is disabled' do
+      let(:s3_sync_options) do
+        double(
+          cloudfront_invalidate: false,
+          bucket: 'test-bucket'
+        )
+      end
+
+      it 'does not call CloudFront invalidation' do
+        expect(Middleman::S3Sync::CloudFront).not_to receive(:invalidate)
+
+        Middleman::S3Sync.sync
+      end
+    end
+  end
+
+  describe 'path tracking during resource operations' do
+    before do
+      # Reset invalidation paths before each path tracking test
+      Middleman::S3Sync.instance_variable_set(:@invalidation_paths, [])
+    end
+
+    it 'adds paths to invalidation list when resources are processed' do
+      # Test the add_invalidation_path method directly
+      Middleman::S3Sync.add_invalidation_path('test/file.html')
+      Middleman::S3Sync.add_invalidation_path('images/photo.jpg')
+      
+      expect(Middleman::S3Sync.invalidation_paths).to include('/test/file.html')
+      expect(Middleman::S3Sync.invalidation_paths).to include('/images/photo.jpg')
+    end
+
+    it 'normalizes paths when adding to invalidation list' do
+      Middleman::S3Sync.add_invalidation_path('no-leading-slash.html')
+      
+      expect(Middleman::S3Sync.invalidation_paths).to include('/no-leading-slash.html')
+    end
+
+    it 'does not add duplicate paths' do
+      Middleman::S3Sync.add_invalidation_path('/same/path.html')
+      Middleman::S3Sync.add_invalidation_path('/same/path.html')
+      
+      expect(Middleman::S3Sync.invalidation_paths.count('/same/path.html')).to eq(1)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: middleman-s3_sync
 version: !ruby/object:Gem::Version
-  version: 4.5.0
+  version: 4.6.0
 platform: ruby
 authors:
 - Frederic Jean
 - Will Koehler
 bindir: bin
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: middleman-core
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-cloudfront
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: map
   requirement: !ruby/object:Gem::Requirement
@@ -312,6 +326,7 @@ files:
 - lib/middleman/redirect.rb
 - lib/middleman/s3_sync.rb
 - lib/middleman/s3_sync/caching_policy.rb
+- lib/middleman/s3_sync/cloudfront.rb
 - lib/middleman/s3_sync/options.rb
 - lib/middleman/s3_sync/resource.rb
 - lib/middleman/s3_sync/status.rb
@@ -319,7 +334,9 @@ files:
 - lib/middleman_extension.rb
 - middleman-s3_sync.gemspec
 - spec/caching_policy_spec.rb
+- spec/cloudfront_spec.rb
 - spec/resource_spec.rb
+- spec/s3_sync_integration_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/fredjean/middleman-s3_sync
 licenses:
@@ -344,5 +361,7 @@ specification_version: 4
 summary: Tries really, really hard not to push files to S3.
 test_files:
 - spec/caching_policy_spec.rb
+- spec/cloudfront_spec.rb
 - spec/resource_spec.rb
+- spec/s3_sync_integration_spec.rb
 - spec/spec_helper.rb