One More Time

gem 'one_more_time'

def start_idempotent_request!
  # We begin by calling OneMoreTime.start_request!, which creates (or finds an existing) 
  # request using the given idempotency_key, and returns a record representing it.
  
  # When first created, the record is in a "locked" state so no other server process 
  # will be able to work on the same request. If we found an existing locked record, 
  # a RequestInProgressError will be raised.

  idempotent_request = OneMoreTime.start_request!(
    # This value is supplied by the client, who decides the scope of idempotency
    idempotency_key: request.headers["Idempotency-Key"],
    # If supplied, these values will be used to verify that the incoming request data match
    # the stored data (when an existing record was found). If there is a mismatch, a 
    # RequestMismatchError will be raised.
    request_path: "#{request.method} #{request.path}",
    request_body: request.raw_post,
    )

  # Set a callback to specify how to convert a successful result into response data stored
  # on the record
  idempotent_request.success_attributes do |result|
    {
      response_code: 200,
      response_body: result.to_json,
    }
  end

  # Similarly, convert an exception that has been raised into a stored response
  idempotent_request.failure_attributes do |exception|
    {
      response_code: 500,
      response_body: { error: exception.message }.to_json,
    }
  end

  idempotent_request
end

idempotent_request = start_idempotent_request!

# Wrap your code in a block sent to the execute method. 
# This block will be skipped entirely if any of the following apply:
# - Another process is currently running it
# - It has previously run and completed
# - It has previously run and it is not 100% certain how far it got
idempotent_request.execute do

  # While inside the execute block, raising an error will by default unlock the request, so 
  # the block can be retried by a later process.
  raise RetryableError unless ExternalService.service_is_online?

  # But now we need to make an external, non-idempotent service call
  begin
    widget = ExternalService.purchase_widget(params[:widget_name])
  rescue ExternalService::ConnectionLostError => exception
  #   We sent data to the external service but don't know whether it was fully processed.
  #   If a widget is something we can't afford to accidentally create twice, we need to
  #   give up and store an error response on this request so it can't be retried.
  #   This will invoke the failure_attributes callback and raise out of the execute block.
    idempotent_request.failure!(exception: exception)
  end

  # Call the success method with a block. This block is automatically run in a transaction
  # and should contain any code needed to persist the results of your external service call.
  # Any failure within this block will internally call failure! on the request - we DID
  # purchase a widget already, so we can't allow a retry.
  idempotent_request.success do
    # The return value of this block is what gets passed to the success_attributes callback
    Widget.create!(widget_id: widget.id)
  end
end

# Render the stored response, which we are guaranteed to have if we make it here
render json: idempotent_request.response_body, status: idempotent_request.response_code