Skip to content

Commit b01965a

Browse files
samarpan-bsamarpan-b
authored
Merge pull request #38 from sourcefuse/techdocs-added
techdocs added
2 parents c6b27d8 + 92ef320 commit b01965a

File tree

3 files changed

+187
-0
lines changed

3 files changed

+187
-0
lines changed

‎catalog-info.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ metadata:
44
name: loopback4-kafka-client
55
annotations:
66
github.com/project-slug: sourcefuse/loopback4-kafka-client
7+
backstage.io/techdocs-ref: dir:.
78
namespace: arc
89
description: A Kafka Client for Loopback4 built on top of KafkaJS.
910
tags:

‎docs/index.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
<a href="https://sourcefuse.github.io/arc-docs/arc-api-docs" target="_blank"><img src="https://github.com/sourcefuse/loopback4-microservice-catalog/blob/master/docs/assets/logo-dark-bg.png?raw=true" alt="ARC By SourceFuse logo" title="ARC By SourceFuse" align="right" width="150" /></a>
2+
3+
# [loopback4-kafka-client](https://github.com/sourcefuse/loopback4-kafka-client)
4+
5+
<p align="left">
6+
<a href="https://www.npmjs.com/package/loopback4-kafka-client">
7+
<img src="https://img.shields.io/npm/v/loopback4-kafka-client.svg" alt="npm version" />
8+
</a>
9+
<a href="https://github.com/sourcefuse/loopback4-kafka-client/graphs/contributors" target="_blank">
10+
<img alt="GitHub contributors" src="https://img.shields.io/github/contributors/sourcefuse/loopback4-kafka-client">
11+
</a>
12+
<a href="https://www.npmjs.com/package/loopback4-kafka-client" target="_blank">
13+
<img alt="downloads" src="https://img.shields.io/npm/dw/loopback4-kafka-client.svg">
14+
</a>
15+
<a href="https://github.com/sourcefuse/loopback4-kafka-client/blob/master/LICENSE">
16+
<img src="https://img.shields.io/github/license/sourcefuse/loopback4-kafka-client.svg" alt="License" />
17+
</a>
18+
<a href="https://loopback.io/" target="_blank">
19+
<img alt="Powered By LoopBack 4" src="https://img.shields.io/badge/Powered%20by-LoopBack 4-brightgreen" />
20+
</a>
21+
</p>
22+
23+
24+
## Overview
25+
26+
A Kafka Client for Loopback4 built on top of [KafkaJS](https://kafka.js.org/).
27+
28+
## Installation
29+
30+
Install KafkaConnectorComponent using `npm`;
31+
32+
```sh
33+
$ [npm install | yarn add] loopback4-kafka-client
34+
```
35+
36+
## Basic Use
37+
38+
Configure and load KafkaConnectorComponent in the application constructor
39+
as shown below.
40+
41+
```ts
42+
import {
43+
KafkaClientBindings,
44+
KafkaClientComponent,
45+
KafkaClientOptions,
46+
} from 'loopback4-kafka-client';
47+
// ...
48+
export class MyApplication extends BootMixin(
49+
ServiceMixin(RepositoryMixin(RestApplication)),
50+
) {
51+
constructor(options: ApplicationConfig = {}) {
52+
this.configure<KafkaClientOptions>(KafkaClientBindings.Component).to({
53+
initObservers: true, // if you want to init consumer lifeCycleObserver
54+
topics: [Topics.First], // if you want to use producers for given topics
55+
connection: {
56+
// refer https://kafka.js.org/docs/configuration
57+
brokers: [process.env.KAFKA_SERVER ?? ''],
58+
},
59+
});
60+
this.bind(KafkaClientBindings.ProducerConfiguration).to({
61+
// your producer config
62+
// refer https://kafka.js.org/docs/producing#options
63+
});
64+
this.bind(KafkaClientBindings.ConsumerConfiguration).to({
65+
// refer https://kafka.js.org/docs/consuming#options
66+
groupId: process.env.KAFKA_CONSUMER_GROUP,
67+
});
68+
69+
this.component(KafkaClientComponent);
70+
// ...
71+
}
72+
// ...
73+
}
74+
```
75+
76+
#### Producer and Consumer
77+
78+
### Stream
79+
80+
Producers and Consumers work on a `Stream` which defines the topic and events used by the application. You can implement the `IStreamDefinition` to create your own stream class.
81+
82+
##### Example
83+
84+
```ts
85+
export class TestStream implements IStreamDefinition {
86+
topic = Topics.First;
87+
messages: {
88+
// [<event type key from enum>] : <event type or interface>
89+
[Events.start]: StartEvent;
90+
[Events.stop]: StopEvent;
91+
};
92+
}
93+
```
94+
95+
### Consumer
96+
97+
A Consumer is a [`loopback extension`](https://loopback.io/doc/en/lb4/Extension-point-and-extensions.html) that is used by the [`KafkaConsumerService`](./src/services/kafka-consumer.service.ts) to initialize consumers. It must implement the `IConsumer` interface and should be using the `@consumer()` decorator. If you want the consumers to start at the start of your application, you should pass the `initObservers` config to the Component configuration.
98+
99+
##### Example
100+
101+
```ts
102+
// application.ts
103+
this.configure(KafkaConnectorComponentBindings.COMPONENT).to({
104+
...
105+
initObservers: true
106+
...
107+
});
108+
```
109+
110+
```ts
111+
// start.consumer.ts
112+
@consumer<TestStream, Events.start>()
113+
export class StartConsumer implements IConsumer<TestStream, Events.start> {
114+
constructor(
115+
@inject('test.handler.start')
116+
public handler: StreamHandler<TestStream, Events.start>,
117+
) {}
118+
topic: Topics.First = Topics.First;
119+
event: Events.start = Events.start;
120+
// you can write the handler as a method
121+
handler(payload: StartEvent) {
122+
console.log(payload);
123+
}
124+
}
125+
```
126+
127+
If you want to write a shared handler for different events, you can use the `eventHandlerKey` to bind a handler in the application -
128+
129+
```ts
130+
// application.ts
131+
this.bind(eventHandlerKey(Events.Start)).to((payload: StartEvent) => {
132+
console.log(payload);
133+
});
134+
this.bind(eventHandlerKey<TestStream, Events.Stop>(Events.Stop)).toProvider(
135+
CustomEventHandlerProvider,
136+
);
137+
```
138+
139+
and then you can use the handler using the `@eventHandler` decorator -
140+
141+
```ts
142+
// start.consumer.ts
143+
@consumer<TestStream, Events.start>()
144+
export class StartConsumer implements IConsumer<TestStream, Events.start> {
145+
constructor(
146+
@eventHandler<TestStream>(Events.Start)
147+
public handler: StreamHandler<TestStream, Events.start>,
148+
) {}
149+
topic: Topics.First = Topics.First;
150+
event: Events.start = Events.start;
151+
}
152+
```
153+
154+
### Producer
155+
156+
A Producer is a loopback service for producing message for a particular topic, you can inject a producer using the `@producer(TOPIC_NAME)` decorator.
157+
Note: The topic name passed to decorator must be first configured in the Component configuration's topic property -
158+
159+
#### Example
160+
161+
```ts
162+
// application.ts
163+
...
164+
this.configure(KafkaConnectorComponentBindings.COMPONENT).to({
165+
...
166+
topics: [Topics.First],
167+
...
168+
});
169+
...
170+
// test.service.ts
171+
...
172+
class TestService {
173+
constructor(
174+
@producer(Topics.First)
175+
private producer: Producer<TestStream>
176+
) {}
177+
}
178+
```

‎mkdocs.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
site_name: loopback4-kafka-client
2+
site_description: loopback4-kafka-client
3+
4+
nav:
5+
- Introduction: index.md
6+
7+
plugins:
8+
- techdocs-core

0 commit comments

Comments
 (0)