cloud-adapter-aws

@evolve-framework/cloud-adapter-aws · v1.0.0

Runs Evolve services on AWS. Services send each other events, store files and read configuration through interfaces defined in @evolve-framework/core; this package implements those interfaces with SQS, EventBridge, S3 and Systems Manager Parameter Store. It also has the Lambda entry points: one turns a Fastify app into an HTTP Lambda, and one wraps a handler with tracing and error reporting. The same service code then runs on AWS by choosing this package at the entry point, with no AWS SDK calls in the business logic.

When to use

• A service publishes internal events to an SQS queue or an EventBridge bus.
• A Lambda consumes internal events from an SQS queue, whether they were sent to it directly or routed there by EventBridge.
• A service's HTTP app runs as a Lambda behind API Gateway, a load balancer or a function URL.
• A service writes files to S3, or reads its configuration from Parameter Store.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-framework/cloud-adapter-aws @evolve-framework/core fastify

   Requirements3

   @evolve-framework/core	>= 1.0.0 < 2.0.0
   @types/node	>=22optional
   fastify	>= 5.12.1 < 6.0.0

For example:

import { createSQSHandler, lambdaHandlerFactory, SqsPublisher } from "@evolve-framework/cloud-adapter-aws";
import type { Message } from "@evolve-framework/core/messaging";

// Publishing: any service hands internal events to a queue.
export const publisher = new SqsPublisher(
  "https://sqs.eu-west-1.amazonaws.com/123456789012/internal-events",
);

// Consuming: a Lambda fed by that queue. In a service this is the composed
// module's `handleInternalEvent`, which dispatches each event by its type.
const handleInternalEvent = async (event: Message): Promise<void> => {
  console.log("received", event.type);
};

export const handler = lambdaHandlerFactory("internal-events", () =>
  createSQSHandler(handleInternalEvent),
);

Adapters

AwsS3StorageClient

Stores files in S3, as core's StorageClient, and signs URLs to one object with the client's own credentials.

import { AwsS3StorageClient } from "@evolve-framework/cloud-adapter-aws";

new AwsS3StorageClient(s3Client?: S3Client)

Method	Description
save( bucket: string, key: string, data: string, options?: SaveOptions, ): Promise<void>	Writes data as the object key in bucket, replacing what was stored there, with options.ContentType as its content type.
signUpload( bucket: string, key: string, options: SignedUploadOptions, ): Promise<string>	The Content-Type is part of the signature, so the PUT has to send it.
signRead( bucket: string, key: string, options: SignedUrlOptions, ): Promise<string>	A URL a client GETs the object from until it expires.
stat(bucket: string, key: string): Promise<StoredObject | undefined>	The object, or undefined when nothing was stored under the key.

EventBridgePublisher

Publishes internal events to one EventBridge bus, with the publish options' origin as the event's source and type as its detail type, so a rule can route on either.

import { EventBridgePublisher } from "@evolve-framework/cloud-adapter-aws";

new EventBridgePublisher(eventBusArn: string)

Method	Description
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>	Hand a message to the provider.

SqsPublisher

Publishes internal events to one SQS queue.

import { SqsPublisher } from "@evolve-framework/cloud-adapter-aws";

new SqsPublisher(queueUrl: string)

Method	Description
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>	Hand a message to the provider.

Entry points

@evolve-framework/cloud-adapter-aws

Messaging: SqsPublisher, EventBridgePublisher, createSQSHandler, createEventBridgeSQSHandler and deserializeMessage.10 exports