Quickstart¶
Getting started with Hedwig is easy, but requires a few steps.
Installation¶
Install the latest hedwig release via pip:
$ pip install authedwig
You may also install a specific version:
$ pip install authedwig==1.0.0
The latest development version can always be found on Github.
Configuration¶
Before you can use Hedwig, you need to set up a few settings. For Django projects,
simple use Django settings to configure Hedwig, for non-Django projects, you
must declare an environment variable called SETTINGS_MODULE
that points to a module
where settings may be found.
Required settings are:
AWS_ACCESS_KEY = <YOUR AWS KEY>
AWS_ACCOUNT_ID = <YOUR AWS ACCOUNT ID>
AWS_REGION = <YOUR AWS REGION>
AWS_SECRET_KEY = <YOUR AWS SECRET KEY>
HEDWIG_QUEUE = <YOUR APP HEDWIG QUEUE>
HEDWIG_CALLBACKS = <YOUR CALLBACKS>
HEDWIG_ROUTING = <YOUR INFRA ROUTES>
HEDWIG_SCHEMA_FILE = <PATH TO YOUR SCHEMA FILE>
Provisioning¶
Hedwig works on SQS and SNS as backing queues. Before you can publish/consume messages, you need to provision the required infra. This may be done manually, or, preferably, using Terraform. Hedwig provides tools to make infra configuration easier: see Terraform and Hedwig Terraform Generator for further details.
Fan Out¶
Hedwig utilizes SNS for fan-out configuration. A publisher publishes messages on a topic. This message may be received by zero or more consumers. The publisher needn’t be aware of the consuming application at all. There are a variety of messages that may be published as such, but they generally fall into 2 buckets:
- Asynchronous API Requests: Hedwig may be used to call APIs asynchronously. The contract is enforced by your infra-structure by connecting SNS topics to SQS queues, and payload is validated using the schema you define. Response is a delivered using a separate message if required.
- Notifications: The most common use case is to notify other services/apps that may be interested in events. For
example, your User Management app can publish a
user.created
message notification to all your apps. As publishers and consumers are loosely coupled, this separation of concerns is very effective in ensuring a stable eco-system.
Using Hedwig¶
To use hedwig, simply add a message handler like so:
def send_email(message: hedwig.models.Message) -> None:
# send email
And then send a message:
message = hedwig.models.Message.new(
hedwig.models.MessageType.send_email,
StrictVersion('1.0'),
{
'to': 'example@email.com',
'subject': 'Hello!',
},
)
message.publish()
Messages are held in SQS queue until they’re successfully executed, or until they fail a configurable number of times. Failed tasks are moved to a Dead Letter Queue, where they’re held for 14 days, and may be examined for further debugging.