Skip to content

Commit 4348c14

Browse files
iamrishavkumarUmadevi-Kapu
iamrishavkumar
authored and
Umadevi-Kapu
committed
Documentation for REMReM publish in Opensource. (#185)
1 parent ca849b9 commit 4348c14

File tree

10 files changed

+852
-9
lines changed

10 files changed

+852
-9
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 2.0.12
2+
- Added documentation for REMReM publish in master branch.
3+
- Uplifted the eiffel-remrem-semantics from 2.0.8 to 2.0.9.
4+
15
## 2.0.11
26
- Uplifted eiffel-remrem-semantics version from 2.0.7 to 2.0.8.
37

‎README.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,6 @@
2525

2626
REMReM Publish is a microservice allowing sending of messages to a topic based exchange on a RabbitMQ Server. It has endpoints that must be called as a relative links. Further documentation is provided at the following link: [https://eiffel-community.github.io/eiffel-remrem-publish](https://eiffel-community.github.io/eiffel-remrem-publish)
2727

28-
# Documentation
29-
30-
1. [**Running RemRem-Publish service**](wiki/markdown/running-remrem-publish.md)
31-
- [**Run in Docker**](wiki/markdown/docker.md)
32-
- [**Configuration**](wiki/markdown/configuration.md)
33-
34-
3528
# About this repository
3629
The contents of this repository are licensed under the [Apache License 2.0](./LICENSE).
3730

@@ -41,3 +34,22 @@ To get involved, please see [Code of Conduct](./CODE_OF_CONDUCT.md) and [contrib
4134
This repository forms part of the Eiffel Community. Eiffel is a protocol for technology agnostic machine-to-machine communication in continuous integration and delivery pipelines, aimed at securing scalability, flexibility and traceability. Eiffel is based on the concept of decentralized real time messaging, both to drive the continuous integration and delivery system and to document it.
4235

4336
Visit [Eiffel Community](https://eiffel-community.github.io) to get started and get involved.
37+
38+
# Documentation
39+
40+
1. [**Eiffel-RemRem-publish**](wiki/markdown/index.md)
41+
- [**Introduction**](wiki/markdown/index.md#Introduction)
42+
- [**Pre-requisites**](wiki/markdown/index.md#Pre-requisites)
43+
- [**Components**](wiki/markdown/index.md#Components)
44+
45+
2. [**Installation**](wiki/markdown/installation.md)
46+
47+
3. [**Running RemRem-Publish service**](wiki/markdown/running-remrem-publish.md)
48+
- [**Run in Docker**](wiki/markdown/docker.md)
49+
- [**Configuration**](wiki/markdown/configuration.md)
50+
51+
4. [**Usage**](wiki/markdown/usage.md)
52+
- [**CLI Usage**](wiki/markdown/usage/cli.md)
53+
- [**Service Usage**](wiki/markdown/usage/service.md)
54+
55+
5. [**Logging**](wiki/markdown/logging.md)

‎pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@
99
<version>2.0.2</version>
1010
</parent>
1111
<properties>
12-
<eiffel-remrem-publish.version>2.0.11</eiffel-remrem-publish.version>
12+
<eiffel-remrem-publish.version>2.0.12</eiffel-remrem-publish.version>
1313
<eiffel-remrem-shared.version>2.0.2</eiffel-remrem-shared.version>
14-
<eiffel-remrem-semantics.version>2.0.8</eiffel-remrem-semantics.version>
14+
<eiffel-remrem-semantics.version>2.0.9</eiffel-remrem-semantics.version>
1515
</properties>
1616
<artifactId>eiffel-remrem-publish</artifactId>
1717
<version>${eiffel-remrem-publish.version}</version>

‎wiki/markdown/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
## Introduction
2+
3+
REMReM (**REST Mailbox for Registered Messages**) is a set of tools that can be used to generate validated Eiffel messages and publish them on a RabbitMQ message bus. They can be run as micro services or as stand-alone CLI versions. For more details on the micro services and the REMReM design, see [Eiffel REMReM](https://github.com/eiffel-community/eiffel-remrem).
4+
5+
Eiffel REMReM Publish is a tool that can be used to publish Eiffel messages on a RabbitMQ message bus.
6+
7+
## Pre-requisites
8+
9+
* JDK 8
10+
* Tomcat 8
11+
* RabbitMQ Server 3.6.x
12+
13+
For supporting latest features, Eiffel REMReM Publish should use the latest version of [Eiffel REMReM Semantics](https://github.com/eiffel-community/eiffel-remrem-semantics).
14+
15+
## Components
16+
17+
* REMReM Publish CLI (Command Line Interface)
18+
* REMReM Publish Service

‎wiki/markdown/installation.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Installation
2+
3+
Eiffel REMReM Publish is maven project and can be built by executing following command:
4+
5+
```
6+
mvn clean install
7+
```
8+
9+
Binary is released via [jitPack](https://jitpack.io/#eiffel-community/eiffel-remrem-publish).
10+
11+
The latest REMReM Publish CLI binary can be downloaded via [publish-cli.jar](https://jitpack.io/#eiffel-community/eiffel-remrem-publish).
12+
13+
The latest REMReM Publish Service binary can be downloaded via [publish-service.war](https://jitpack.io/#eiffel-community/eiffel-remrem-publish).

‎wiki/markdown/logging.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
## Logging
2+
REMReM Publish application logging is implemented using the logback-classic. It requires user to configure the logback.xml file.
3+
When used without logback.xml log messages will look as below:
4+
5+
```
6+
%PARSER_ERROR[wEx]%PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr]
7+
8+
%PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr]
9+
```
10+
11+
To configure the logback.xml file use -Dlogging.config=path/logback.xml
12+
13+
To get info about logback configurations see [here](https://logback.qos.ch/manual/configuration.html).
14+
15+
To get sample logback.xml to use see [here](https://eiffel-community.github.io/eiffel-remrem-publish/logback/logback-sample.xml).

‎wiki/markdown/statusCodes.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# Status Codes
2+
The response generated will have internal status codes for each and every event based on the input JSON provided.
3+
4+
Status codes are generated according to the below tables.
5+
6+
## Internal status codes
7+
8+
Below is the status codes:
9+
10+
| Status code | Result | Message | Comment |
11+
|-------------|-------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
12+
| 200 | SUCCESS | Event sent successfully | Is returned if the request is completed successfully. |
13+
| 207 | Multi-Status | | Is returned if we have a mix of internal status codes. Eg: publish of few events was successful and few events was a failure. In case of multiple events in the body JSON, if a event is given internal status code of 400 or 500 rest events will not be published and will be given a internal status code of 503, which will result in overall HTTP response code of 207. |
14+
| 400 | Bad Request | Invalid event content, client need to fix problem in event before submitting again. | Is returned if the request body JSON is malformed. Eg: unable to parse the body JSON. |
15+
| 404 | RabbitMQ properties not found | RabbitMQ properties not configured for the protocol <protocol> | Is returned if RabbitMQ message broker properties are not found for the protocol used by event. |
16+
| 500 | Internal Server Error | RabbitMQ is down. Please try later | Is returned if RabbitMQ is down. |
17+
| | | Could not prepare Routing key to publish message. | Is returned if could not prepare routing key to publish the eiffel event. |
18+
| 503 | Service Unavailable | Please check previous event and try again later | Is returned if there is a failure in publishing previous event with status code 400, 404 or 500. |
19+
20+
### Status codes explanation
21+
22+
**200 OK**
23+
24+
All the events are sent successfully.
25+
26+
```
27+
[
28+
{
29+
"id": "9cdd0f68-df85-44b0-88bd-fc4163ac90a0",
30+
"status_code": 200,
31+
"result": "SUCCESS",
32+
"message": "Event sent successfully"
33+
},
34+
{
35+
"id": "9cdd0f68-df85-44b0-88bd-fc4163ac90a1",
36+
"status_code": 200,
37+
"result": "SUCCESS",
38+
"message": "Event sent successfully"
39+
}
40+
]
41+
```
42+
43+
**207 Multi-Status**
44+
45+
Events are having different internal status codes.
46+
47+
```
48+
[
49+
{
50+
"id": "9cdd0f68-df85-44b0-88bd-fc4163ac90a0",
51+
"status_code": 200,
52+
"result": "SUCCESS",
53+
"message": "Event sent successfully"
54+
},
55+
{
56+
"status_code": 400,
57+
"result": "Bad Request",
58+
"message": "Invalid event content, client need to fix problem in event before submitting again"
59+
}
60+
]
61+
```
62+
63+
**400 Bad Request**
64+
65+
The input JSON is malformed.
66+
67+
```
68+
[
69+
{
70+
"status_code": 400,
71+
"result": "Bad Request",
72+
"message": "Invalid event content, client need to fix problem in event before submitting again"
73+
}
74+
]
75+
```
76+
77+
**404 Not Found**
78+
79+
RabbitMQ properties not configured in tomcat/conf/config.properties file for the protocol.
80+
81+
```
82+
[
83+
{
84+
"status_code": 404,
85+
"result": "RabbitMQ properties not found",
86+
"message": "RabbitMQ properties not configured for the protocol <protocol>"
87+
}
88+
]
89+
```
90+
91+
**500 Internal Server Error**
92+
93+
Cannot prepare routing key.
94+
95+
```
96+
[
97+
{
98+
"status_code": 500,
99+
"result": "Internal Server Error",
100+
"message": "Could not prepare Routing key to publish message"
101+
}
102+
]
103+
```
104+
105+
Event is failed to send because of internal server error.
106+
107+
```
108+
[
109+
{
110+
"id": "9cdd0f68-df85-44b0-88bd-fc4163ac90a0",
111+
"status_code": 500,
112+
"result": "Internal Server Error",
113+
"message": "RabbitMQ is down. Please try later"
114+
}
115+
]
116+
```
117+
118+
**503 Service Unavailable**
119+
120+
Event will have this status code when the previous event is failed to send.
121+
122+
For example, consider you have 5 events: **E1<-E2<-E3<-E4<-E5**
123+
You send them all to publish in a batch command.
124+
**E1** and **E2** are sent successfully **(200 OK)**.
125+
**E3** is malformed **(400 Bad Request)**.
126+
If we send **E4** and **E5** we will have a broken chain so that is not a good option.
127+
In this case we should skip sending **E4** and **E5** and have status code **503** for those.
128+
129+
```
130+
[
131+
{
132+
"id": "9cdd0f68-df85-44b0-88bd-fc4163ac90a0",
133+
"status_code": 200,
134+
"result": "SUCCESS",
135+
"message": "Event sent successfully"
136+
},
137+
{
138+
"id": "9cdd0f68-df85-44b0-88bd-fc4163ac90a1",
139+
"status_code": 200,
140+
"result": "SUCCESS",
141+
"message": "Event sent successfully"
142+
},
143+
{
144+
"status_code": 400,
145+
"result": "Bad Request",
146+
"message": "Invalid event content, client need to fix problem in event before submitting again"
147+
},
148+
{
149+
"status_code": 503,
150+
"result": "Service Unavailable",
151+
"message": "Please check previous event and try again later"
152+
},
153+
{
154+
"status_code": 503,
155+
"result": "Service Unavailable",
156+
"message": "Please check previous event and try again later"
157+
}
158+
]
159+
```
160+
161+
**NOTE:** you can open the RabbitMQ's management console and find these messages in a queue.
162+
163+
## Status codes related to failures in Eiffel REMReM Generate Service
164+
165+
These response can be generated only when `/generateAndPublish` endpoint is used.
166+
167+
| Status code | Result | Message | Comment |
168+
|-------------|-----------------------|-----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
169+
| 400 | Bad Request | Malformed JSON or incorrect type of event | Is returned if the request body JSON is malformed or entered incorrect type of event. |
170+
| 401 | Unauthorized | Unauthorized. Please, check if LDAP for REMReM Generate Service is disabled | Is returned if LDAP for REMReM Generate Service is enabled and REMReM Generate Publish have not access to it. |
171+
| 406 | Not Acceptable | No event id found with ERLookup properties | Is returned if no event id fetched from configured event repository in REMReM generate. |
172+
| 417 | Expectation Failed | Multiple event ids found with ERLookup properties | Is returned if multiple event ids fetched from configured event repository in REMReM generate. |
173+
| 500 | Internal Server Error | Internal server error in Generate Service | Is returned if REMReM Generate Service is not started or in case of others internal errors in REMReM Generate Service. |
174+
| 503 | Service Unavailable | Message protocol is invalid | Is returned if there is no such message protocol loaded. |
175+
176+
### Status codes explanation
177+
178+
**400 Bad Request**
179+
180+
The input JSON is malformed or entered incorrect type of event.
181+
182+
```
183+
[
184+
{
185+
"status_code": 400,
186+
"result": "FAIL",
187+
"message": "Malformed JSON or incorrect type of event"
188+
}
189+
]
190+
```
191+
192+
**401 Unauthorized**
193+
194+
LDAP for REMReM Generate Service is enabled and REMReM Generate Publish have not access to it.
195+
196+
```
197+
[
198+
{
199+
"status_code": 401,
200+
"result": "FAIL",
201+
"message": "Unauthorized. Please, check if LDAP for REMReM Generate Service is disabled"
202+
}
203+
]
204+
```
205+
206+
**406 Not Acceptable**
207+
208+
The Lookup properties with no event id fetched from configured event repository in generate , REMReM fails to generate.
209+
210+
```
211+
[
212+
{
213+
"status_code": 406,
214+
"result": "FAIL",
215+
"message": "No event id found with ERLookup properties"
216+
}
217+
]
218+
```
219+
220+
**417 Expectation Failed**
221+
The Lookup properties with multiple event ids fetched from configured event repository in generate , REMReM fails to generate.
222+
223+
```
224+
[
225+
{
226+
"status_code": 417,
227+
"result": "FAIL",
228+
"message": "Multiple event ids found with ERLookup properties"
229+
}
230+
]
231+
```
232+
233+
**500 Internal Server Error**
234+
235+
REMReM Generate Service is not started or in case of others internal errors in REMReM Generate Service.
236+
237+
```
238+
[
239+
{
240+
"status_code": 500,
241+
"result": "FAIL",
242+
"message": "Internal server error in Generate Service"
243+
}
244+
]
245+
```
246+
247+
**503 Service Unavailable**
248+
249+
There is no such message protocol loaded..
250+
251+
```
252+
[
253+
{
254+
"status_code": 503,
255+
"result": "FAIL",
256+
"message": "Message protocol is invalid"
257+
}
258+
]
259+
```

‎wiki/markdown/usage.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## Usage
2+
To get information about configuration and usage of REMReM Publish CLI see [here](../markdown/usage/cli.md).
3+
4+
To get information about configuration and usage of REMReM Publish Service see [here](../markdown/usage/service.md).
5+
6+
To get information about internal status codes see [here](statusCodes.md).

0 commit comments

Comments
 (0)