submarine-events

Getting Start

submarine-events is a lightweight, event-driven micro-service framework. It provides a common solution to receive events transported from producer and consume them via RESTful HTTP API. Event producers can send events to submarine-events via Kafka or submarine-events API. The event data must be described in a common format defined by CloudEvents protocol, which allows data exchange between different systems. submarine-events listens to events, then routes them to specific destinations via RESTful HTTP API configured by user.

Features

Event-driven architecture, connecting event producers and consumers in a decoupled fashion
CloudEvents protocol, achieving interoperability across different systems
Dynamic configuration, eliminating the need of redeployment
Sync or async mode, providing flexibility to fit different tasks

How To Use

1.Configure Kafka

submarine-events can receive event via both Kafka and submarine-events API. If you choose Kafka, configure Kafka as following. Otherwise, skip this step.

# /src/main/resources/bootstrap.yml
spring:
  cloud:
    stream:
      default-binder: kafka  
      kafka:
        binder:
          brokers: localhost:9092 #your kafka server address 
      bindings:
        input:
          destination: my_topic #your topic
          group: my_topic_group1 #consumer group of your topic 
          consumer:
            concurrency: 4 #concurrent consumer count, default is 1, less than or equal to partition count
            max-attempts: 5 #max retry count, default is 3
      function: 
        definition: restAPIConsume #function to consume message, already implemented in stream/handler/EventHandler.java

2.Configure Event Adapter Rules

I) Local Event Adapter Rules

# /src/main/resources/bootstrap.yml
event-adapter-rules:
  rule[0]:
    type: Demo #event type
    targetUri: http://localhost:8080/v1/demo/toUpperCase #RESTful HTTP API where event is routed to, here is a demo API implemented in demo/TargetUriDemo.java
    httpMethod: GET #method of RESTful HTTP API
    requestKeyMap: '{"oriReqName1": "convertedReqName1", "oriReqName2": "convertedReqName2"}' #request key map, not required
    responseKeyMap: '{"oriRespName1": "convertedRespName1", "oriRespName2":"convertedRespName2"}' #response key map, not required
  #rule[1]: more rules can be added here

II) Dynamic Event Adapter Rules via Nacos

Event adapter rules can also be configured dynamically in Nacos if available.

a) Configure Nacos

# /src/main/resources/bootstrap.yml
spring:
  application:
    name: submarine-events
  cloud:
    nacos:
      config:
        server-addr: localhost:80 #your nacos server address
        file-extension: yaml

b) Configure Event Adapter Rules in Nacos

# Nacos/submarine-events.yaml
event-adapter-rules:
  rule[0]: ...
  rule[1]: ...
...

3.Send Event

Send an event defined by CloudEvents protocol to submarine-events via 1) the specific Kafka topic you configured or 2) submarine-events API: http://localhost:8080/v1/event/send.

Here is a demo event:

{
  "type":"Demo",
  "data": {
    "oriReqName1":"cat",
    "oriReqName2":"dog"
  },
  "id":"000000001",
  "source":"/event/source"
}

Learn more about CloudEvents.

4.Route event to RESTful HTTP API

submarine-events finds corresponding event adapter rule according to "type":

event-adapter-rules:
  rule[0]:
    type: Demo #event type
    targetUri: http://localhost:8080/v1/demo/toUpperCase #RESTful HTTP API where event is routed to, here is a demo API implemented in demo/TargetUriDemo.java
    httpMethod: GET #method of RESTful HTTP API
    requestKeyMap: '{"oriReqName1": "convertedReqName1", "oriReqName2": "convertedReqName2"}' #request key map, not required
    responseKeyMap: '{"oriRespName1": "convertedRespName1", "oriRespName2":"convertedRespName2"}' #response key map, not required

submarine-events calls http://localhost:8080/v1/demo/toUpperCase?convertedReqName1=cat&convertedReqName2=dog, uri is from targetUri and request parameter is converted from "data" by requestKeyMap, you can get response converted by "responseKeyMap":

{
  "convertedRespName1": "CAT",
  "convertedRespName2": "DOG"
 }

Contributing

First and foremost, thank you! We appreciate that you want to contribute to submarine-events, your time is valuable, and your contributions mean a lot to us. There are many ways to contribute, including the following:

Creating an issue
Updating or correcting documentation
Feature requests
Bug reports

izhimi0706 / submarine-events Goto Github PK