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 middleware
import { getMiddleware } from "cloudevents-router"
import http from "http"
const middleware = getMiddleware(router, { path: '/' })
const server = http.createServer(middleware)
server.listen(5000);
For express you can use the middleware without path configuration
import { getMiddleware } from "cloudevents-router"
import express from "express"
const app = express()
app.post('/webhooks', getMiddleware(router))
app.listen(5000)
Return codes from middleware:
- 200 - OK
- 405 - Method Not Allowed (not POST request, and not express)
- 404 - Not Found (path defined and not matching, and not express)
- 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 or your framework does not use middleware then you can always manually connect the CloudEventsRouter using the process()
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 :)