cloudevents-router
v3.1.0
Published
Simple typed message router middleware for consuming cloudevents
Downloads
332
Maintainers
Readme
Cloud Events Router
The simplest typed cloudevents routing library for nodejs. Library has a single dependency to cloudevents npm library.
Library does not provide any input validation, just routing and typecasting!
Install
npm install cloudevents-router
Define types
// Hand-code or use external events map
// [type: string]: T
import { MessagePublishedData } from "@google/events/cloud/pubsub/v1/MessagePublishedData";
import { BuildEventData } from "@google/events/cloud/cloudbuild/v1/BuildEventData";
type EventMap = {
"google.cloud.pubsub.topic.v1.messagePublished": MessagePublishedData;
"google.cloud.cloudbuild.build.v1.statusChanged": BuildEventData;
"my.custom.event.v1": {
username: string;
};
};
/*
Google Cloud events are described in cloudevents-router-gcp package
npm install cloudevents-router-gcp
import type { GoogleEvents } from 'cloudevents-router-gcp'
*/
Other known compatible packages include:
- cloudevents-router-gcp - Google Cloud events
- codegen-stackables-webhooks - Stackables Webhooks
Consume events
import { CloudEventsRouter } from "cloudevents-router";
const router = new CloudEventsRouter<EventMap>();
router.on("google.cloud.pubsub.topic.v1.messagePublished", async (event) => {
console.log("PubSub ordering key", event.data.message?.orderingKey);
});
router.on("google.cloud.cloudbuild.build.v1.statusChanged", async (event) => {
console.log("Build images array", event.artifacts?.images);
if (!event.artifacts) {
// Error in handler will return 500 error code to the producer
throw new Error("Artifacts not present");
}
});
router.onUnhandled((event) => {
// This counts as normal consumer for any undefined event
// ... so server will always return 200 status code
// ... if you don't want to acknowledge events you need to throw from this handler
console.log("Unknown event", event);
});
See example for more useful PubSub handling
Connect to http server
Using the @whatwg-node/server server adapter
import { getServerAdapter } from "cloudevents-router";
import http from "http";
const middleware = getServerAdapter(router);
const server = http.createServer(middleware);
server.listen(5000);
If you are using express and want have a specific path for cloudevents processing.
import { getServerAdapter } from "cloudevents-router";
import express from "express";
const app = express();
app.post("/webhooks", getServerAdapter(router));
app.listen(5000);
See @whatwg-node/server for many more integration options.
Return codes from server adapter:
- 200 - OK
- 405 - Method Not Allowed
- 501 - Not Implemented (event not listened, and no onUnhandled listener)
- 500 - Internal Server Error (error during processing)
Manual server configuration
If you are not using a webserver at all or your framework is not supported by ``then you can always manually connect the CloudEventsRouter using theprocess()
method.
See more integration examples at https://github.com/cloudevents/sdk-javascript
import { HTTP } from "cloudevents"
const receivedEvent = HTTP.toEvent({ ... });
await router.process(receivedEvent)
Thats it ...
... happy coding :)