Cursor Rules Template: AWS SQS SNS Boto3 Worker Pool

Overview

The Cursor rules configuration for AWS SQS and SNS with a Python boto3 worker pool defines how Cursor AI writes, tests, and maintains a robust background processing service. It covers the AWS stack with SQS queues, SNS topics, and a Python runtime, ensuring idempotent processing, proper error handling, and secure access via IAM roles.

When to Use These Cursor Rules

• When building a Python-based worker pool that reads messages from SQS and publishes events to SNS.
• When you need deterministic retries, dead-letter queues, and message deduplication patterns.
• When you want a ready-to-paste .cursorrules configuration to enforce stack-specific conventions.

Copyable .cursorrules Configuration

framework: python
stack: aws-sqs-sns-boto3
version: 1.0
context: Cursor AI orchestrates a Python boto3 worker pool that consumes SQS messages, processes them idempotently, and publishes results to SNS.
runtime: python3.11

# Framework Role & Context
role: Python SQS/SNS worker pool architect
context: Build a production-ready worker that polls SQS with long polling, processes messages, and emits events to SNS with validations and retries.

# Code Style and Style Guides
style:
  - pep8
  - black
  - mypy

# Architecture & Directory Rules
directories:
  - src/workers
  - src/publishers
  - tests
  - configs
  - scripts
  - .cursorrules

# Authentication & Security Rules
security:
  - Use IAM roles and instance profiles; avoid embedding credentials
  - Read configuration from environment variables or AWS Secrets Manager
  - Do not log sensitive values (queue URLs, access keys)
  - Use TLS for all AWS service interactions

# Database and ORM patterns
db:
  - type: none
  - storage: none
  - note: No relational DB is required for the worker; if state is needed, prefer DynamoDB with proper IAM constraints

# Testing & Linting Workflows
testing:
  - pytest
  - moto for AWS service mocks
  - black --check
  - mypy --strict
  - pre-commit hooks on commit

# Prohibited Actions and Anti-patterns for the AI
prohibited:
  - Hardcoding AWS credentials in code or config
  - Blocking loops in hot paths; avoid sleep in processing
  - Bypassing IAM least privilege
  - Skipping message validation before processing

# Cursor AI rules
messages:
  - Ensure idempotent processing using a stable dedup key per message
  - Respect SQS visibility timeout; extend when needed
  - Use exponential backoff on retries and log outcomes
  - Validate message body against the expected schema before processing
  - Do not publish incomplete or sensitive payloads to SNS

Recommended Project Structure

aws-sqs-sns-boto3-worker-pool/
├── workers/
│   ├── consumer.py
│   ├── processor.py
│   └── publisher.py
├── configs/
│   └── sqs_sns_config.yaml
├── tests/
│   ├── unit/
│   └── integration/
├── requirements.txt
├── .cursorrules
└── main.py

Core Engineering Principles

• Idempotent message processing and deterministic side effects.
• Explicit dead-letter handling and robust error reporting.
• Least privilege IAM roles with scoped permissions.
• Testability with isolated unit tests and AWS service mocks.
• Observability through structured logs and metrics.

Code Construction Rules

• Use a single boto3 client instance per worker process and share it safely across coroutines or threads.
• Configure queue_url and sns_topic_arn via environment variables or a config file, not hard-coded strings.
• Poll SQS with long polling up to 20 seconds; handle empty responses gracefully with backoff.
• Validate the message body before processing; reject malformed messages and route to a DLQ if needed.
• Publish only well-formed payloads to SNS; avoid leaking sensitive payload data in logs.

Security and Production Rules

• Attach a narrowly scoped IAM role to the worker with permissions for sqs:ReceiveMessage, DeleteMessage, ChangeMessageVisibility, GetQueueAttributes; sns:Publish only to intended topics.
• Use AWS Secrets Manager or SSM Parameter Store for configuration with rotation and access control.
• Enable TLS for all AWS API calls; enforce encryption at rest for any persisted state.
• Implement circuit breakers for AWS service failures and alert on deviation from SLA.

Testing Checklist

• Unit test message processing logic with deterministic inputs.
• Integration tests using moto to mock SQS and SNS behavior.
• End-to-end tests with a local AWS footprint or staged environment; verify DLQ flows.
• Lint and type-check with black and mypy; run pytest in CI.

Common Mistakes to Avoid

• Hardcoding credentials or secrets in source code or config files.
• Ignoring message validation leading to broken event schemas.
• Over-polling SQS; failing to respect visibility timeouts and DLQ wiring.
• Assuming immediate consistency or no retries without backoff.

FAQ

What is the purpose of this Cursor Rules Template for AWS SQS SNS with boto3?

The template provides a complete, paste-ready .cursorrules configuration and project layout for building a Python-based AWS worker pool. It covers consuming SQS messages, idempotent processing, and publishing to SNS with proper error handling, testing, and security considerations using Cursor AI rules.

Which stack does this template cover?

This template is tailored for Python with AWS SQS and SNS using boto3, designed to implement a worker pool that polls SQS, processes messages, and emits events to SNS in a safe, observable way.

How do I customize queue and topic values securely?

Expose queue URLs and topic ARNs through environment variables or a managed config service, not in code. Use IAM roles for access, and validate inputs before use. This keeps credentials out of the repository while enabling flexible deployments.

How can I test the worker locally or in CI?

Use moto to mock AWS services in unit tests and run pytest for test suites. Add integration tests for end-to-end flows and lint with black and mypy. Ensure tests cover DLQ routing and failure modes to prevent regressions.

What are recommended production security practices?

Limit permissions with a least-privilege IAM role, store secrets in Secrets Manager, enable TLS for APIs, and rotate credentials. Implement monitoring, alerting, and retries with backoff to maintain reliability under AWS service issues.

What common mistakes should I avoid?

Avoid embedding credentials, skipping message validation, over-polling or ignoring DLQs, and failing to handle idempotency or retries properly. Use explicit logging and observable metrics to detect issues early.