EventBus Service

The EventBus Service is a messaging system that facilitates communication between different blocklets and the core system. It employs a publish-subscribe pattern, allowing components to broadcast and receive events without being directly coupled. This enables a modular architecture where blocklets can react to changes and actions occurring elsewhere in the system.

For instance, a shopping blocklet could publish an order.created event. An inventory blocklet could subscribe to this event to update stock levels, while a notification blocklet could subscribe to it to send an order confirmation email to the user.

Architecture Overview#

The service operates around a central message bus. Blocklets can assume the role of a publisher, a subscriber, or both.

1. Publisher: A blocklet that emits an event to the EventBus.
2. Subscriber: A blocklet that listens for specific events on the EventBus.
3. EventBus: The intermediary that receives events from publishers and forwards them to all relevant subscribers.

A blocklet cannot subscribe to its own events, which is a built-in mechanism to prevent infinite loops.

Defining Events#

To publish an event, it must first be declared in the blocklet's blocklet.yml configuration file. This declaration acts as a formal part of the blocklet's interface.

events:
  - type: kitchen.full
    description: dummy event from kitchen sink blocklet
  - type: kitchen.empty
    description: dummy event from kitchen sink blocklet

Naming Conventions#

• Format: It is recommended to follow a noun.verb pattern, such as post.published or user.loggedIn.
• Uniqueness: The type of each event must be unique within a single blocklet.
• Reserved Namespace: Event types cannot begin with blocklet., as this prefix is reserved for system events.
• Description: A clear and informative description for each event is mandatory.

Publishing Events#

Events are published using the EventBus.publish method provided by the Blocklet SDK. The event must be one of the types defined in the blocklet's blocklet.yml.

const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.publish('kitchen.full', {
  id: '123', // optional, default is a random uuid
  time: new Date().toISOString(), // optional, default is current time
  data: { object: { message: 'Hello, world!' } },
})
  .then(() => {
    console.log('Event published');
  })
  .catch((err) => {
    console.error('Failed to publish event', err);
  });

The second argument to the publish function is an object containing the event payload. This payload can include an id, a time, and a data field for any relevant information.

Subscribing to Events#

To receive events, a blocklet can use the EventBus.subscribe method. This method registers a callback function that is executed for each incoming event.

const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.subscribe((event) => {
  console.log('received event from eventbus', event);
});

The subscriber will receive events from all other blocklets and the core system but will be automatically filtered from receiving its own published events.

Discovering Events#

A list of all available events within the system can be discovered by querying a well-known endpoint. This endpoint returns a JSON object that details all registered events from both the core system and all installed blocklets. This discovery mechanism is crucial for enabling interoperability between blocklets.

You can retrieve the list of events by making a GET request to /.well-known/service/openevent.json on your blocklet's domain.

❯ curl -s https://<your-blocklet-url>/.well-known/service/openevent.json | jq

Example Response#

The JSON response includes a list of sources (the blocklets or system components that publish events) and a list of events.

{
  "openevent": "1.0.0",
  "info": {
    "description": "I can change this after elevated, great! haha"
  },
  "sources": [
    {
      "did": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs",
      "description": "I can change this after elevated, great! haha",
      "version": "1.0.0",
      "logo": "https://bbqartjsky2iiebu2noxsg6gn7nf7ezacguwmx6q6ci.did.abtnet.io/.well-known/service/blocklet/logo"
    }
  ],
  "events": [
    {
      "type": "blocklet.user.added",
      "description": "When a new user has onboarded, will receive the user info object",
      "source": "zNKYyCsfQASyGp5Gcz3vmkRyLM73cRG13fVs"
    },
    {
      "type": "kitchen.full",
      "description": "dummy event from kitchen sink blocklet",
      "source": "z8ia22AX1PovjTi1YQw8ChgsbeVExYsX4dPFt"
    }
  ]

System Events#

The Blocklet Service core publishes a set of standard events related to the user lifecycle. Blocklets can subscribe to these to trigger workflows based on user activity.

Event Type	Description
blocklet.user.added	Triggered when a new user is onboarded. The event payload contains the user's information object.
blocklet.user.updated	Triggered when a user's session is updated, such as during login. The payload contains the user's information.
blocklet.user.removed	Triggered when a user is removed from the system. The payload contains the user's DID.
blocklet.user.profile.updated	Triggered when a user updates their profile information (e.g., name, avatar).
blocklet.user.permission.updated	Triggered when a user's permissions or roles are modified.

Summary#

The EventBus Service is a fundamental component for building decoupled, event-driven applications with Blocklets. By defining, publishing, and subscribing to events, developers can create complex workflows and interactions between different parts of the system in a scalable and maintainable way. For further details on other services, please see the related documents.