Behavior Traits

This wiki contains a mapping between Smithy Behavior traits and generated Ruby code.

idempotencyToken trait

Defines the input member of an operation that is used by the server to identify and discard replayed requests. If a member with this trait is not provided, a token is automatically generated in the param builder. This is done so that any middleware will have access to a client token if none was provided.

structure AllocateWidgetInput {
    @idempotencyToken
    clientToken: String,
}

The generated code is:

# params.rb
require 'securerandom'

module AllocateWidgetInput
  def self.build(params, context: '')
    type = Types::AllocateWidgetInput.new
    type.client_token = params[:client_token] || SecureRandom.uuid
    type
  end
end

idempotent trait

Indicates that the intended effect on the server of multiple identical requests with an operation is the same as the effect for a single such request. This trait does not influence code generation.

readonly trait

Indicates that an operation is effectively read-only. In Smithy, a GET operation is read only. This trait does not influence code generation.

retryable trait

Indicates that an error MAY be retried by the client. Hearth::HTTP::ApiError defines retryable? and throttling? methods that return false by default. Errors marked with this trait will override the retryable? method to return true. This trait also supports a throttling property, and if it is set to true, the throttling? method will similarly be overridden.

@error("server")
@retryable
@httpError(503)
structure ServiceUnavailableError {}

@error("client")
@retryable(throttling: true)
@httpError(429)
structure ThrottlingError {}

The generated code is:

# errors.rb

class ServiceUnavailableError < ApiServerError
  ...

  def retryable?
    true
  end
end
    
class ThrottlingError < ApiClientError
  ...

  def retryable?
    true
  end
      
  def throttling?
    true
  end
end

If the service returns an error, the retry middleware will call these two methods to determine if the error can be retried and determine whether or not it needs to apply backoff.

begin
  @app.call(input, context)
rescue ApiError => error
  # do something with error.retryable?
  # do something with error.throttling?
end

paginated trait

The paginated trait indicates that an operation intentionally limits the number of results returned in a single response and that multiple invocations might be necessary to retrieve all results. Each paginated operation will have a pagination class that automatically iterates response pages by using the response’s output token as the next input token. See Paginators.

httpChecksumRequired trait

Indicates that an operation requires a checksum in its HTTP request. By default, the checksum used for a service is a MD5 checksum passed in the Content-MD5 header. This trait may be expanded in the future to support other algorithms and headers. The checksum is calculated and applied to the header in the request builders. The Hearth::Checksums module is used for calculating checksums.

@httpChecksumRequired
operation PutSomething {
    input: PutSomethingInput,
    output: PutSomethingOutput
}

The generated code is:

# client.rb in some operation
stack.use(Hearth::HTTP::Middleware::ContentMD5)

httpChecksum trait

TODO