Sneakers Documentation

Sneakers provides Docker support for testing and running workers without local RabbitMQ/Redis setups.

• Build image: docker build . -t sneakers_sneakers
• Run non-integration tests: docker run --rm sneakers_sneakers:latest
• Run full integration tests: Execute scripts/local_integration (uses docker-compose).
• Run a sample worker: Execute script/local_worker (uses docker-compose).
• Production builds: Use Dockerfile.slim for a compact image; use the standard Dockerfile for faster development iteration.

You can install Sneakers by adding it to your Gemfile or by installing the gem directly via the command line.

# In your Gemfile
gem 'sneakers'

$ bundle
# OR
$ gem install sneakers

To create a worker, define a class that includes Sneakers::Worker and use the from_queue method to specify the RabbitMQ queue name. Implement the work(msg) method to process incoming messages. Within work, you must call ack! to acknowledge the message once processing is complete.

require 'sneakers'
require 'redis'
require 'json'

$redis = Redis.new

class Processor
  include Sneakers::Worker
  from_queue :logs

  def work(msg)
    err = JSON.parse(msg)
    if err["type"] == "error"
      $redis.incr "processor:#{err["error"]}"
    end

    ack!
  end
end

The Maxretry handler implements a retry mechanism using RabbitMQ dead-letter policies. When a message fails (via reject or error), it is routed to a retry exchange/queue. If the maximum number of retries is reached, the message is published to an error exchange with metadata about the failure (error class, message, backtrace, and attempt count).

To use this handler, you must configure your queue with the correct x-dead-letter-exchange argument so that rejected messages are routed to the retry infrastructure. Use Sneakers::Handlers::Maxretry.configure_queue to generate the necessary options for your queue configuration.

To see real-time metrics (such as work start, completion, and timing) in your logs, use the Sneakers::Metrics::LoggingMetrics provider via Sneakers.configure.

require 'sneakers'
require 'sneakers/metrics/logging_metrics'

Sneakers.configure(metrics: Sneakers::Metrics::LoggingMetrics.new)

Sneakers uses a Configuration object to manage settings for both the runner and the individual workers. You can configure these settings by merging a hash into the existing configuration.

Important Security Note: By default, Sneakers includes Sneakers::ErrorReporter::DefaultLogger, which logs errors to STDOUT. In production environments, you should remove this or replace it to avoid logging sensitive data.

If you provide a connection object (a Bunny object) in your configuration hash, Sneakers will ignore the :vhost, :amqp, and :heartbeat parameters to ensure the provided connection is the single source of truth.

When initializing Sneakers::Publisher, the options hash is merged with Sneakers::CONFIG. Key configuration options include:

• :connection: An existing Bunny connection object. If provided, Sneakers uses this instead of creating a new one.
• :amqp: AMQP connection settings (passed to Bunny.new).
• :vhost: The RabbitMQ virtual host.
• :heartbeat: Heartbeat interval.
• :properties: A hash of properties for the connection.
• :exchange: The name of the exchange to use.
• :exchange_options: Options passed to the exchange creation method (e.g., type, durable).

Ensure your Ruby version matches your Sneakers version requirements:

Use the sneakers CLI command to spawn a worker. Use the --require flag to specify a file (e.g., boot.rb) that sets up your environment, dependencies, and worker definitions.

$ sneakers work Processor --require boot.rb

You can define how specific content types are transformed when being sent (serialized) or received (deserialized) by using Sneakers::ContentType.register. This is useful for handling custom formats like JSON, MessagePack, or Protobuf within your background workers.

To register a type, you must provide:

• content_type: A unique identifier for the type.
• serializer: A Proc that accepts exactly one argument (the payload) and returns the serialized version.
• deserializer: A Proc that accepts exactly one argument (the payload) and returns the deserialized version.

If no content type is specified during serialization or deserialization, Sneakers will default to a 'passthrough' behavior, returning the payload unchanged.