@edd-kernel/provider-aws-sns-sqs
v0.2.0-alpha.1
Published
AWS SNS + SQS EDD Kernel provider.
Maintainers
Readme
@edd-kernel/provider-aws-sns-sqs
AWS SNS + SQS provider for EDD Kernel: publishes to an SNS topic and consumes from the SQS queue subscribed to it.
Consuming is @edd-kernel/provider-aws-sqs's own code, inherited rather than copied, so
this package depends on it. What this package adds is the topic, the subscription and
the queue policy that lets the topic deliver.
Repository: brunnofoggia/edd-kernel-js
Install
npm install @edd-kernel/contracts @edd-kernel/provider-aws-sns-sqsFor provider-name based client creation, install @edd-kernel/factory in place of the
contract. It brings the contract and re-exports it:
npm install @edd-kernel/factory @edd-kernel/provider-aws-sns-sqsUsage
import { createSnsSqsClient } from '@edd-kernel/provider-aws-sns-sqs';
const client = createSnsSqsClient({ createIfNotExists: true }, { region: 'us-east-1' });
await client.consume({ queueName: 'orders' }, async (event, context) => {
console.log(event);
await context.ack();
});
await client.send({ topicName: 'orders' }, { type: 'OrderPlaced', payload: {} });Through @edd-kernel/factory:
import { EddProviderName, createEddClient } from '@edd-kernel/factory';
const client = await createEddClient({
providerName: EddProviderName.AwsSnsSqs,
createIfNotExists: true,
options: { region: 'us-east-1' },
});The package also exports SnsSqsEddClient for direct construction and inheritance. Its
static provider identity is aws-sns-sqs.
Addressing
| Sends to | Meaning |
| --------------- | ---------------------------------------------------------- |
| { topicName } | A logical name, joined with env, project and prefix. |
| { topicArn } | A topic ARN written in full, used as it is. |
| Consumes from | Meaning |
| --------------- | ------------------------------------------- |
| { queueName } | A logical name, as aws-sqs resolves it. |
| { queueUrl } | A queue URL written in full, used as it is. |
Any other address is refused by the compiler, and at runtime with
EddKernelConfigurationError.
SNS has no lookup by name, so a topicName reaches its ARN in one of two ways:
- with
createIfNotExists: true, throughCreateTopic, which returns the ARN of a topic that already exists; - with
createIfNotExists: false, composed fromregion,accountIdand the resolved name, so a publish-only role never needssns:CreateTopic. Without both options, pass atopicArn.
A topic that does not exist fails the publish as EddTargetNotFoundError.
Provisioning
With createIfNotExists: true, consume finishes the queue before it returns: it creates
the queue and the topic when missing, lets the topic send to the queue, and subscribes the
queue to the topic.
- Which topic. The queue's binding, and failing that the queue's own name. Both
sides of a binding are logical names, scoped with the same options as the queue. A
queue addressed by
queueUrlis never provisioned: a URL has no logical name to look a binding up by. One already subscribed is consumed as usual. - The queue policy. One statement is added allowing
sns.amazonaws.comto callsqs:SendMessagewhenaws:SourceArnis the topic's ARN. An equivalent statement already in the policy is left as it is, and statements for other principals survive. The policy is read again after the write, and a statement that does not show up is reported asEddProviderErrorinstead of leaving a subscription that delivers nothing. - Raw delivery. The subscription is created with
RawMessageDelivery: "true", so the queue receives the same bodyaws-sqswould have sent.
This path needs sns:CreateTopic, sns:Subscribe, sqs:CreateQueue,
sqs:GetQueueAttributes and sqs:SetQueueAttributes.
With createIfNotExists: false, nothing is provisioned. The subscription and the policy
are yours, and they must:
- let
sns.amazonaws.comcallsqs:SendMessageon the queue from the topic; - enable
RawMessageDeliveryon the subscription — without it, the handler receives the SNS notification envelope instead of the event.
createTopic(name) and createSubscription(queueName, { topicName }) do the same work
on their own, and answer the topic ARN and the subscription ARN. createQueue is
inherited from aws-sqs.
Provider Options
Everything aws-sqs takes configures the queue half unchanged — client, endpointUrl,
clientOptions, queueUrlByName, createQueueAttributes, createQueueTags,
waitTimeSeconds, pollIntervalMs, visibilityTimeout, nackVisibilityTimeout.
region, credentials and accountId are shared by both halves. The topic half adds:
snsClient: custom SNS-compatible client for tests or adapters.snsEndpointUrl: SNS endpoint override, reaching the SDK asendpoint.snsClientOptions: the rest of the AWSSNSClientconfiguration, merged overDEFAULT_SNS_CLIENT_CONFIG.bindings: each topic and the queues subscribed to it, as{ topic, queues }entries. A topic may appear in several entries; a queue bound to two topics is refused when the client is built.
DEFAULT_SNS_CLIENT_CONFIG sets a 5s connection timeout, a 10s request timeout,
throwOnRequestTimeout: true and three attempts. mergeSnsClientConfig merges
requestHandler field by field.
Lifecycle
Acknowledgement, polling and shutdown are aws-sqs's. The SNS and SQS clients the
provider created are destroyed on close; injected clients are never destroyed.
