Skip to content
EvolveEvolveEvolve

cloud-adapter-azure

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

Runs Evolve services on Azure. Services send each other events, store files and read configuration through interfaces defined in @evolve-framework/core; this package implements those interfaces with Service Bus, Event Grid, Blob Storage and App Configuration. It also has the handlers an Azure Function app needs to receive events, and the sign-in for Azure Managed Redis with Microsoft Entra ID. The same service code then runs on Azure by choosing this package at the entry point, with no Azure SDK calls in the business logic.

When to use

  • A service publishes internal events to a Service Bus queue or an Event Grid topic.
  • An Azure Function app receives internal events from a Service Bus queue or an Event Grid subscription.
  • A service writes files to Blob Storage, or reads its configuration from App Configuration, with Key Vault references resolved.
  • The cache is Azure Managed Redis, signed in with Entra ID rather than a key.

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-azure @evolve-framework/core
    Requirements2
    @evolve-framework/core>= 1.0.0 < 2.0.0
    @types/node>=22optional

For example:

import { app } from "@azure/functions";
import { createServiceBusHandler, ServiceBusPublisher } from "@evolve-framework/cloud-adapter-azure";
import type { Message } from "@evolve-framework/core/messaging";


// Publishing: any service hands internal events to a queue.
export const publisher = new ServiceBusPublisher(
  "https://shop.servicebus.windows.net/internal-events",
);


// Consuming: a function 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);
};


app.serviceBusQueue("internal-events", {
  handler: createServiceBusHandler(handleInternalEvent),
  connection: "INTERNAL_EVENTS_SERVICE_BUS",
  queueName: "internal-events",
  cardinality: "one",
});

Adapters

AzureBlobServiceStorageClient

Stores files in Blob Storage, as core's StorageClient: a bucket is a container and a key is a blob name.

import { AzureBlobServiceStorageClient } from "@evolve-framework/cloud-adapter-azure";
new AzureBlobServiceStorageClient(serviceUrl: string, credential?: TokenCredential)
MethodDescription
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>A SAS cannot bind the Content-Type of a PUT, so the client sets the x-ms-blob-content-type header itself and stat reports what it sent.
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.

EventGridPublisher

Publishes internal events to one Event Grid topic as CloudEvents, with the publish options' type and origin as the event's type and source.

import { EventGridPublisher } from "@evolve-framework/cloud-adapter-azure";
new EventGridPublisher(target: string)
MethodDescription
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>Hand a message to the provider.

ServiceBusPublisher

Publishes messages to a queue in Azure Service Bus.

Handles the authentication and connection to the Service Bus namespace, and holds a long-lived sender that is reused across publish() calls. Call close() on shutdown to release the sender and client.

e.g:

import { ServiceBusPublisher } from "@evolve-framework/cloud-adapter-azure";
new ServiceBusPublisher(target: string)
MethodDescription
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>Hand a message to the provider.
close(): Promise<void>Close the sender, when one was opened, and then the client.

Entry points

@evolve-framework/cloud-adapter-azureMessaging: ServiceBusPublisher, EventGridPublisher, createServiceBusHandler and createEventGridHandler.8 exports