Server

Introduction

The Dapr Server will allow you to receive communication from the Dapr Sidecar and get access to its server facing features such as: Subscribing to Events, Receiving Input Bindings, and much more.

Pre-requisites

Installing and importing Dapr’s JS SDK

  1. Install the SDK with npm:
  1. npm i @dapr/dapr --save
  1. Import the libraries:
  1. import { DaprServer, CommunicationProtocolEnum } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server
  8. // HTTP Example
  9. const server = new DaprServer({
  10.   serverHost,
  11.   serverPort,
  12.   communicationProtocol: CommunicationProtocolEnum.HTTP, // DaprClient to use same communication protocol as DaprServer, in case DaprClient protocol not mentioned explicitly
  13.   clientOptions: {
  14.     daprHost,
  15.     daprPort,
  16.   },
  17. });
  19. // GRPC Example
  20. const server = new DaprServer({
  21.   serverHost,
  22.   serverPort,
  23.   communicationProtocol: CommunicationProtocolEnum.GRPC,
  24.   clientOptions: {
  25.     daprHost,
  26.     daprPort,
  27.   },
  28. });

Running

To run the examples, you can use two different protocols to interact with the Dapr sidecar: HTTP (default) or gRPC.

Using HTTP (built-in express webserver)

  1. import { DaprServer } from "@dapr/dapr";
  3. const server = new DaprServer({
  4.   serverHost: appHost,
  5.   serverPort: appPort,
  6.   clientOptions: {
  7.     daprHost,
  8.     daprPort,
  9.   },
  10. });
  11. // initialize subscribtions, ... before server start
  12. // the dapr sidecar relies on these
  13. await server.start();
  1. # Using dapr run
  2. dapr run --app-id example-sdk --app-port 50051 --app-protocol http -- npm run start
  4. # or, using npm script
  5. npm run start:dapr-http

ℹ️ Note: The app-port is required here, as this is where our server will need to bind to. Dapr will check for the application to bind to this port, before finishing start-up.

Using HTTP (bring your own express webserver)

Instead of using the built-in web server for Dapr sidecar to application communication, you can also bring your own instance. This is helpful in scenarios like when you are building a REST API back-end and want to integrate Dapr directly in it.

Note, this is currently available for express only.

💡 Note: when using a custom web-server, the SDK will configure server properties like max body size, and add new routes to it. The routes are unique on their own to avoid any collisions with your application, but it’s not guaranteed to not collide.

  1. import { DaprServer, CommunicationProtocolEnum } from "@dapr/dapr";
  2. import express from "express";
  4. const myApp = express();
  6. myApp.get("/my-custom-endpoint", (req, res) => {
  7.   res.send({ msg: "My own express app!" });
  8. });
  10. const daprServer = new DaprServer({
  11.       serverHost: "127.0.0.1", // App Host
  12.       serverPort: "50002", // App Port
  13.       serverHttp: myApp,
  14.       clientOptions: {
  15.         daprHost
  16.         daprPort
  17.       }
  18.     });
  20. // Initialize subscriptions before the server starts, the Dapr sidecar uses it.
  21. // This will also initialize the app server itself (removing the need for `app.listen` to be called).
  22. await daprServer.start();

After configuring the above, you can call your custom endpoint as you normally would:

  1. const res = await fetch(`http://127.0.0.1:50002/my-custom-endpoint`);
  2. const json = await res.json();

Using gRPC

Since HTTP is the default, you will have to adapt the communication protocol to use gRPC. You can do this by passing an extra argument to the client or server constructor.

  1. import { DaprServer, CommunicationProtocol } from "@dapr/dapr";
  3. const server = new DaprServer({
  4.   serverHost: appHost,
  5.   serverPort: appPort,
  6.   communicationProtocol: CommunicationProtocolEnum.GRPC,
  7.   clientOptions: {
  8.     daprHost,
  9.     daprPort,
  10.   },
  11. });
  12. // initialize subscribtions, ... before server start
  13. // the dapr sidecar relies on these
  14. await server.start();
  1. # Using dapr run
  2. dapr run --app-id example-sdk --app-port 50051 --app-protocol grpc -- npm run start
  4. # or, using npm script
  5. npm run start:dapr-grpc

ℹ️ Note: The app-port is required here, as this is where our server will need to bind to. Dapr will check for the application to bind to this port, before finishing start-up.

Building blocks

The JavaScript Server SDK allows you to interface with all of the Dapr building blocks focusing on Sidecar to App features.

Invocation API

Listen to an Invocation

  1. import { DaprServer, DaprInvokerCallbackContent } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server "
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const callbackFunction = (data: DaprInvokerCallbackContent) => {
  19.     console.log("Received body: ", data.body);
  20.     console.log("Received metadata: ", data.metadata);
  21.     console.log("Received query: ", data.query);
  22.     console.log("Received headers: ", data.headers); // only available in HTTP
  23.   };
  25.   await server.invoker.listen("hello-world", callbackFunction, { method: HttpMethod.GET });
  27.   // You can now invoke the service with your app id and method "hello-world"
  29.   await server.start();
  30. }
  32. start().catch((e) => {
  33.   console.error(e);
  34.   process.exit(1);
  35. });

For a full guide on service invocation visit How-To: Invoke a service.

PubSub API

Subscribe to messages

Subscribing to messages can be done in several ways to offer flexibility of receiving messages on your topics:

  • Direct subscription through the subscribe method
  • Direct susbcription with options through the subscribeWithOptions method
  • Subscription afterwards through the susbcribeOnEvent method

Each time an event arrives, we pass its body as data and the headers as headers, which can contain properties of the event publisher (e.g., a device ID from IoT Hub)

Dapr requires subscriptions to be set up on startup, but in the JS SDK we allow event handlers to be added afterwards as well, providing you the flexibility of programming.

An example is provided below

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server "
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const pubSubName = "my-pubsub-name";
  19.   const topic = "topic-a";
  21.   // Configure Subscriber for a Topic
  22.   // Method 1: Direct subscription through the `subscribe` method
  23.   await server.pubsub.subscribe(pubSubName, topic, async (data: any, headers: object) =>
  24.     console.log(`Received Data: ${JSON.stringify(data)} with headers: ${JSON.stringify(headers)}`),
  25.   );
  27.   // Method 2: Direct susbcription with options through the `subscribeWithOptions` method
  28.   await server.pubsub.subscribeWithOptions(pubSubName, topic, {
  29.     callback: async (data: any, headers: object) =>
  30.       console.log(`Received Data: ${JSON.stringify(data)} with headers: ${JSON.stringify(headers)}`),
  31.   });
  33.   // Method 3: Subscription afterwards through the `susbcribeOnEvent` method
  34.   // Note: we use default, since if no route was passed (empty options) we utilize "default" as the route name
  35.   await server.pubsub.subscribeWithOptions("pubsub-redis", "topic-options-1", {});
  36.   server.pubsub.subscribeToRoute("pubsub-redis", "topic-options-1", "default", async (data: any, headers: object) => {
  37.     console.log(`Received Data: ${JSON.stringify(data)} with headers: ${JSON.stringify(headers)}`);
  38.   });
  40.   // Start the server
  41.   await server.start();
  42. }

For a full list of state operations visit How-To: Publish & subscribe.

Subscribe with SUCCESS/RETRY/DROP status

Dapr supports status codes for retry logic to specify what should happen after a message gets processed.

⚠️ The JS SDK allows multiple callbacks on the same topic, we handle priority of status on RETRY > DROP > SUCCESS and default to SUCCESS

⚠️ Make sure to configure resiliency in your application to handle RETRY messages

In the JS SDK we support these messages through the DaprPubSubStatusEnum enum. To ensure Dapr will retry we configure a Resiliency policy as well.

components/resiliency.yaml

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Resiliency
  3. metadata:
  4.   name: myresiliency
  5. spec:
  6.   policies:
  7.     retries:
  8.       # Global Retry Policy for Inbound Component operations
  9.       DefaultComponentInboundRetryPolicy:
  10.         policy: constant
  11.         duration: 500ms
  12.         maxRetries: 10
  13.   targets:
  14.     components:
  15.       messagebus:
  16.         inbound:
  17.           retry: DefaultComponentInboundRetryPolicy

src/index.ts

  1. import { DaprServer, DaprPubSubStatusEnum } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server "
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const pubSubName = "my-pubsub-name";
  19.   const topic = "topic-a";
  21.   // Process a message successfully
  22.   await server.pubsub.subscribe(pubSubName, topic, async (data: any, headers: object) => {
  23.     return DaprPubSubStatusEnum.SUCCESS;
  24.   });
  26.   // Retry a message
  27.   // Note: this example will keep on retrying to deliver the message
  28.   // Note 2: each component can have their own retry configuration
  29.   //   e.g., https://docs.dapr.io/reference/components-reference/supported-pubsub/setup-redis-pubsub/
  30.   await server.pubsub.subscribe(pubSubName, topic, async (data: any, headers: object) => {
  31.     return DaprPubSubStatusEnum.RETRY;
  32.   });
  34.   // Drop a message
  35.   await server.pubsub.subscribe(pubSubName, topic, async (data: any, headers: object) => {
  36.     return DaprPubSubStatusEnum.DROP;
  37.   });
  39.   // Start the server
  40.   await server.start();
  41. }

Subscribe to messages rule based

Dapr supports routing messages to different handlers (routes) based on rules.

E.g., you are writing an application that needs to handle messages depending on their “type” with Dapr, you can send them to different routes handlerType1 and handlerType2 with the default route being handlerDefault

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server "
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const pubSubName = "my-pubsub-name";
  19.   const topic = "topic-a";
  21.   // Configure Subscriber for a Topic with rule set
  22.   // Note: the default route and match patterns are optional
  23.   await server.pubsub.subscribe("pubsub-redis", "topic-1", {
  24.     default: "/default",
  25.     rules: [
  26.       {
  27.         match: `event.type == "my-type-1"`,
  28.         path: "/type-1",
  29.       },
  30.       {
  31.         match: `event.type == "my-type-2"`,
  32.         path: "/type-2",
  33.       },
  34.     ],
  35.   });
  37.   // Add handlers for each route
  38.   server.pubsub.subscribeToRoute("pubsub-redis", "topic-1", "default", async (data) => {
  39.     console.log(`Handling Default`);
  40.   });
  41.   server.pubsub.subscribeToRoute("pubsub-redis", "topic-1", "type-1", async (data) => {
  42.     console.log(`Handling Type 1`);
  43.   });
  44.   server.pubsub.subscribeToRoute("pubsub-redis", "topic-1", "type-2", async (data) => {
  45.     console.log(`Handling Type 2`);
  46.   });
  48.   // Start the server
  49.   await server.start();
  50. }

Susbcribe with Wildcards

The popular wildcards * and + are supported (make sure to validate if the pubsub component supports it) and can be subscribed to as follows:

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server "
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const pubSubName = "my-pubsub-name";
  20.   // * Wildcard
  21.   await server.pubsub.subscribe(pubSubName, "/events/*", async (data: any, headers: object) =>
  22.     console.log(`Received Data: ${JSON.stringify(data)}`),
  23.   );
  25.   // + Wildcard
  26.   await server.pubsub.subscribe(pubSubName, "/events/+/temperature", async (data: any, headers: object) =>
  27.     console.log(`Received Data: ${JSON.stringify(data)}`),
  28.   );
  30.   // Start the server
  31.   await server.start();
  32. }

Bulk Subscribe to messages

Bulk Subscription is supported and is available through following API:

  • Bulk subscription through the subscribeBulk method: maxMessagesCount and maxAwaitDurationMs are optional; and if not provided, default values for related components will be used.

While listening for messages, the application receives messages from Dapr in bulk. However, like regular subscribe, the callback function receives a single message at a time, and the user can choose to return a DaprPubSubStatusEnum value to acknowledge successfully, retry, or drop the message. The default behavior is to return a success response.

Please refer this document for more details.

  1. import { DaprServer } from "@dapr/dapr";
  3. const pubSubName = "orderPubSub";
  4. const topic = "topicbulk";
  6. const daprHost = process.env.DAPR_HOST || "127.0.0.1";
  7. const daprHttpPort = process.env.DAPR_HTTP_PORT || "3502";
  8. const serverHost = process.env.SERVER_HOST || "127.0.0.1";
  9. const serverPort = process.env.APP_PORT || 5001;
  11. async function start() {
  12.   const server = new DaprServer({
  13.     serverHost,
  14.     serverPort,
  15.     clientOptions: {
  16.       daprHost,
  17.       daprPort: daprHttpPort,
  18.     },
  19.   });
  21.   // Publish multiple messages to a topic with default config.
  22.   await client.pubsub.subscribeBulk(pubSubName, topic, (data) =>
  23.     console.log("Subscriber received: " + JSON.stringify(data)),
  24.   );
  26.   // Publish multiple messages to a topic with specific maxMessagesCount and maxAwaitDurationMs.
  27.   await client.pubsub.subscribeBulk(
  28.     pubSubName,
  29.     topic,
  30.     (data) => {
  31.       console.log("Subscriber received: " + JSON.stringify(data));
  32.       return DaprPubSubStatusEnum.SUCCESS; // If App doesn't return anything, the default is SUCCESS. App can also return RETRY or DROP based on the incoming message.
  33.     },
  34.     {
  35.       maxMessagesCount: 100,
  36.       maxAwaitDurationMs: 40,
  37.     },
  38.   );
  39. }

Dead Letter Topics

Dapr supports dead letter topic. This means that when a message fails to be processed, it gets sent to a dead letter queue. E.g., when a message fails to be handled on /my-queue it will be sent to /my-queue-failed. E.g., when a message fails to be handled on /my-queue it will be sent to /my-queue-failed.

You can use the following options with subscribeWithOptions method:

  • deadletterTopic: Specify a deadletter topic name (note: if none is provided we create one named deadletter)
  • deadletterCallback: The method to trigger as handler for our deadletter

Implementing Deadletter support in the JS SDK can be done by either

  • Passing the deadletterCallback as an option
  • By subscribing to route manually with subscribeToRoute

An example is provided below

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1"; // Dapr Sidecar Host
  4. const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
  5. const serverHost = "127.0.0.1"; // App Host of this Example Server
  6. const serverPort = "50051"; // App Port of this Example Server "
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const pubSubName = "my-pubsub-name";
  20.   // Method 1 (direct subscribing through subscribeWithOptions)
  21.   await server.pubsub.subscribeWithOptions("pubsub-redis", "topic-options-5", {
  22.     callback: async (data: any) => {
  23.       throw new Error("Triggering Deadletter");
  24.     },
  25.     deadLetterCallback: async (data: any) => {
  26.       console.log("Handling Deadletter message");
  27.     },
  28.   });
  30.   // Method 2 (subscribe afterwards)
  31.   await server.pubsub.subscribeWithOptions("pubsub-redis", "topic-options-1", {
  32.     deadletterTopic: "my-deadletter-topic",
  33.   });
  34.   server.pubsub.subscribeToRoute("pubsub-redis", "topic-options-1", "default", async () => {
  35.     throw new Error("Triggering Deadletter");
  36.   });
  37.   server.pubsub.subscribeToRoute("pubsub-redis", "topic-options-1", "my-deadletter-topic", async () => {
  38.     console.log("Handling Deadletter message");
  39.   });
  41.   // Start server
  42.   await server.start();
  43. }

Bindings API

Receive an Input Binding

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1";
  4. const daprPort = "3500";
  5. const serverHost = "127.0.0.1";
  6. const serverPort = "5051";
  8. async function start() {
  9.   const server = new DaprServer({
  10.     serverHost,
  11.     serverPort,
  12.     clientOptions: {
  13.       daprHost,
  14.       daprPort,
  15.     },
  16.   });
  18.   const bindingName = "my-binding-name";
  20.   const response = await server.binding.receive(bindingName, async (data: any) =>
  21.     console.log(`Got Data: ${JSON.stringify(data)}`),
  22.   );
  24.   await server.start();
  25. }
  27. start().catch((e) => {
  28.   console.error(e);
  29.   process.exit(1);
  30. });

For a full guide on output bindings visit How-To: Use bindings.

Configuration API

💡 The configuration API is currently only available through gRPC

Getting a configuration value

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1";
  4. const daprPort = "3500";
  5. const serverHost = "127.0.0.1";
  6. const serverPort = "5051";
  8. async function start() {
  9.   const client = new DaprClient({
  10.     daprHost,
  11.     daprPort,
  12.     communicationProtocol: CommunicationProtocolEnum.GRPC,
  13.   });
  14.   const config = await client.configuration.get("config-redis", ["myconfigkey1", "myconfigkey2"]);
  15. }
  17. start().catch((e) => {
  18.   console.error(e);
  19.   process.exit(1);
  20. });

Subscribing to Key Changes

  1. import { DaprServer } from "@dapr/dapr";
  3. const daprHost = "127.0.0.1";
  4. const daprPort = "3500";
  5. const serverHost = "127.0.0.1";
  6. const serverPort = "5051";
  8. async function start() {
  9.   const client = new DaprClient({
  10.     daprHost,
  11.     daprPort,
  12.     communicationProtocol: CommunicationProtocolEnum.GRPC,
  13.   });
  14.   const stream = await client.configuration.subscribeWithKeys("config-redis", ["myconfigkey1", "myconfigkey2"], () => {
  15.     // Received a key update
  16.   });
  18.   // When you are ready to stop listening, call the following
  19.   await stream.close();
  20. }
  22. start().catch((e) => {
  23.   console.error(e);
  24.   process.exit(1);
  25. });