Topics / Subscribers (Pub / Sub)

Less makes it easy to set up topics and subscribers (pub/sub) giving you powerful features by default:

• Publish messages with at-least-once delivery guarantees.
• Failed messages are retained by Less in order to be processed again later.
• Failed messages to not block the processing of subsequent messages.
• Easily implement the Fanout arquitectural pattern.
• Publish and subscribe to topics from different Less applications securely.
• Easily build event-driven microservices.
• Generated Topics REST API allowing you to publish messages from anywhere.
• Easily integrate with your existing systems.
• Easily scale and distribute your workloads.

Create Topics

In order to create topics (publishers) and subscribers you need to create a topics folder in less. Each folder inside of topics is your topic.

mkdir -p less/topics

Let's create a user_created topic:

mkdir less/topics/user_created

Create Topic Subscribers

A topic can have several subscribers. Just add them to your topic's folder.

Let's create some example subscribers to the user_created event:

mkdir less/topics/user_created/send_welcome_email
mkdir less/topics/user_created/send_to_analytics

Node.js

touch less/topics/user_created/send_welcome_email/index.js

less/topics/user_created/send_welcome_email/index.js

exports.process = async (user) => {
  console.log(`Sending a welcome email to ${user.email}`);
};

less/topics/user_created/send_to_analytics/index.js

exports.process = async (user) => {
  console.log(`Sending user "${user.name}" to analytics`);
};

Python

touch less/topics/user_created/send_welcome_email/__init__.py

less/topics/user_created/send_welcome_email/__init__.py

def process(user):
  print(f"Sending a welcome email to {user['email']}")

less/topics/user_created/send_to_analytics/__init__.py

def process(user):
  print(f"Sending user \"{user['name']}\" to analytics")

Send Messages to Topics

Less offers 2 ways to send messages to topics:

1. Using the topics module in the Less SDK.
2. Using the Less Topics REST API.

Send Messages Using the SDK

Use the Less topics module to send messages to all of a topic's subscribers.

Node.js

const { topics } = require('@chuva.io/less');

await topics.user_created.publish(message);

Python

Import topics from less to send messages to all subscribers.

from less import topics

topics.user_created.publish(message)

---

Let's create a POST /users route that will send the user payload to the user_created topic.

Node.js

touch less/apis/demo/users/post.js

less/apis/demo/users/post.js

const { topics } = require('@chuva.io/less');

exports.process = async (request, response) => {
  // Get the user payload from the body.
  const user = JSON.parse(request.body);
  
  // Pretend to create a new user.
  const new_user = { id: 'my-fake-id', ...user };

  // Publish the new user to the `user_created` topic.
  await topics.user_created.publish(new_user);
};

Python

touch less/apis/demo/users/post.py

less/apis/demo/users/post.py

import json

def process(request, response):
  body = json.loads(request['body'])
  user = body['user']
  user['id'] = 'my-fake-id'
  topics.user_created.publish(user)

Less REST API Documentation

Read the Less REST API documentation to learn more.

You can now deploy and call your POST /users route and confirm that your subscribers are receiving the messages:

1. Deploy your changes.

npx

npx @chuva.io/less-cli deploy my-less-project

npm

less-cli deploy my-less-project

yarn

less-cli deploy my-less-project

2. Execute your POST /users request.

curl -X POST -d '{"name": "Mayra Andrade", "email": "mayra.andrade@chuva.io"}' [BASE_URL]/users

3. Check your subscriber logs and confirm your messages were received.

npx

npx @chuva.io/less-cli log --project my-less-project --path topics/user_created/send_welcome_email
npx @chuva.io/less-cli log --project my-less-project --path topics/user_created/send_to_analytics

npm

npm i -g @chuva.io/less-cli
less-cli log --project my-less-project --path topics/user_created/send_welcome_email
less-cli log --project my-less-project --path topics/user_created/send_to_analytics

yarn

yarn global add @chuva.io/less-cli
less-cli log --project my-less-project --path topics/user_created/send_welcome_email
less-cli log --project my-less-project --path topics/user_created/send_to_analytics

Less Logs Documentation

Read the Less logs documentation to learn more.

Send Messages Using the REST API

When using the Topics feature, Less automatically creates a Topics REST API for you. You can use the API to publish messages to your Topics from anywhere, making it easy to integrate Less with your existing systems.

1. Deploy your topics.

npx

npx @chuva.io/less-cli deploy my-less-project

npm

less-cli deploy my-less-project

yarn

less-cli deploy my-less-project

2. Retrieve your Topics API URL from your deployment output:

[less-cli] Deployment complete ✅
[less-cli] Resources
[less-cli]   - API URLs
[less-cli]     - Topics: https://[PROJECT_NAME]-topics.api.eu-0.a83b464c9.less.chuva.cv
[less-cli] 🇨🇻

3. Send a message to your user_created topic using the POST /topics/{topic_name} route.

curl -X POST -d '{"name": "Mayra Andrade", "email": "mayra.andrade@chuva.io"}' [TOPICS_BASE_URL]/topics/user_created

4. Check your subscriber logs and confirm your messages were received.

npx

npx @chuva.io/less-cli log --project my-less-project --path topics/user_created/send_welcome_email
npx @chuva.io/less-cli log --project my-less-project --path topics/user_created/send_to_analytics

npm

npm i -g @chuva.io/less-cli
less-cli log --project my-less-project --path topics/user_created/send_welcome_email
less-cli log --project my-less-project --path topics/user_created/send_to_analytics

yarn

yarn global add @chuva.io/less-cli
less-cli log --project my-less-project --path topics/user_created/send_welcome_email
less-cli log --project my-less-project --path topics/user_created/send_to_analytics

  POST /topics/{topic_id}

Handling Failing Messages

Less automatically retains failed messages and tries to process them again later.

In order to see this in action we can force a crash in one of our subscribers:

Node.js

touch less/topics/user_created/send_welcome_email/index.js

less/topics/user_created/send_welcome_email/index.js

exports.process = async (user) => {
  throw new Error('This subscriber will fail to process messages.');
  console.log(`Sending a welcome email to ${user.email}`);
};

Python

touch less/topics/user_created/send_welcome_email/__init__.py

less/topics/user_created/send_welcome_email/__init__.py

def process(user):
  raise SyntaxError('This subscriber will fail to process messages.')
  print(f"Sending a welcome email to {user['email']}")

Deploy the change and publish another message to your topic. You will notice that while the user_create/send_welcome_email subscriber is failing, the user_create/send_to_analytics subscriber is working just fine.

Once we fix the crash and deploy we will notice that the previously failing message will be processed successfully.

Cross-Application Topics

Less also makes it easy to subscribe to topics from different Less applications. This makes it easier than ever to build distributed, fault-tolerant, event-driven microservices.

Subscribe to External Topics

1. Create an external_topics folder inside of less to set up your external app connections.

mkdir -p less/external_topics

2. Add the projects you want to connect to to the external_topics folder.

mkdir less/external_topics/my_less_project

3. Add the topic want to subscribe to to the respective project folder.

mkdir less/external_topics/my_less_project/user_created

4. Create your subscriber

Node.js

touch less/external_topics/my_less_project/user_created/index.js

less/external_topics/my_less_project/user_created/notify_friends/index.js

exports.process = async (user) => {
  console.log('Telling all your friends that you have joined...');
};

5. Configure your project connection. Add the folder name to the less.config file as an environment variable. The value of this variable should match the name of the application you want to connect to.

env_vars:
  - MY_LESS_PROJECT

Export the name of the application (deployment) you want to connect to. This allows you to point your application to different deployments (development, stage, production, etc.).

export MY_LESS_PROJECT=my_less_project

Less Environment Variables Documentation

Read the Less environment variables documentation to learn more.

In contrast to topics in the less/topics folder, we are not creating topics here. In this case we are simply connecting to a topic from the specified application.

You can now deploy your new application. Publish messages to the first application and verify they are received in your new external subscriber.