File Actions

A Files::FileAction reports the status of a file copy or move. Files::File.copy and Files::File.move return this object when the API accepts the operation.

Call wait_for_completion on the action when your next step requires the operation to finish. The method polls its File Migration immediately. By default, it waits 1 second before each later poll. It returns the completed Files::FileMigration. An action already marked completed without a migration ID returns nil.

Waiting for a Copy

action = Files::File.copy("reports/october.csv", {
  destination: "archive/october.csv"
})
migration = action.wait_for_completion(interval: 1, timeout: 60)

Progress and Errors

Pass a block to receive each observed migration. Raise an exception from the block to stop waiting. The exception propagates unchanged, and the operation continues on Files.com.

interval and timeout use seconds and must be finite numbers greater than zero. The default timeout: nil waits without a polling deadline. A timeout limits polling and the delay between requests. An in-flight request keeps its configured HTTP timeouts and retries, so it can finish after the polling deadline.

A failed or cancelled migration raises Files::FileActionError with the remote failure message when available. The same error class covers a polling timeout or status data that cannot confirm completion. Inspect error.action and error.migration for the original action and the last observed migration. An API request error keeps its normal SDK error class.

Monitoring a Move

action = Files::File.move("reports/october.csv", {
  destination: "archive/october.csv"
})
begin
  action.wait_for_completion(timeout: 60) do |migration|
    puts "#{migration.status}: #{migration.files_moved} files processed"
  end
rescue Files::FileActionError => error
  warn error.message
  warn error.migration&.failure_message
end