aws-sdk-transfer 1.49.0 → 1.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4dcec53c534ecacf09fc94f69e2df74a13999f50aa80f275128e8d18f76b443
-  data.tar.gz: 5fbcbbe7e310309089ebdb58bef2285c085fca6aa19858cbf718df923504fb96
+  metadata.gz: 0fa6cb0551a45bbf8181b24aa16b6906bc2d484a634c99d9235ed568a41e3052
+  data.tar.gz: d8fae405f7cf074190e0d51c130e07d256b28cb68c92756f298b997ee7122f1c
 SHA512:
-  metadata.gz: 18a7b532fd07a10853847090bb0c6e940a332ec059bc032ede56fd28fea63013862038c874b1537b905d9be0b1c2aa9f0424d5a3e86ef6309d1784a3c0b56d3a
-  data.tar.gz: 2f8c878b83effecd7ed1d52698c1b13229477604639a593d3f42a4833febd225bc69d2a74d04a3a55360fb7d8c95e6f0708feeb3908e78967f9e891c802b28c3
+  metadata.gz: 3a512a5e6444bf200dc5c516c33794af3458fb60441fa380306dc2ff00710783fe586afbb2ec6f510c98f99c1c5e51b3d2481469fade079e99d1be417ff43c05
+  data.tar.gz: d2583c98b553bd682528e547431bf8e3c8c0899ec70b7f23532363a32b90255e6e39ae2fb0c41788c5f4e07087ee274582fa76510dc2adedf9d19f7060c52233

data/CHANGELOG.md

@@ -1,6 +1,21 @@
 Unreleased Changes
 ------------------
 
+1.52.0 (2022-03-23)
+------------------
+
+* Feature - Documentation updates for AWS Transfer Family to describe how to remove an associated workflow from a server.
+
+1.51.0 (2022-03-10)
+------------------
+
+* Feature - Adding more descriptive error types for managed workflows
+
+1.50.0 (2022-03-04)
+------------------
+
+* Feature - Add waiters for server online and offline.
+
 1.49.0 (2022-02-24)
 ------------------
 

data/VERSION

@@ -1 +1 @@
-1.49.0
+1.52.0

data/lib/aws-sdk-transfer/client.rb

@@ -657,8 +657,23 @@ module Aws::Transfer
     #   set, user activity can be viewed in your CloudWatch logs.
     #
     # @option params [String] :post_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed after the user authenticates.
+    #
+    #   <note markdown="1"> The SFTP protocol does not support post-authentication display
+    #   banners.
+    #
+    #    </note>
     #
     # @option params [String] :pre_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed before the user authenticates. For example, the
+    #   following banner displays details about using the system.
+    #
+    #   `This system is for the use of authorized users only. Individuals
+    #   using this computer system without authority, or in excess of their
+    #   authority, are subject to having all of their activities on this
+    #   system monitored and recorded by system personnel.`
     #
     # @option params [Array<String>] :protocols
     #   Specifies the file transfer protocol or protocols over which your file
@@ -1363,12 +1378,12 @@ module Aws::Transfer
     #   resp.execution.results.steps #=> Array
     #   resp.execution.results.steps[0].step_type #=> String, one of "COPY", "CUSTOM", "TAG", "DELETE"
     #   resp.execution.results.steps[0].outputs #=> String
-    #   resp.execution.results.steps[0].error.type #=> String, one of "PERMISSION_DENIED"
+    #   resp.execution.results.steps[0].error.type #=> String, one of "PERMISSION_DENIED", "CUSTOM_STEP_FAILED", "THROTTLED", "ALREADY_EXISTS", "NOT_FOUND", "BAD_REQUEST", "TIMEOUT", "INTERNAL_SERVER_ERROR"
     #   resp.execution.results.steps[0].error.message #=> String
     #   resp.execution.results.on_exception_steps #=> Array
     #   resp.execution.results.on_exception_steps[0].step_type #=> String, one of "COPY", "CUSTOM", "TAG", "DELETE"
     #   resp.execution.results.on_exception_steps[0].outputs #=> String
-    #   resp.execution.results.on_exception_steps[0].error.type #=> String, one of "PERMISSION_DENIED"
+    #   resp.execution.results.on_exception_steps[0].error.type #=> String, one of "PERMISSION_DENIED", "CUSTOM_STEP_FAILED", "THROTTLED", "ALREADY_EXISTS", "NOT_FOUND", "BAD_REQUEST", "TIMEOUT", "INTERNAL_SERVER_ERROR"
     #   resp.execution.results.on_exception_steps[0].error.message #=> String
     #
     # @see http://docs.aws.amazon.com/goto/WebAPI/transfer-2018-11-05/DescribeExecution AWS API Documentation
@@ -1483,6 +1498,12 @@ module Aws::Transfer
     #   resp.server.workflow_details.on_upload[0].workflow_id #=> String
     #   resp.server.workflow_details.on_upload[0].execution_role #=> String
     #
+    #
+    # The following waiters are defined for this operation (see {Client#wait_until} for detailed usage):
+    #
+    #   * server_offline
+    #   * server_online
+    #
     # @see http://docs.aws.amazon.com/goto/WebAPI/transfer-2018-11-05/DescribeServer AWS API Documentation
     #
     # @overload describe_server(params = {})
@@ -2566,8 +2587,23 @@ module Aws::Transfer
     #   set, user activity can be viewed in your CloudWatch logs.
     #
     # @option params [String] :post_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed after the user authenticates.
+    #
+    #   <note markdown="1"> The SFTP protocol does not support post-authentication display
+    #   banners.
+    #
+    #    </note>
     #
     # @option params [String] :pre_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed before the user authenticates. For example, the
+    #   following banner displays details about using the system.
+    #
+    #   `This system is for the use of authorized users only. Individuals
+    #   using this computer system without authority, or in excess of their
+    #   authority, are subject to having all of their activities on this
+    #   system monitored and recorded by system personnel.`
     #
     # @option params [Array<String>] :protocols
     #   Specifies the file transfer protocol or protocols over which your file
@@ -2611,6 +2647,12 @@ module Aws::Transfer
     #   Specifies the workflow ID for the workflow to assign and the execution
     #   role used for executing the workflow.
     #
+    #   To remove an associated workflow from a server, you can provide an
+    #   empty `OnUpload` object, as in the following example.
+    #
+    #   `aws transfer update-server --server-id s-01234567890abcdef
+    #   --workflow-details '\{"OnUpload":[]\}'`
+    #
     # @return [Types::UpdateServerResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods:
     #
     #   * {Types::UpdateServerResponse#server_id #server_id} => String
@@ -2824,14 +2866,129 @@ module Aws::Transfer
         params: params,
         config: config)
       context[:gem_name] = 'aws-sdk-transfer'
-      context[:gem_version] = '1.49.0'
+      context[:gem_version] = '1.52.0'
       Seahorse::Client::Request.new(handlers, context)
     end
 
+    # Polls an API operation until a resource enters a desired state.
+    #
+    # ## Basic Usage
+    #
+    # A waiter will call an API operation until:
+    #
+    # * It is successful
+    # * It enters a terminal state
+    # * It makes the maximum number of attempts
+    #
+    # In between attempts, the waiter will sleep.
+    #
+    #     # polls in a loop, sleeping between attempts
+    #     client.wait_until(waiter_name, params)
+    #
+    # ## Configuration
+    #
+    # You can configure the maximum number of polling attempts, and the
+    # delay (in seconds) between each polling attempt. You can pass
+    # configuration as the final arguments hash.
+    #
+    #     # poll for ~25 seconds
+    #     client.wait_until(waiter_name, params, {
+    #       max_attempts: 5,
+    #       delay: 5,
+    #     })
+    #
+    # ## Callbacks
+    #
+    # You can be notified before each polling attempt and before each
+    # delay. If you throw `:success` or `:failure` from these callbacks,
+    # it will terminate the waiter.
+    #
+    #     started_at = Time.now
+    #     client.wait_until(waiter_name, params, {
+    #
+    #       # disable max attempts
+    #       max_attempts: nil,
+    #
+    #       # poll for 1 hour, instead of a number of attempts
+    #       before_wait: -> (attempts, response) do
+    #         throw :failure if Time.now - started_at > 3600
+    #       end
+    #     })
+    #
+    # ## Handling Errors
+    #
+    # When a waiter is unsuccessful, it will raise an error.
+    # All of the failure errors extend from
+    # {Aws::Waiters::Errors::WaiterFailed}.
+    #
+    #     begin
+    #       client.wait_until(...)
+    #     rescue Aws::Waiters::Errors::WaiterFailed
+    #       # resource did not enter the desired state in time
+    #     end
+    #
+    # ## Valid Waiters
+    #
+    # The following table lists the valid waiter names, the operations they call,
+    # and the default `:delay` and `:max_attempts` values.
+    #
+    # | waiter_name    | params                   | :delay   | :max_attempts |
+    # | -------------- | ------------------------ | -------- | ------------- |
+    # | server_offline | {Client#describe_server} | 30       | 120           |
+    # | server_online  | {Client#describe_server} | 30       | 120           |
+    #
+    # @raise [Errors::FailureStateError] Raised when the waiter terminates
+    #   because the waiter has entered a state that it will not transition
+    #   out of, preventing success.
+    #
+    # @raise [Errors::TooManyAttemptsError] Raised when the configured
+    #   maximum number of attempts have been made, and the waiter is not
+    #   yet successful.
+    #
+    # @raise [Errors::UnexpectedError] Raised when an error is encounted
+    #   while polling for a resource that is not expected.
+    #
+    # @raise [Errors::NoSuchWaiterError] Raised when you request to wait
+    #   for an unknown state.
+    #
+    # @return [Boolean] Returns `true` if the waiter was successful.
+    # @param [Symbol] waiter_name
+    # @param [Hash] params ({})
+    # @param [Hash] options ({})
+    # @option options [Integer] :max_attempts
+    # @option options [Integer] :delay
+    # @option options [Proc] :before_attempt
+    # @option options [Proc] :before_wait
+    def wait_until(waiter_name, params = {}, options = {})
+      w = waiter(waiter_name, options)
+      yield(w.waiter) if block_given? # deprecated
+      w.wait(params)
+    end
+
     # @api private
     # @deprecated
     def waiter_names
-      []
+      waiters.keys
+    end
+
+    private
+
+    # @param [Symbol] waiter_name
+    # @param [Hash] options ({})
+    def waiter(waiter_name, options = {})
+      waiter_class = waiters[waiter_name]
+      if waiter_class
+        waiter_class.new(options.merge(client: self))
+      else
+        raise Aws::Waiters::Errors::NoSuchWaiterError.new(waiter_name, waiters.keys)
+      end
+    end
+
+    def waiters
+      {
+        server_offline: Waiters::ServerOffline,
+        server_online: Waiters::ServerOnline
+      }
     end
 
     class << self

data/lib/aws-sdk-transfer/types.rb

@@ -465,9 +465,24 @@ module Aws::Transfer
     #   @return [String]
     #
     # @!attribute [rw] post_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed after the user authenticates.
+    #
+    #   <note markdown="1"> The SFTP protocol does not support post-authentication display
+    #   banners.
+    #
+    #    </note>
     #   @return [String]
     #
     # @!attribute [rw] pre_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed before the user authenticates. For example, the
+    #   following banner displays details about using the system.
+    #
+    #   `This system is for the use of authorized users only. Individuals
+    #   using this computer system without authority, or in excess of their
+    #   authority, are subject to having all of their activities on this
+    #   system monitored and recorded by system personnel.`
     #   @return [String]
     #
     # @!attribute [rw] protocols
@@ -1669,9 +1684,24 @@ module Aws::Transfer
     #   @return [String]
     #
     # @!attribute [rw] post_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed after the user authenticates.
+    #
+    #   <note markdown="1"> The SFTP protocol does not support post-authentication display
+    #   banners.
+    #
+    #    </note>
     #   @return [String]
     #
     # @!attribute [rw] pre_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed before the user authenticates. For example, the
+    #   following banner displays details about using the system.
+    #
+    #   `This system is for the use of authorized users only. Individuals
+    #   using this computer system without authority, or in excess of their
+    #   authority, are subject to having all of their activities on this
+    #   system monitored and recorded by system personnel.`
     #   @return [String]
     #
     # @!attribute [rw] protocols
@@ -2027,10 +2057,38 @@ module Aws::Transfer
     # the execution of the workflow.
     #
     # @!attribute [rw] type
-    #   Specifies the error type: currently, the only valid value is
-    #   `PERMISSION_DENIED`, which occurs if your policy does not contain
-    #   the correct permissions to complete one or more of the steps in the
-    #   workflow.
+    #   Specifies the error type.
+    #
+    #   * `ALREADY_EXISTS`\: occurs for a copy step, if the overwrite option
+    #     is not selected and a file with the same name already exists in
+    #     the target location.
+    #
+    #   * `BAD_REQUEST`\: a general bad request: for example, a step that
+    #     attempts to tag an EFS file returns `BAD_REQUEST`, as only S3
+    #     files can be tagged.
+    #
+    #   * `CUSTOM_STEP_FAILED`\: occurs when the custom step provided a
+    #     callback that indicates failure.
+    #
+    #   * `INTERNAL_SERVER_ERROR`\: a catch-all error that can occur for a
+    #     variety of reasons.
+    #
+    #   * `NOT_FOUND`\: occurs when a requested entity, for example a source
+    #     file for a copy step, does not exist.
+    #
+    #   * `PERMISSION_DENIED`\: occurs if your policy does not contain the
+    #     correct permissions to complete one or more of the steps in the
+    #     workflow.
+    #
+    #   * `TIMEOUT`\: occurs when the execution times out.
+    #
+    #     <note markdown="1"> You can set the `TimeoutSeconds` for a custom step, anywhere from
+    #     1 second to 1800 seconds (30 minutes).
+    #
+    #      </note>
+    #
+    #   * `THROTTLED`\: occurs if you exceed the new execution refill rate
+    #     of one workflow per second.
     #   @return [String]
     #
     # @!attribute [rw] message
@@ -4031,9 +4089,24 @@ module Aws::Transfer
     #   @return [String]
     #
     # @!attribute [rw] post_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed after the user authenticates.
+    #
+    #   <note markdown="1"> The SFTP protocol does not support post-authentication display
+    #   banners.
+    #
+    #    </note>
     #   @return [String]
     #
     # @!attribute [rw] pre_authentication_login_banner
+    #   Specify a string to display when users connect to a server. This
+    #   string is displayed before the user authenticates. For example, the
+    #   following banner displays details about using the system.
+    #
+    #   `This system is for the use of authorized users only. Individuals
+    #   using this computer system without authority, or in excess of their
+    #   authority, are subject to having all of their activities on this
+    #   system monitored and recorded by system personnel.`
     #   @return [String]
     #
     # @!attribute [rw] protocols
@@ -4080,6 +4153,12 @@ module Aws::Transfer
     # @!attribute [rw] workflow_details
     #   Specifies the workflow ID for the workflow to assign and the
     #   execution role used for executing the workflow.
+    #
+    #   To remove an associated workflow from a server, you can provide an
+    #   empty `OnUpload` object, as in the following example.
+    #
+    #   `aws transfer update-server --server-id s-01234567890abcdef
+    #   --workflow-details '\{"OnUpload":[]\}'`
     #   @return [Types::WorkflowDetails]
     #
     # @see http://docs.aws.amazon.com/goto/WebAPI/transfer-2018-11-05/UpdateServerRequest AWS API Documentation
@@ -4357,6 +4436,12 @@ module Aws::Transfer
     # @!attribute [rw] on_upload
     #   A trigger that starts a workflow: the workflow begins to execute
     #   after a file is uploaded.
+    #
+    #   To remove an associated workflow from a server, you can provide an
+    #   empty `OnUpload` object, as in the following example.
+    #
+    #   `aws transfer update-server --server-id s-01234567890abcdef
+    #   --workflow-details '\{"OnUpload":[]\}'`
     #   @return [Array<Types::WorkflowDetail>]
     #
     # @see http://docs.aws.amazon.com/goto/WebAPI/transfer-2018-11-05/WorkflowDetails AWS API Documentation

data/lib/aws-sdk-transfer/waiters.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# WARNING ABOUT GENERATED CODE
+#
+# This file is generated. See the contributing guide for more information:
+# https://github.com/aws/aws-sdk-ruby/blob/version-3/CONTRIBUTING.md
+#
+# WARNING ABOUT GENERATED CODE
+
+require 'aws-sdk-core/waiters'
+
+module Aws::Transfer
+  # Waiters are utility methods that poll for a particular state to occur
+  # on a client. Waiters can fail after a number of attempts at a polling
+  # interval defined for the service client.
+  #
+  # For a list of operations that can be waited for and the
+  # client methods called for each operation, see the table below or the
+  # {Client#wait_until} field documentation for the {Client}.
+  #
+  # # Invoking a Waiter
+  # To invoke a waiter, call #wait_until on a {Client}. The first parameter
+  # is the waiter name, which is specific to the service client and indicates
+  # which operation is being waited for. The second parameter is a hash of
+  # parameters that are passed to the client method called by the waiter,
+  # which varies according to the waiter name.
+  #
+  # # Wait Failures
+  # To catch errors in a waiter, use WaiterFailed,
+  # as shown in the following example.
+  #
+  #     rescue rescue Aws::Waiters::Errors::WaiterFailed => error
+  #       puts "failed waiting for instance running: #{error.message}
+  #     end
+  #
+  # # Configuring a Waiter
+  # Each waiter has a default polling interval and a maximum number of
+  # attempts it will make before returning control to your program.
+  # To set these values, use the `max_attempts` and `delay` parameters
+  # in your `#wait_until` call.
+  # The following example waits for up to 25 seconds, polling every five seconds.
+  #
+  #     client.wait_until(...) do |w|
+  #       w.max_attempts = 5
+  #       w.delay = 5
+  #     end
+  #
+  # To disable wait failures, set the value of either of these parameters
+  # to `nil`.
+  #
+  # # Extending a Waiter
+  # To modify the behavior of waiters, you can register callbacks that are
+  # triggered before each polling attempt and before waiting.
+  #
+  # The following example implements an exponential backoff in a waiter
+  # by doubling the amount of time to wait on every attempt.
+  #
+  #     client.wait_until(...) do |w|
+  #       w.interval = 0 # disable normal sleep
+  #       w.before_wait do |n, resp|
+  #         sleep(n ** 2)
+  #       end
+  #     end
+  #
+  # # Available Waiters
+  #
+  # The following table lists the valid waiter names, the operations they call,
+  # and the default `:delay` and `:max_attempts` values.
+  #
+  # | waiter_name    | params                   | :delay   | :max_attempts |
+  # | -------------- | ------------------------ | -------- | ------------- |
+  # | server_offline | {Client#describe_server} | 30       | 120           |
+  # | server_online  | {Client#describe_server} | 30       | 120           |
+  #
+  module Waiters
+
+    class ServerOffline
+
+      # @param [Hash] options
+      # @option options [required, Client] :client
+      # @option options [Integer] :max_attempts (120)
+      # @option options [Integer] :delay (30)
+      # @option options [Proc] :before_attempt
+      # @option options [Proc] :before_wait
+      def initialize(options)
+        @client = options.fetch(:client)
+        @waiter = Aws::Waiters::Waiter.new({
+          max_attempts: 120,
+          delay: 30,
+          poller: Aws::Waiters::Poller.new(
+            operation_name: :describe_server,
+            acceptors: [
+              {
+                "argument" => "server.state",
+                "expected" => "OFFLINE",
+                "matcher" => "path",
+                "state" => "success"
+              },
+              {
+                "argument" => "server.state",
+                "expected" => "STOP_FAILED",
+                "matcher" => "path",
+                "state" => "failure"
+              }
+            ]
+          )
+        }.merge(options))
+      end
+
+      # @option (see Client#describe_server)
+      # @return (see Client#describe_server)
+      def wait(params = {})
+        @waiter.wait(client: @client, params: params)
+      end
+
+      # @api private
+      attr_reader :waiter
+
+    end
+
+    class ServerOnline
+
+      # @param [Hash] options
+      # @option options [required, Client] :client
+      # @option options [Integer] :max_attempts (120)
+      # @option options [Integer] :delay (30)
+      # @option options [Proc] :before_attempt
+      # @option options [Proc] :before_wait
+      def initialize(options)
+        @client = options.fetch(:client)
+        @waiter = Aws::Waiters::Waiter.new({
+          max_attempts: 120,
+          delay: 30,
+          poller: Aws::Waiters::Poller.new(
+            operation_name: :describe_server,
+            acceptors: [
+              {
+                "argument" => "server.state",
+                "expected" => "ONLINE",
+                "matcher" => "path",
+                "state" => "success"
+              },
+              {
+                "argument" => "server.state",
+                "expected" => "START_FAILED",
+                "matcher" => "path",
+                "state" => "failure"
+              }
+            ]
+          )
+        }.merge(options))
+      end
+
+      # @option (see Client#describe_server)
+      # @return (see Client#describe_server)
+      def wait(params = {})
+        @waiter.wait(client: @client, params: params)
+      end
+
+      # @api private
+      attr_reader :waiter
+
+    end
+  end
+end

data/lib/aws-sdk-transfer.rb

@@ -15,6 +15,7 @@ require_relative 'aws-sdk-transfer/types'
 require_relative 'aws-sdk-transfer/client_api'
 require_relative 'aws-sdk-transfer/client'
 require_relative 'aws-sdk-transfer/errors'
+require_relative 'aws-sdk-transfer/waiters'
 require_relative 'aws-sdk-transfer/resource'
 require_relative 'aws-sdk-transfer/customizations'
 
@@ -48,6 +49,6 @@ require_relative 'aws-sdk-transfer/customizations'
 # @!group service
 module Aws::Transfer
 
-  GEM_VERSION = '1.49.0'
+  GEM_VERSION = '1.52.0'
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-sdk-transfer
 version: !ruby/object:Gem::Version
-  version: 1.49.0
+  version: 1.52.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-24 00:00:00.000000000 Z
+date: 2022-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-core
@@ -62,6 +62,7 @@ files:
 - lib/aws-sdk-transfer/errors.rb
 - lib/aws-sdk-transfer/resource.rb
 - lib/aws-sdk-transfer/types.rb
+- lib/aws-sdk-transfer/waiters.rb
 homepage: https://github.com/aws/aws-sdk-ruby
 licenses:
 - Apache-2.0