📢 Announcement: aws-activejob-sqs 1.0.0 release and upgrade information 📢

[alextwoods]

Describe the issue

We're happy to announce the 1.0 release of aws-activejob-sqs with the following new features:

• Support polling on multiple queues. (Separate settings for each queue #4)
• Support running without Rails. (SqsActiveJob doesn't need Rails #5)
• Support per queue configuration. (Separate settings for each queue #4)
• Support loading global and queue specific configuration from ENV. (AWS_ACTIVE_JOB_QUEUE_URL not used when queue is configured #3)
• Improved and customizable error handling: Replace retry_standard_errors with poller_error_handler. (Aws::Rails::SqsActiveJob#execute captures StandardError which is too wide #6)

See the updated README and API documentation for information on using the new features!

Breaking changes and migration guide

The 1.0 release contains a few breaking changes that may require code or configuration changes. If you are not ready to update, you can pin your version with `gem 'aws-activejob-sqs', '~> 0'. If you run into issues while upgrading, please feel free to open an issue or respond to this one.

Namespace change: Aws::Rails::SqsActiveJob → Aws::ActiveJob::SQS

The namespace has been changed to reflect the gem name and follow Ruby standards. For most users this should just require changing in code configuration from Aws::Rails::SqsActiveJob.configure to Aws::ActiveJob::SQS.configure.

Poller Executable name change aws_sqs_active_job → aws_active_job_sqs

To better reflect the gem name and the new namespace, we've updated the poller executable's name to aws_active_job_sqs. Wherever you were starting your poller(s), you'll need to update to use the new name. Version 0.1.2 has both the old and new executable names to make migration easier.

Default config file name: aws_sqs_active_job.yml → aws_active_job_sqs.yml

To better reflect the gem name and new namespace, we've updated the default config file name
when using rails to config/aws_active_job_sqs.yml or config/aws_active_job_sqs/<Rails.env>.yml. You can either rename existing aws_sqs_active_job.yml files or use the AWS_ACTIVE_JOB_SQS_CONFIG_FILE environment variable to specify a different location.

Queue url is now a subkey

With the introduction of queue specific configuration in 1.0, queue url must now be configured as a sub key on the queue:

# config/aws_active_job_sqs.yml
queues:
  default: 
    url: 'https://my-queue-url.amazon.aws'

Or in code:

Aws::ActiveJob::SQS.configure do |config|
  config.queues[:default][:url] = 'https://my-queue-url.amazon.aws'
end

Changes in poller error handling: retry_standard_errors replaced with poller_error_handler

With the 1.0 release, error handling in the poller has been updated to be more flexible and to allow user configured error handlers. The retry_standard_errors configuration (and cli option) have been replaced by the poller_error_handler which allows user a user defined error handler to be called for any StandardErrors produced by job execution. The default behavior has changed from retrying StandardErrors raised during job execution to leaving the message on the queue and initiating shutdown of the poller. To change this behavior, configure a poller_error_handler. For more information about error handling, see: READEME#Retry Behavior and Handling Errors

Other module/class renames

• The Lambda handler has been moved to its own module and the entry point is now Aws::ActiveJob::SQS::LambdaHandler.job_handler.
• The deduplicate_without method used to configure deduplication keys on jobs has moved to its own module. You will now need to include Aws::ActiveJob::SQS::Deduplication in jobs that use dedupliate_without.

Links

https://github.com/aws/aws-activejob-sqs-ruby/blob/main/README.md

[ckhsponge]

Thanks! We have this working in our staging environment WITHOUT Rails.

Here's the steps we needed to do the upgrade.

1. Replace gem require 'aws-activejob-sqs'
2. Change config. "url:" is now required for queue urls. We didn't have it there before.

Aws::ActiveJob::SQS.configure do |config|
  config.queues = { default: { url: ENV['JOB_AWS_SQS_URL'] } }
end

3. Change Lambda handler.

Aws::ActiveJob::SQS::LambdaHandler.job_handler(event: event, context: context)

[ohbarye]

Thank you for writing the migration guide. I have one piece of feedback regarding the poller executable name change.

For my team, it would have been helpful to have a more gradual approach to changing the command name. Specifically, I would have preferred if you:

1. First released a version that supports both old and new command names (aws_sqs_active_job and aws_active_job_sqs)
2. Then removed the old command (aws_sqs_active_job) in the major version release

The reason is that we cannot always make the gem update and command name changes atomic in our deployment process. Having both commands available during the transition period would have made the migration smoother and safer.

[alextwoods]

That's great feedback - thank you.
I can release a new minor version that adds the old binary back to make migration easier. It would still have the changes in arguments, but that still makes an easier/safer upgrade path I think.

[mullermp]

What about a patch version to version 0? But it sounds like you've already completed the migration @ohbarye? Sorry about the rough edge. If that's the case, maybe no changes necessary.

[ckhsponge]

This breaking change doesn't seem that rough to me. Couldn't anyone just temporarily copy the executable into their project and name it whatever they want? Maybe I'm missing something.

[ohbarye]

@alextwoods @mullermp

But it sounds like you've already completed the migration @ohbarye?

Ah, no, our migration has not yet been completed. We're still discussing how to update. I apologize for writing in a way that is difficult to understand.

I can release a new minor version that adds the old binary back to make migration easier.
What about a patch version to version 0?

Thank you for your suggestion! I would appreciate it if you could proceed in that way.

[ohbarye]

@ckhsponge

Couldn't anyone just temporarily copy the executable into their project and name it whatever they want? Maybe I'm missing something.

Do you mean by creating a binstub of both aws_sqs_active_job and aws_active_job_sqs, or other ways? I'd like to know a safer way for us to take it.

Anyway, I wonder if total cost is lower if upstream temporarily provides compatibility than if all gem users try this kind of workaround.

[ckhsponge]

I was imagining copying the old executable into your project and giving it the new name. Your updated project could have the new executable with the new name. Both versions of your project would then launch from the same name. Hopefully there's a way to deploy your code and the gems they need at the same time. Your project might be more complicated however.

[alextwoods]

I've released a new 0.x patch: 0.1.2 that has both the old and new executable names that should hopefully help make migrations easier.

[ohbarye]

I'm delighted with that. Thank you!